This 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.
All documentation for esp_http_server applies also to a server you create this way.
The 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:
“send”, “receive” and “pending” function overrides - secure socket handling
“transport context” - both global and session
httpd_sess_get_transport_ctx()- returns SSL used for the session
httpd_get_global_transport_ctx()- returns the shared SSL context
httpd_config_t.open_fn- used to set up secure sockets
Everything else can be used without limitations.
Please see the example protocols/https_server to learn how to set up a secure server.
Basically 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.
The server can be started with or without SSL by changing a flag in the init struct -
httpd_ssl_config.transport_mode. This could be used e.g. for testing or in trusted environments where you prefer speed over security.
The 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 100 ms).
httpd_ssl_start(httpd_handle_t *handle, httpd_ssl_config_t *config)¶
Create a SSL capable HTTP server (secure mode may be disabled in config)
[inout] config: - server config, must not be const. Does not have to stay valid after calling this function.
[out] handle: - storage for the server handle, must be a valid pointer
Stop the server. Blocks until the server is shut down.
HTTPS server config struct
Please use HTTPD_SSL_CONFIG_DEFAULT() to initialize it.
Underlying HTTPD server config
Parameters like task stack size and priority can be adjusted here.
const uint8_t *
CA certificate (here it is treated as server cert) Todo: Fix this change in release/v5.0 as it would be a breaking change i.e. Rename the nomenclature of variables holding different certs in https_server component as well as example 1)The cacert variable should hold the CA which is used to authenticate clients (should inherit current role of client_verify_cert_pem var) 2)There should be another variable servercert which whould hold servers own certificate (should inherit current role of cacert var)
CA certificate byte length
const uint8_t *
Client verify authority certificate (CA used to sign clients, or client cert itself
Client verify authority cert len
const uint8_t *
Private key byte length
Transport Mode (default secure)
Port used when transport mode is secure (default 443)
Port used when transport mode is insecure (default 80)
Default config struct init
(http_server default config had to be copied for customization)
port is set when starting the server, according to ‘transport_mode’
one socket uses ~ 40kB RAM with SSL, we reduce the default socket count to 4
SSL sockets are usually long-lived, closing LRU prevents pool exhaustion DOS
Stack size may need adjustments depending on the user application
typedef struct httpd_ssl_config