kopia lustrzana https://github.com/espressif/esp-idf
219 wiersze
7.6 KiB
C
219 wiersze
7.6 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2018-2023 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef _ESP_HTTPS_SERVER_H_
|
|
#define _ESP_HTTPS_SERVER_H_
|
|
|
|
#include <stdbool.h>
|
|
#include "esp_err.h"
|
|
#include "esp_http_server.h"
|
|
#include "esp_tls.h"
|
|
|
|
#include "esp_event.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
ESP_EVENT_DECLARE_BASE(ESP_HTTPS_SERVER_EVENT);
|
|
|
|
typedef enum {
|
|
HTTPS_SERVER_EVENT_ERROR = 0, /*!< This event occurs when there are any errors during execution */
|
|
HTTPS_SERVER_EVENT_START, /*!< This event occurs when HTTPS Server is started */
|
|
HTTPS_SERVER_EVENT_ON_CONNECTED, /*!< Once the HTTPS Server has been connected to the client */
|
|
HTTPS_SERVER_EVENT_ON_DATA, /*!< Occurs when receiving data from the client */
|
|
HTTPS_SERVER_EVENT_SENT_DATA, /*!< Occurs when an ESP HTTPS server sends data to the client */
|
|
HTTPS_SERVER_EVENT_DISCONNECTED, /*!< The connection has been disconnected */
|
|
HTTPS_SERVER_EVENT_STOP, /*!< This event occurs when HTTPS Server is stopped */
|
|
} esp_https_server_event_id_t;
|
|
|
|
typedef enum {
|
|
HTTPD_SSL_TRANSPORT_SECURE, // SSL Enabled
|
|
HTTPD_SSL_TRANSPORT_INSECURE // SSL disabled
|
|
} httpd_ssl_transport_mode_t;
|
|
|
|
/**
|
|
* @brief Indicates the state at which the user callback is executed,
|
|
* i.e at session creation or session close
|
|
*/
|
|
typedef enum {
|
|
HTTPD_SSL_USER_CB_SESS_CREATE,
|
|
HTTPD_SSL_USER_CB_SESS_CLOSE
|
|
} httpd_ssl_user_cb_state_t;
|
|
|
|
/**
|
|
* @brief Callback data struct, contains the ESP-TLS connection handle
|
|
* and the connection state at which the callback is executed
|
|
*/
|
|
typedef struct esp_https_server_user_cb_arg {
|
|
httpd_ssl_user_cb_state_t user_cb_state; /*!< State of user callback */
|
|
esp_tls_t *tls; /*!< ESP-TLS connection handle */
|
|
} esp_https_server_user_cb_arg_t;
|
|
|
|
typedef esp_tls_last_error_t esp_https_server_last_error_t;
|
|
|
|
/**
|
|
* @brief 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 void esp_https_server_user_cb(esp_https_server_user_cb_arg_t *user_cb);
|
|
|
|
/**
|
|
* HTTPS server config struct
|
|
*
|
|
* Please use HTTPD_SSL_CONFIG_DEFAULT() to initialize it.
|
|
*/
|
|
struct httpd_ssl_config {
|
|
/**
|
|
* Underlying HTTPD server config
|
|
*
|
|
* Parameters like task stack size and priority can be adjusted here.
|
|
*/
|
|
httpd_config_t httpd;
|
|
|
|
/** Server certificate */
|
|
const uint8_t *servercert;
|
|
|
|
/** Server certificate byte length */
|
|
size_t servercert_len;
|
|
|
|
/** CA certificate ((CA used to sign clients, or client cert itself) */
|
|
const uint8_t *cacert_pem;
|
|
|
|
/** CA certificate byte length */
|
|
size_t cacert_len;
|
|
|
|
/** Private key */
|
|
const uint8_t *prvtkey_pem;
|
|
|
|
/** Private key byte length */
|
|
size_t prvtkey_len;
|
|
|
|
/** Use ECDSA peripheral to use private key */
|
|
bool use_ecdsa_peripheral;
|
|
|
|
/** The efuse block where ECDSA key is stored */
|
|
uint8_t ecdsa_key_efuse_blk;
|
|
|
|
/** Transport Mode (default secure) */
|
|
httpd_ssl_transport_mode_t transport_mode;
|
|
|
|
/** Port used when transport mode is secure (default 443) */
|
|
uint16_t port_secure;
|
|
|
|
/** Port used when transport mode is insecure (default 80) */
|
|
uint16_t port_insecure;
|
|
|
|
/** Enable tls session tickets */
|
|
bool session_tickets;
|
|
|
|
/** Enable secure element for server session */
|
|
bool use_secure_element;
|
|
|
|
/** User callback for esp_https_server */
|
|
esp_https_server_user_cb *user_cb;
|
|
|
|
/** User data to add to the ssl context */
|
|
void *ssl_userdata;
|
|
|
|
/** Certificate selection callback to use.
|
|
* The callback is only applicable when CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK is enabled in menuconfig */
|
|
esp_tls_handshake_callback cert_select_cb;
|
|
|
|
/** 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 */
|
|
const char** alpn_protos;
|
|
};
|
|
|
|
typedef struct httpd_ssl_config httpd_ssl_config_t;
|
|
|
|
/**
|
|
* Default config struct init
|
|
* 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
|
|
*/
|
|
#define HTTPD_SSL_CONFIG_DEFAULT() { \
|
|
.httpd = { \
|
|
.task_priority = tskIDLE_PRIORITY+5, \
|
|
.stack_size = 10240, \
|
|
.core_id = tskNO_AFFINITY, \
|
|
.task_caps = (MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT), \
|
|
.server_port = 0, \
|
|
.ctrl_port = ESP_HTTPD_DEF_CTRL_PORT+1, \
|
|
.max_open_sockets = 4, \
|
|
.max_uri_handlers = 8, \
|
|
.max_resp_headers = 8, \
|
|
.backlog_conn = 5, \
|
|
.lru_purge_enable = true, \
|
|
.recv_wait_timeout = 5, \
|
|
.send_wait_timeout = 5, \
|
|
.global_user_ctx = NULL, \
|
|
.global_user_ctx_free_fn = NULL, \
|
|
.global_transport_ctx = NULL, \
|
|
.global_transport_ctx_free_fn = NULL, \
|
|
.enable_so_linger = false, \
|
|
.linger_timeout = 0, \
|
|
.keep_alive_enable = false, \
|
|
.keep_alive_idle = 0, \
|
|
.keep_alive_interval = 0, \
|
|
.keep_alive_count = 0, \
|
|
.open_fn = NULL, \
|
|
.close_fn = NULL, \
|
|
.uri_match_fn = NULL \
|
|
}, \
|
|
.servercert = NULL, \
|
|
.servercert_len = 0, \
|
|
.cacert_pem = NULL, \
|
|
.cacert_len = 0, \
|
|
.prvtkey_pem = NULL, \
|
|
.prvtkey_len = 0, \
|
|
.use_ecdsa_peripheral = false, \
|
|
.ecdsa_key_efuse_blk = 0, \
|
|
.transport_mode = HTTPD_SSL_TRANSPORT_SECURE, \
|
|
.port_secure = 443, \
|
|
.port_insecure = 80, \
|
|
.session_tickets = false, \
|
|
.use_secure_element = false, \
|
|
.user_cb = NULL, \
|
|
.ssl_userdata = NULL, \
|
|
.cert_select_cb = NULL, \
|
|
.alpn_protos = NULL, \
|
|
}
|
|
|
|
/**
|
|
* Create a SSL capable HTTP server (secure mode may be disabled in config)
|
|
*
|
|
* @param[in,out] config - server config, must not be const. Does not have to stay valid after
|
|
* calling this function.
|
|
* @param[out] handle - storage for the server handle, must be a valid pointer
|
|
* @return success
|
|
*/
|
|
esp_err_t httpd_ssl_start(httpd_handle_t *handle, httpd_ssl_config_t *config);
|
|
|
|
/**
|
|
* Stop the server. Blocks until the server is shut down.
|
|
*
|
|
* @param[in] handle
|
|
* @return
|
|
* - ESP_OK: Server stopped successfully
|
|
* - ESP_ERR_INVALID_ARG: Invalid argument
|
|
* - ESP_FAIL: Failure to shut down server
|
|
*/
|
|
esp_err_t httpd_ssl_stop(httpd_handle_t handle);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // _ESP_HTTPS_SERVER_H_
|