HTTPS 服务器

[English]

概述

HTTPS 服务器组件建立在 HTTP 服务器 组件的基础上。该服务器借助常规 HTTP 服务器中的钩子注册函数,注册 SSL 会话回调处理函数。

HTTP 服务器 组件的所有文档同样适用于用户按照本文档搭建的服务器。

API 说明

下列 HTTP 服务器 的 API 已不适用于 HTTPS 服务器。这些 API 仅限内部使用,用于处理安全会话和维护内部状态。

其他 API 均可使用,没有其他限制。

如何使用

请参考示例 protocols/https_server 来学习如何搭建安全的服务器。

总体而言,您只需要生成证书,将其嵌入到固件中,并且在初始化结构体中配置好正确的证书地址和长度后,将其传入服务器启动函数。

通过改变初始化配置结构体中的标志 httpd_ssl_config::transport_mode,可以选择是否需要 SSL 连接来启动服务器。在测试时或在速度比安全性更重要的可信环境中,您可以使用此功能。

性能

建立起始会话大约需要两秒,在时钟速度较慢或日志记录冗余信息较多的情况下,可能需要花费更多时间。后续通过已打开的安全套接字建立请求的速度会更快,最快只需不到 100 ms。

API 参考

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)

参数
  • 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

返回

success

esp_err_t httpd_ssl_stop(httpd_handle_t handle)

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

参数

handle[in]

返回

  • 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

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 *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

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

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

Enumerations

enum httpd_ssl_transport_mode_t

Values:

enumerator HTTPD_SSL_TRANSPORT_SECURE
enumerator HTTPD_SSL_TRANSPORT_INSECURE
enum httpd_ssl_user_cb_state_t

Indicates the state at which the user callback is executed, i.e at session creation or session close.

Values:

enumerator HTTPD_SSL_USER_CB_SESS_CREATE
enumerator HTTPD_SSL_USER_CB_SESS_CLOSE