1HTTPS server
2============
3
4Overview
5--------
6
7This component is built on top of `esp_http_server`. The HTTPS server takes advantage of hooks and function overrides in the regular HTTP server to provide encryption using OpenSSL.
8
9All documentation for `esp_http_server` applies also to a server you create this way.
10
11Used APIs
12---------
13
14The following API of `esp_http_server` should not be used with `esp_https_server`, as they are used internally to handle secure sessions and to maintain internal state:
15
16* "send", "receive" and "pending" function overrides - secure socket handling
17
18  * :cpp:func:`httpd_sess_set_send_override`
19  * :cpp:func:`httpd_sess_set_recv_override`
20  * :cpp:func:`httpd_sess_set_pending_override`
21* "transport context" - both global and session
22
23  * :cpp:func:`httpd_sess_get_transport_ctx` - returns SSL used for the session
24  * :cpp:func:`httpd_sess_set_transport_ctx`
25  * :cpp:func:`httpd_get_global_transport_ctx` - returns the shared SSL context
26  * :c:member:`httpd_config_t.global_transport_ctx`
27  * :c:member:`httpd_config_t.global_transport_ctx_free_fn`
28  * :c:member:`httpd_config_t.open_fn` - used to set up secure sockets
29
30Everything else can be used without limitations.
31
32Usage
33-----
34
35Please see the example :example:`protocols/https_server` to learn how to set up a secure server.
36
37Basically all you need is to generate a certificate, embed it in the firmware, and provide its pointers and lengths to the start function via the init struct.
38
39The server can be started with or without SSL by changing a flag in the init struct - :c:member:`httpd_ssl_config.transport_mode`. This could be used e.g. for testing or in trusted environments where you prefer speed over security.
40
41Performance
42-----------
43
44The initial session setup can take about two seconds, or more with slower clock speeds or more verbose logging. Subsequent requests through the open secure socket are much faster (down to under
45100 ms).
46
47API Reference
48-------------
49
50.. include-build-file:: inc/esp_https_server.inc
51