alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-09-19 14:26:01 -04:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs: Add section for server verification (esp_https_ota)

Browse Source 
- Updated OTA example README
This commit is contained in:
Laukik Hase 2022-04-26 18:04:56 +05:30
parent f38e6cb4fa
commit 1a7eac2d69
No known key found for this signature in database
GPG Key ID: 11C571361F51A199
3 changed files with 17 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/api-reference/protocols/esp_tls.rst
View File

@ -40,6 +40,8 @@ The ESP-TLS component has a file :component_file:`esp-tls/esp_tls.h` which cont
of the two SSL/TLS Libraries between mbedtls and wolfssl for its operation. API specific to mbedtls are present in :component_file:`esp-tls/private_include/esp_tls_mbedtls.h` and API
specific to wolfssl are present in :component_file:`esp-tls/private_include/esp_tls_wolfssl.h`.
.. _esp_tls_server_verification:
TLS Server verification
-----------------------

8
docs/en/api-reference/system/esp_https_ota.rst
View File

@ -32,6 +32,14 @@ Application Example
return ESP_OK;
}
Server Verification
-------------------
Please refer to :ref:`ESP-TLS: TLS Server Verification <esp_tls_server_verification>` for more information on server verification. The root certificate (in PEM format) needs to be provided to the :cpp:member:`esp_http_client_config_t::cert_pem` member.
.. note:: The server-endpoint **root** certificate should be used for verification instead of any intermediate ones from the certificate chain. The reason being that the root certificate has the maximum validity and usually remains the same for a long period of time. Users can also use the ``ESP x509 Certificate Bundle`` feature for verification, which covers most of the trusted root certificates (using the :cpp:member:`esp_http_client_config_t::crt_bundle_attach` member).
Partial Image Download over HTTPS
---------------------------------

13
examples/system/ota/README.md
View File

@ -140,14 +140,14 @@ If you see this error, check that the configured (and actual) flash size is larg
Make sure to run "idf.py erase-flash" after making changes to the partition table.
### Local https server
### Local HTTPS Server
Running a local https server might be tricky in some cases (due to self signed certificates, or potential issues with `openssl s_server` on Windows). Here are some suggestions for alternatives:
* Run a plain HTTP server to test the connection. (Note that using a plain http is **not secure** and should only be used for testing)
- Execute `python -m http.server 8070` in the directory with the firmware image
- Use http://<host-ip>:8070/<firmware-name> as the firmware upgrade URL
- Enable *Allow HTTP for OTA* (`CONFIG_ESP_HTTPS_OTA_ALLOW_HTTP`) in `Component config -> ESP HTTPS OTA` so the URI without TLS is accepted
* Start the https server using [example_test](simple_ota_example/example_test.py) with two or more parameters: `example_test.py <BIN_DIR> <PORT> [CERT_DIR]`, where:
* Start the HTTPS server using [example_test](simple_ota_example/example_test.py) with two or more parameters: `example_test.py <BIN_DIR> <PORT> [CERT_DIR]`, where:
- `<BIN_DIR>` is a directory containing the image and by default also the certificate and key files:`ca_cert.pem` and `ca_key.pem`
- `<PORT>` is the server's port, here `8070`
- `[CERT_DIR]` is an optional argument pointing to a specific directory with the certificate and key file.
@ -166,9 +166,10 @@ echo "" | openssl s_client -showcerts -connect raw.githubusercontent.com:443 | s
Please note that URL used here is `raw.githubusercontent.com`. This URL allows raw access to files hosted on github.com repository. Additionally, command above copies last certificate from chain of certs as the CA root cert of server.
---
**NOTE**
### Using HTTPS Server in Production
For examples using certificate bundle approach (e.g., `simple_ota_example`), it already has most common root certificates and hence there is no need to add any additional certs.
Please refer to [ESP-TLS: TLS Server Verification](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_tls.html#tls-server-verification) for more information on server verification. The root certificate (in PEM format) needs to be provided to the `cert_pem` member of the `esp_http_client_config_t` configuration.
---
Note that the server-endpoint **root** certificate should be used for verification instead of any intermediate ones from the certificate chain. The reason being that the root certificate has the maximum validity and usually remains the same for a long period of time.
Users can also use the `ESP x509 Certificate Bundle` feature for verification, which covers most of the trusted root certificates (using the `crt_bundle_attach` member of the `esp_http_client_config_t` configuration). There is no need to add any additional certificates. Please refer to the [simple_ota_example](simple_ota_example) for its usage.