From aa6066a1970af6b0324b0959926646c2ca9d805e Mon Sep 17 00:00:00 2001 From: Anurag Kar Date: Thu, 1 Nov 2018 18:24:19 +0530 Subject: [PATCH] esp_https_server : Docs and API references fixed --- .../esp_http_server/include/esp_http_server.h | 20 +++++--- components/esp_https_server/README.md | 44 ---------------- docs/Doxyfile | 1 + .../protocols/esp_https_server.rst | 51 +++++++++++++++++++ docs/en/api-reference/protocols/index.rst | 1 + .../protocols/esp_https_server.rst | 1 + examples/protocols/https_server/README.md | 17 +++++-- .../https_server/main/certs/gencert.sh | 8 --- 8 files changed, 81 insertions(+), 62 deletions(-) delete mode 100644 components/esp_https_server/README.md create mode 100644 docs/en/api-reference/protocols/esp_https_server.rst create mode 100644 docs/zh_CN/api-reference/protocols/esp_https_server.rst delete mode 100644 examples/protocols/https_server/main/certs/gencert.sh diff --git a/components/esp_http_server/include/esp_http_server.h b/components/esp_http_server/include/esp_http_server.h index 519538f9a..990828a1c 100644 --- a/components/esp_http_server/include/esp_http_server.h +++ b/components/esp_http_server/include/esp_http_server.h @@ -150,6 +150,10 @@ typedef struct httpd_config { * function for freeing the global user context, please specify that here. */ void * global_user_ctx; + + /** + * Free function for global user context + */ httpd_free_ctx_fn_t global_user_ctx_free_fn; /** @@ -159,6 +163,10 @@ typedef struct httpd_config { * It will be freed using free(), unless global_transport_ctx_free_fn is specified. */ void * global_transport_ctx; + + /** + * Free function for global transport context + */ httpd_free_ctx_fn_t global_transport_ctx_free_fn; /** @@ -570,8 +578,8 @@ esp_err_t httpd_set_pending_override(httpd_req_t *r, httpd_pending_func_t pendin * * @see httpd_set_send_override() * - * @param[in] hd HTTPD instance handle - * @param[in] fd session socket FD + * @param[in] hd HTTPD instance handle + * @param[in] sockfd Session socket FD * @param[in] send_func The send function to be set for this session * * @return status code @@ -583,8 +591,8 @@ esp_err_t httpd_set_sess_send_override(httpd_handle_t hd, int sockfd, httpd_send * * @see httpd_set_recv_override() * - * @param[in] hd HTTPD instance handle - * @param[in] fd session socket FD + * @param[in] hd HTTPD instance handle + * @param[in] sockfd Session socket FD * @param[in] recv_func The receive function to be set for this session * * @return status code @@ -596,8 +604,8 @@ esp_err_t httpd_set_sess_recv_override(httpd_handle_t hd, int sockfd, httpd_recv * * @see httpd_set_pending_override() * - * @param[in] hd HTTPD instance handle - * @param[in] fd session socket FD + * @param[in] hd HTTPD instance handle + * @param[in] sockfd Session socket FD * @param[in] pending_func The receive function to be set for this session * * @return status code diff --git a/components/esp_https_server/README.md b/components/esp_https_server/README.md deleted file mode 100644 index 2d7bc7f8b..000000000 --- a/components/esp_https_server/README.md +++ /dev/null @@ -1,44 +0,0 @@ -# HTTPS server - -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. - -All documentation for `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: - -- "send", "receive" and "pending" function overrides - secure socket handling - - `httpd_set_sess_send_override()` - - `httpd_set_sess_recv_override()` - - `httpd_set_sess_pending_override()` - - `httpd_set_send_override()` - - `httpd_set_recv_override()` - - `httpd_set_pending_override()` -- "transport context" - both global and session - - `httpd_sess_get_transport_ctx()` - returns SSL used for the session - - `httpd_sess_set_transport_ctx()` - - `httpd_get_global_transport_ctx()` - returns the shared SSL context - - `httpd_config_t.global_transport_ctx` - - `httpd_config_t.global_transport_ctx_free_fn` - - `httpd_config_t.open_fn` - used to set up secure sockets - -Everything else can be used without limitations. - -## Usage - -Please see the 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. - -The server can be started with or without SSL by changing a flag in the init struct. -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). diff --git a/docs/Doxyfile b/docs/Doxyfile index 3306fbc07..9e1bcdc9e 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -98,6 +98,7 @@ INPUT = \ ../../components/mdns/include/mdns.h \ ../../components/esp_http_client/include/esp_http_client.h \ ../../components/esp_http_server/include/esp_http_server.h \ + ../../components/esp_https_server/include/esp_https_server.h \ ## ## Provisioning - API Reference ## diff --git a/docs/en/api-reference/protocols/esp_https_server.rst b/docs/en/api-reference/protocols/esp_https_server.rst new file mode 100644 index 000000000..714afec3f --- /dev/null +++ b/docs/en/api-reference/protocols/esp_https_server.rst @@ -0,0 +1,51 @@ +HTTPS server +============ + +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. + +All documentation for `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: + +- "send", "receive" and "pending" function overrides - secure socket handling + - :cpp:func:`httpd_set_sess_send_override` + - :cpp:func:`httpd_set_sess_recv_override` + - :cpp:func:`httpd_set_sess_pending_override` + - :cpp:func:`httpd_set_send_override` + - :cpp:func:`httpd_set_recv_override` + - :cpp:func:`httpd_set_pending_override` +- "transport context" - both global and session + - :cpp:func:`httpd_sess_get_transport_ctx` - returns SSL used for the session + - :cpp:func:`httpd_sess_set_transport_ctx` + - :cpp:func:`httpd_get_global_transport_ctx` - returns the shared SSL context + - :c:member:`httpd_config_t.global_transport_ctx` + - :c:member:`httpd_config_t.global_transport_ctx_free_fn` + - :c:member:`httpd_config_t.open_fn` - used to set up secure sockets + +Everything else can be used without limitations. + +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. + +The server can be started with or without SSL by changing a flag in the init struct. 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). + +API Reference +------------- + +.. include:: /_build/inc/esp_https_server.inc diff --git a/docs/en/api-reference/protocols/index.rst b/docs/en/api-reference/protocols/index.rst index fff67481f..f57b4cc4e 100644 --- a/docs/en/api-reference/protocols/index.rst +++ b/docs/en/api-reference/protocols/index.rst @@ -8,6 +8,7 @@ Protocols API ESP-TLS HTTP Client HTTP Server + HTTPS Server ASIO ESP-MQTT Modbus slave diff --git a/docs/zh_CN/api-reference/protocols/esp_https_server.rst b/docs/zh_CN/api-reference/protocols/esp_https_server.rst new file mode 100644 index 000000000..8f338a342 --- /dev/null +++ b/docs/zh_CN/api-reference/protocols/esp_https_server.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/protocols/esp_https_server.rst diff --git a/examples/protocols/https_server/README.md b/examples/protocols/https_server/README.md index c89c0f79f..08aa770c0 100644 --- a/examples/protocols/https_server/README.md +++ b/examples/protocols/https_server/README.md @@ -6,10 +6,19 @@ See the `esp_https_server` component documentation for details. ## Certificates -You will need to approve a security exception in your browser. This is because of a self signed +You will need to approve a security exception in your browser. This is because of a self signed certificate; this will be always the case, unless you preload the CA root into your browser/system as trusted. -You can generate a new certificate using the OpenSSL command line tool as shown in the script -`main/certs/gencert.sh`. It is **strongly recommended** to not reuse the example certificate in -your application; it is included only for demonstration. +You can generate a new certificate using the OpenSSL command line tool: + +``` +openssl req -newkey rsa:2048 -nodes -keyout prvtkey.pem -x509 -days 3650 -out cacert.pem -subj "/CN=ESP32 HTTPS server example" +``` + +Expiry time and metadata fields can be adjusted in the invocation. + +Please see the openssl man pages (man openssl-req) for more details. + +It is **strongly recommended** to not reuse the example certificate in your application; +it is included only for demonstration. diff --git a/examples/protocols/https_server/main/certs/gencert.sh b/examples/protocols/https_server/main/certs/gencert.sh deleted file mode 100644 index 5b2f79dc4..000000000 --- a/examples/protocols/https_server/main/certs/gencert.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/bin/bash - -# Example command to generate a new certificate in the correct format. -# Expiry time and metadata fields can be adjusted in the invocation. - -# Please see the openssl man pages (man openssl-req) for more details - -openssl req -newkey rsa:2048 -nodes -keyout prvtkey.pem -x509 -days 3650 -out cacert.pem -subj "/CN=ESP32 HTTPS server example"