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:

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

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)

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

Provide feedback about this document