HTTPS 服务器
概述
HTTPS 服务器组件建立在 HTTP 服务器 组件的基础上。该服务器借助常规 HTTP 服务器中的钩子注册函数，注册 SSL 会话回调处理函数。
HTTP 服务器 组件的所有文档同样适用于用户按照本文档搭建的服务器。
API 说明
下列 HTTP 服务器 的 API 已不适用于 HTTPS 服务器。这些 API 仅限内部使用，用于处理安全会话和维护内部状态。
“send”、”receive” 和 “pending” 回调注册函数——处理安全套接字
“transport context”——传输层上下文
其他 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
-
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
-
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
-
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