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

  • httpd_sess_set_send_override()

  • httpd_sess_set_recv_override()

  • httpd_sess_set_pending_override()

• “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

• components/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)

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

void httpd_ssl_stop(httpd_handle_t handle)

Stop the server. Blocks until the server is shut down.

Parameters

handle – [in]

Structures

struct esp_https_server_user_cb_arg

Callback data struct, contains the ESP-TLS connection handle.

Public Members

const esp_tls_t *tls

ESP-TLS connection handle

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)

bool session_tickets

Enable tls session tickets

esp_https_server_user_cb *user_cb

User callback for esp_https_server

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.

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

Enumerations

enum httpd_ssl_transport_mode_t

Values:

enumerator HTTPD_SSL_TRANSPORT_SECURE

enumerator HTTPD_SSL_TRANSPORT_INSECURE

Provide feedback about this document