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 session
- httpd_sess_set_transport_ctx()
- httpd_get_global_transport_ctx() - returns the shared SSL context
- httpd_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¶

esp_https_server/include/esp_https_server.h

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

size_t cacert_len¶: CA certificate byte length

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)

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¶

Enumerations¶

enum httpd_ssl_transport_mode_t¶

Values:

HTTPD_SSL_TRANSPORT_SECURE¶

HTTPD_SSL_TRANSPORT_INSECURE¶