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
This header file can be included with:
#include "esp_https_server.h"
- This header file is a part of the API provided by the
esp_https_servercomponent. To declare that your component depends onesp_https_server, add the following to your CMakeLists.txt:
REQUIRES esp_https_serveror
> PRIV_REQUIRES esp_https_server
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
bool use_ecdsa_peripheral
Use ECDSA peripheral to use private key
uint8_t ecdsa_key_efuse_blk
The efuse block where ECDSA key is stored
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
const char **alpn_protos
Application protocols the server supports in order of prefernece. Used for negotiating during the TLS handshake, first one the client supports is selected. The data structure must live as long as the https server itself!
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