diff --git a/components/esp_https_server/Kconfig b/components/esp_https_server/Kconfig index a14d157b52..e4fbc5503a 100644 --- a/components/esp_https_server/Kconfig +++ b/components/esp_https_server/Kconfig @@ -13,4 +13,13 @@ menu "ESP HTTPS server" This config option helps in setting the time in millisecond to wait for event to be posted to the system default event loop. Set it to -1 if you need to set timeout to portMAX_DELAY. + config ESP_HTTPS_SERVER_CERT_SELECT_HOOK + select ESP_TLS_SERVER_CERT_SELECT_HOOK + bool "Enable certificate selection hook" + default n + help + Enable certificate selection hook for ESP HTTPS Server. When enabled, this allows the server to + dynamically select the appropriate certificate based on the client's Server Name Indication (SNI). + This is useful for hosting multiple domains on a single server with different SSL certificates. + endmenu diff --git a/components/esp_https_server/include/esp_https_server.h b/components/esp_https_server/include/esp_https_server.h index 786ab8e658..56f19edca7 100644 --- a/components/esp_https_server/include/esp_https_server.h +++ b/components/esp_https_server/include/esp_https_server.h @@ -44,6 +44,8 @@ typedef enum { HTTPD_SSL_USER_CB_SESS_CLOSE } httpd_ssl_user_cb_state_t; +typedef esp_tls_handshake_callback esp_https_server_cert_select_cb; + /** * @brief Callback data struct, contains the ESP-TLS connection handle * and the connection state at which the callback is executed @@ -123,8 +125,8 @@ struct httpd_ssl_config { 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; + * The callback is only applicable when CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK is enabled in menuconfig */ + esp_https_server_cert_select_cb 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. diff --git a/components/esp_https_server/src/https_server.c b/components/esp_https_server/src/https_server.c index 6fe65dec69..ed3d432a94 100644 --- a/components/esp_https_server/src/https_server.c +++ b/components/esp_https_server/src/https_server.c @@ -278,7 +278,7 @@ static esp_err_t create_secure_context(const struct httpd_ssl_config *config, ht cfg->userdata = config->ssl_userdata; cfg->alpn_protos = config->alpn_protos; -#if defined(CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK) +#if defined(CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK) cfg->cert_select_cb = config->cert_select_cb; #endif @@ -312,13 +312,13 @@ static esp_err_t create_secure_context(const struct httpd_ssl_config *config, ht goto exit; } } else { -#if defined(CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK) +#if defined(CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK) if (config->cert_select_cb == NULL) { #endif ESP_LOGE(TAG, "No Server certificate supplied"); ret = ESP_ERR_INVALID_ARG; goto exit; -#if defined(CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK) +#if defined(CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK) } else { ESP_LOGW(TAG, "Server certificate not supplied, make sure to supply it in the certificate selection hook!"); } @@ -349,7 +349,7 @@ static esp_err_t create_secure_context(const struct httpd_ssl_config *config, ht goto exit; } } else { -#if defined(CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK) +#if defined(CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK) if (config->cert_select_cb == NULL) { ESP_LOGE(TAG, "No Server key supplied and no certificate selection hook is present"); ret = ESP_ERR_INVALID_ARG; diff --git a/docs/en/api-reference/protocols/esp_https_server.rst b/docs/en/api-reference/protocols/esp_https_server.rst index aee3357b52..e1ac55111f 100644 --- a/docs/en/api-reference/protocols/esp_https_server.rst +++ b/docs/en/api-reference/protocols/esp_https_server.rst @@ -70,6 +70,26 @@ Application Examples - :example:`protocols/https_server/wss_server` demonstrates how to create an SSL server with a simple WebSocket request handler that supports handling multiple clients, PING-PONG mechanism, and sending asynchronous messages to all clients. +HTTPS Server Cert Selection Hook +-------------------------------- + +The ESP HTTPS Server component provides an option to set the server certification selection hook. This feature allows you to configure and use a certificate selection callback during server handshake. The callback helps to select a certificate to present to the client based on the TLS extensions supplied in the client hello message, such as ALPN and SNI. To enable this feature, please enable :ref:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` in the ESP HTTPS Server menuconfig. Note that you also need to enable :ref:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK` from the ESP-TLS component, as this option depends on it. Please note that the ESP-TLS option is only available when Mbedtls is used as the TLS stack for ESP-TLS (default behaviour). + +When enabled, you can set the certificate selection callback using the :cpp:member:`httpd_ssl_config::cert_select_cb` member of the :cpp:type:`httpd_ssl_config_t` structure. + +.. code-block:: c + + int cert_selection_callback(mbedtls_ssl_context *ssl) + { + /* Code that the callback should execute */ + return 0; + } + + httpd_ssl_config_t cfg = { + cert_select_cb = cert_section_callback, + }; + + API Reference ------------- diff --git a/docs/en/migration-guides/release-5.x/5.4/index.rst b/docs/en/migration-guides/release-5.x/5.4/index.rst index f6b85cb5e7..4b04ce76b3 100644 --- a/docs/en/migration-guides/release-5.x/5.4/index.rst +++ b/docs/en/migration-guides/release-5.x/5.4/index.rst @@ -11,3 +11,4 @@ Migration from 5.3 to 5.4 bluetooth-classic storage wifi + protocols diff --git a/docs/en/migration-guides/release-5.x/5.4/protocols.rst b/docs/en/migration-guides/release-5.x/5.4/protocols.rst new file mode 100644 index 0000000000..a327325408 --- /dev/null +++ b/docs/en/migration-guides/release-5.x/5.4/protocols.rst @@ -0,0 +1,14 @@ +Protocols +========= + +:link_to_translation:`zh_CN:[中文]` + +HTTPS Server +------------ + +Certificate Selection Hook +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to enable the Certificate Selection hook feature in ESP HTTPS Server, now you need to enable :ref:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` instead of :ref:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK`. + +The new :ref:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` option automatically selects :ref:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK`. diff --git a/docs/zh_CN/migration-guides/release-5.x/5.4/index.rst b/docs/zh_CN/migration-guides/release-5.x/5.4/index.rst index e2256533e9..04f94d7947 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.4/index.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.4/index.rst @@ -11,3 +11,4 @@ bluetooth-classic storage wifi + protocols diff --git a/docs/zh_CN/migration-guides/release-5.x/5.4/protocols.rst b/docs/zh_CN/migration-guides/release-5.x/5.4/protocols.rst new file mode 100644 index 0000000000..7ff979f89e --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/5.4/protocols.rst @@ -0,0 +1 @@ +.. include:: ../../../../en/migration-guides/release-5.x/5.4/protocols.rst diff --git a/examples/protocols/https_server/simple/sdkconfig.ci b/examples/protocols/https_server/simple/sdkconfig.ci index badfd866fe..d12b3d37a6 100644 --- a/examples/protocols/https_server/simple/sdkconfig.ci +++ b/examples/protocols/https_server/simple/sdkconfig.ci @@ -1,4 +1,4 @@ CONFIG_ESP_HTTPS_SERVER_ENABLE=y -CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK=y +CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK=y CONFIG_EXAMPLE_ENABLE_HTTPS_USER_CALLBACK=y CONFIG_EXAMPLE_WIFI_SSID_PWD_FROM_STDIN=y