esp_https_server : Docs and API references fixed
This commit is contained in:
Anurag Kar
bot
parent
4dd0fa61e9
commit
aa6066a197
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
##
|
||||
|
|
|
|||
51
docs/en/api-reference/protocols/esp_https_server.rst
Normal file
51
docs/en/api-reference/protocols/esp_https_server.rst
Normal file
|
|
@ -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
|
||||
|
|
@ -8,6 +8,7 @@ Protocols API
|
|||
ESP-TLS <esp_tls>
|
||||
HTTP Client <esp_http_client>
|
||||
HTTP Server <esp_http_server>
|
||||
HTTPS Server <esp_https_server>
|
||||
ASIO <asio>
|
||||
ESP-MQTT <mqtt>
|
||||
Modbus slave <modbus>
|
||||
|
|
|
|||
1
docs/zh_CN/api-reference/protocols/esp_https_server.rst
Normal file
1
docs/zh_CN/api-reference/protocols/esp_https_server.rst
Normal file
|
|
@ -0,0 +1 @@
|
|||
.. include:: ../../../en/api-reference/protocols/esp_https_server.rst
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
Loading…
Reference in a new issue