Merge branch 'feat/updating_configs_of_esp_https_server' into 'master'

mahavirj · mahavirj · commit 401fa7b0f3c4 · 2024-11-15T18:35:00.000+08:00
feat(esp_https_server): Updated the ESP_TLS_SERVER_CERT_SELECT_HOOK config

Closes IDF-8418

See merge request espressif/esp-idf!33966
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+.. include:: ../../../../en/migration-guides/release-5.x/5.4/protocols.rst`