esp-idf/docs/en/api-reference/protocols/esp_https_server.rst

HTTPS Server
============
:link_to_translation:`zh_CN:[中文]`

Overview
--------

This component is built on top of :doc:`esp_http_server`. The HTTPS server takes advantage of hook registration functions in the regular HTTP server to provide callback function for SSL session.

All documentation for :doc:`esp_http_server` applies also to a server you create this way.

Used APIs
---------

The following APIs of :doc:`esp_http_server` should not be used with :doc:`esp_https_server`, as they are used internally to handle secure sessions and to maintain internal state:

* "send", "receive" and "pending" callback registration functions - secure socket handling

  * :cpp:func:`httpd_sess_set_send_override`
  * :cpp:func:`httpd_sess_set_recv_override`
  * :cpp:func:`httpd_sess_set_pending_override`

* "transport context" - both global and session

  * :cpp:func:`httpd_sess_get_transport_ctx` - returns SSL used for the session
  * :cpp:func:`httpd_sess_set_transport_ctx`
  * :cpp:func:`httpd_get_global_transport_ctx` - returns the shared SSL context
  * :cpp:member:`httpd_config::global_transport_ctx`
  * :cpp:member:`httpd_config::global_transport_ctx_free_fn`
  * :cpp:member:`httpd_config::open_fn` - used to set up secure sockets

Everything else can be used without limitations.

Usage
-----

Please see the example :example:`protocols/https_server` to learn how to set up a secure server.

Basically, all you need is to generate a certificate, embed it into the firmware, and pass the init struct into the start function after the certificate address and lengths are correctly configured in the init struct.

The server can be started with or without SSL by changing a flag in the init struct - :cpp:member:`httpd_ssl_config::transport_mode`. This could be used, e.g., for testing or in trusted environments where you prefer speed over security.

Performance
-----------

The initial session setup can take about two seconds, or more with slower clock speed or more verbose logging. Subsequent requests through the open secure socket are much faster (down to under 100 ms).

API Reference
-------------

.. include-build-file:: inc/esp_https_server.inc
docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			`HTTPS Server`
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00			`============`
docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			:link_to_translation:`zh_CN:[中文]`
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00
			`Overview`
			`--------`

docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			This component is built on top of :doc:`esp_http_server`. The HTTPS server takes advantage of hook registration functions in the regular HTTP server to provide callback function for SSL session.
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00
docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			All documentation for :doc:`esp_http_server` applies also to a server you create this way.
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00
			`Used APIs`
			`---------`

docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			The following APIs of :doc:`esp_http_server` should not be used with :doc:`esp_https_server`, as they are used internally to handle secure sessions and to maintain internal state:
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00
docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			`* "send", "receive" and "pending" callback registration functions - secure socket handling`
Docs : esp_https_server API references corrected 2018-11-22 05:27:05 -05:00
			* :cpp:func:`httpd_sess_set_send_override`
			* :cpp:func:`httpd_sess_set_recv_override`
			* :cpp:func:`httpd_sess_set_pending_override`
docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00
Docs : esp_https_server API references corrected 2018-11-22 05:27:05 -05:00			`* "transport context" - both global and session`

			* :cpp:func:`httpd_sess_get_transport_ctx` - returns SSL used for the session
			* :cpp:func:`httpd_sess_set_transport_ctx`
			* :cpp:func:`httpd_get_global_transport_ctx` - returns the shared SSL context
docs: fix broken references to misc API functions and types. 2022-03-24 02:57:51 -04:00			* :cpp:member:`httpd_config::global_transport_ctx`
			* :cpp:member:`httpd_config::global_transport_ctx_free_fn`
			* :cpp:member:`httpd_config::open_fn` - used to set up secure sockets
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00
			`Everything else can be used without limitations.`

			`Usage`
			`-----`

			Please see the example :example:`protocols/https_server` to learn how to set up a secure server.

docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			`Basically, all you need is to generate a certificate, embed it into the firmware, and pass the init struct into the start function after the certificate address and lengths are correctly configured in the init struct.`
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00
docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			The server can be started with or without SSL by changing a flag in the init struct - :cpp:member:`httpd_ssl_config::transport_mode`. This could be used, e.g., for testing or in trusted environments where you prefer speed over security.
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00
			`Performance`
			`-----------`

docs:add cn trans for esp-https-server.rst 2022-05-17 05:36:10 -04:00			`The initial session setup can take about two seconds, or more with slower clock speed or more verbose logging. Subsequent requests through the open secure socket are much faster (down to under 100 ms).`
esp_https_server : Docs and API references fixed 2018-11-01 08:54:19 -04:00
			`API Reference`
			`-------------`

docs: add new top-level docs builder that builds docs for a single chip 2019-11-12 22:46:16 -05:00			`.. include-build-file:: inc/esp_https_server.inc`