diff --git a/docs/en/api-reference/protocols/esp_https_server.rst b/docs/en/api-reference/protocols/esp_https_server.rst index bb4c52cab9..9388769309 100644 --- a/docs/en/api-reference/protocols/esp_https_server.rst +++ b/docs/en/api-reference/protocols/esp_https_server.rst @@ -1,23 +1,25 @@ -HTTPS server +HTTPS Server ============ +:link_to_translation:`zh_CN:[中文]` Overview -------- -This component is built on top of `esp_http_server`. The HTTPS server takes advantage of hooks and function overrides in the regular HTTP server to provide encryption using OpenSSL. +This component is built on top of :doc:`esp_http_server`. The HTTPS server takes advantage of hook registration functions in the regular HTTP server to provide callback function for SSL session. -All documentation for `esp_http_server` applies also to a server you create this way. +All documentation for :doc:`esp_http_server` applies also to a server you create this way. Used APIs --------- -The following API of `esp_http_server` should not be used with `esp_https_server`, as they are used internally to handle secure sessions and to maintain internal state: +The following APIs of :doc:`esp_http_server` should not be used with :doc:`esp_https_server`, as they are used internally to handle secure sessions and to maintain internal state: -* "send", "receive" and "pending" function overrides - secure socket handling +* "send", "receive" and "pending" callback registration functions - secure socket handling * :cpp:func:`httpd_sess_set_send_override` * :cpp:func:`httpd_sess_set_recv_override` * :cpp:func:`httpd_sess_set_pending_override` + * "transport context" - both global and session * :cpp:func:`httpd_sess_get_transport_ctx` - returns SSL used for the session @@ -34,15 +36,14 @@ Usage Please see the example :example:`protocols/https_server` to learn how to set up a secure server. -Basically all you need is to generate a certificate, embed it in the firmware, and provide its pointers and lengths to the start function via the init struct. +Basically, all you need is to generate a certificate, embed it into the firmware, and pass the init struct into the start function after the certificate address and lengths are correctly configured in the init struct. -The server can be started with or without SSL by changing a flag in the init struct - :cpp:member:`httpd_ssl_config::transport_mode`. This could be used e.g. for testing or in trusted environments where you prefer speed over security. +The server can be started with or without SSL by changing a flag in the init struct - :cpp:member:`httpd_ssl_config::transport_mode`. This could be used, e.g., for testing or in trusted environments where you prefer speed over security. Performance ----------- -The initial session setup can take about two seconds, or more with slower clock speeds or more verbose logging. Subsequent requests through the open secure socket are much faster (down to under -100 ms). +The initial session setup can take about two seconds, or more with slower clock speed or more verbose logging. Subsequent requests through the open secure socket are much faster (down to under 100 ms). API Reference ------------- diff --git a/docs/zh_CN/api-reference/protocols/esp_https_server.rst b/docs/zh_CN/api-reference/protocols/esp_https_server.rst index 8f338a3429..ff0fb7ba82 100644 --- a/docs/zh_CN/api-reference/protocols/esp_https_server.rst +++ b/docs/zh_CN/api-reference/protocols/esp_https_server.rst @@ -1 +1,51 @@ -.. include:: ../../../en/api-reference/protocols/esp_https_server.rst +HTTPS 服务器 +============ +:link_to_translation:`en:[English]` + +概述 +------ + +HTTPS 服务器组件建立在 :doc:`esp_http_server` 组件的基础上。该服务器借助常规 HTTP 服务器中的钩子注册函数，注册 SSL 会话回调处理函数。 + +:doc:`esp_http_server` 组件的所有文档同样适用于用户按照本文档搭建的服务器。 + +API 说明 +--------- + +下列 :doc:`esp_http_server` 的 API 已不适用于 :doc:`esp_https_server`。这些 API 仅限内部使用，用于处理安全会话和维护内部状态。 + +* "send"、"receive" 和 "pending" 回调注册函数——处理安全套接字 + + * :cpp:func:`httpd_sess_set_send_override` + * :cpp:func:`httpd_sess_set_recv_override` + * :cpp:func:`httpd_sess_set_pending_override` + +* "transport context"——传输层上下文 + + * :cpp:func:`httpd_sess_get_transport_ctx`：返回会话使用的 SSL + * :cpp:func:`httpd_sess_set_transport_ctx` + * :cpp:func:`httpd_get_global_transport_ctx`：返回共享的 SSL 上下文 + * :cpp:member:`httpd_config::global_transport_ctx` + * :cpp:member:`httpd_config::global_transport_ctx_free_fn` + * :cpp:member:`httpd_config::open_fn`：用于设置安全套接字 + +其他 API 均可使用，没有其他限制。 + +如何使用 +--------- + +请参考示例 :example:`protocols/https_server` 来学习如何搭建安全的服务器。 + +总体而言，您只需要生成证书，将其嵌入到固件中，并且在初始化结构体中配置好正确的证书地址和长度后，将其传入服务器启动函数。 + +通过改变初始化配置结构体中的标志 :cpp:member:`httpd_ssl_config::transport_mode`，可以选择是否需要 SSL 连接来启动服务器。在测试时或在速度比安全性更重要的可信环境中，您可以使用此功能。 + +性能 +----- + +建立起始会话大约需要两秒，在时钟速度较慢或日志记录冗余信息较多的情况下，可能需要花费更多时间。后续通过已打开的安全套接字建立请求的速度会更快，最快只需不到 100 ms。 + +API 参考 +--------- + +.. include-build-file:: inc/esp_https_server.inc