HTTPS Server
Overview
This component is built on top of 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 HTTP Server applies also to a server you create this way.
Used APIs
The following APIs of HTTP Server should not be used with 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
"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::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 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 - 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
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)
- Parameters
config -- [inout] - server config, must not be const. Does not have to stay valid after calling this function.
handle -- [out] - storage for the server handle, must be a valid pointer
- Returns
success
-
esp_err_t httpd_ssl_stop(httpd_handle_t handle)
Stop the server. Blocks until the server is shut down.
- Parameters
handle -- [in]
- Returns
ESP_OK: Server stopped successfully
ESP_ERR_INVALID_ARG: Invalid argument
ESP_FAIL: Failure to shut down server
Structures
-
struct esp_https_server_user_cb_arg
Callback data struct, contains the ESP-TLS connection handle and the connection state at which the callback is executed.
Public Members
-
httpd_ssl_user_cb_state_t user_cb_state
State of user callback
-
httpd_ssl_user_cb_state_t user_cb_state
-
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 *servercert
Server certificate
-
size_t servercert_len
Server certificate byte length
-
const uint8_t *cacert_pem
CA certificate ((CA used to sign clients, or client cert itself)
-
size_t cacert_len
CA certificate byte length
-
const uint8_t *prvtkey_pem
Private key
-
size_t prvtkey_len
Private key byte length
-
bool use_ecdsa_peripheral
Use ECDSA peripheral to use private key
-
uint8_t ecdsa_key_efuse_blk
The efuse block where ECDSA key is stored
-
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)
-
bool session_tickets
Enable tls session tickets
-
bool use_secure_element
Enable secure element for server session
-
esp_https_server_user_cb *user_cb
User callback for esp_https_server
-
void *ssl_userdata
user data to add to the ssl context
-
esp_tls_handshake_callback cert_select_cb
Certificate selection callback to use
-
const char **alpn_protos
Application protocols the server supports in order of prefernece. Used for negotiating during the TLS handshake, first one the client supports is selected. The data structure must live as long as the https server itself!
-
httpd_config_t httpd
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 esp_https_server_user_cb_arg esp_https_server_user_cb_arg_t
Callback data struct, contains the ESP-TLS connection handle and the connection state at which the callback is executed.
-
typedef void esp_https_server_user_cb(esp_https_server_user_cb_arg_t *user_cb)
Callback function prototype Can be used to get connection or client information (SSL context) E.g. Client certificate, Socket FD, Connection state, etc.
- Param user_cb
Callback data struct
-
typedef struct httpd_ssl_config httpd_ssl_config_t