HTTPS server¶
Overview¶
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.
Used APIs¶
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 sessionhttpd_get_global_transport_ctx()
- returns the shared SSL contexthttpd_config_t.global_transport_ctx
httpd_config_t.global_transport_ctx_free_fn
httpd_config_t.open_fn
- used to set up secure sockets
Everything else can be used without limitations.
Usage¶
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.
Performance¶
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).
API Reference¶
Header File¶
Functions¶
-
esp_err_t
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)
- Return
success
- Parameters
[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
-
void
httpd_ssl_stop
(httpd_handle_t handle)¶ Stop the server. Blocks until the server is shut down.
- Parameters
[in] handle
:
Structures¶
-
struct
httpd_ssl_config
¶ HTTPS server config struct
Please use HTTPD_SSL_CONFIG_DEFAULT() to initialize it.
Public Members
-
httpd_config_t
httpd
¶ Underlying HTTPD server config
Parameters like task stack size and priority can be adjusted here.
-
const uint8_t *
cacert_pem
¶ 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)
-
size_t
cacert_len
¶ CA certificate byte length
-
const uint8_t *
client_verify_cert_pem
¶ Client verify authority certificate (CA used to sign clients, or client cert itself
-
size_t
client_verify_cert_len
¶ Client verify authority cert len
-
const uint8_t *
prvtkey_pem
¶ Private key
-
size_t
prvtkey_len
¶ Private key byte length
-
httpd_ssl_transport_mode_t
transport_mode
¶ Transport Mode (default secure)
-
uint16_t
port_secure
¶ Port used when transport mode is secure (default 443)
-
uint16_t
port_insecure
¶ Port used when transport mode is insecure (default 80)
-
httpd_config_t
Macros¶
-
HTTPD_SSL_CONFIG_DEFAULT
()¶ Default config struct init
(http_server default config had to be copied for customization)
Notes:
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
Type Definitions¶
-
typedef struct httpd_ssl_config
httpd_ssl_config_t
¶