/* * 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 #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_