Skip to content

Commit adb5bd6

Browse files
hrushikesh430hrushikesh430
committed
feat(esp_encrypted_img): Added pre_encrypted_ota example
Added the pre_encrypted_ota example in esp_encrypted_img component Closes IDF-7818
1 parent 9634f8d commit adb5bd6

File tree

14 files changed

+623
-11
lines changed

14 files changed

+623
-11
lines changed

‎.github/workflows/build_and_run_apps.yml

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,9 @@ jobs:
7272
fail-fast: false
7373
matrix:
7474
idf_ver:
75-
- "release-v5.0"
76-
- "release-v5.1"
77-
- "release-v5.2"
75+
# - "release-v5.0"
76+
# - "release-v5.1"
77+
# - "release-v5.2"
7878
- "release-v5.3"
7979
- "latest"
8080
parallel_index: [1,2,3,4,5] # Update --parallel-count below when changing this
@@ -122,25 +122,25 @@ jobs:
122122
fail-fast: false
123123
matrix:
124124
idf_ver:
125-
- "release-v5.0"
126-
- "release-v5.1"
127-
- "release-v5.2"
125+
# - "release-v5.0"
126+
# - "release-v5.1"
127+
# - "release-v5.2"
128128
- "release-v5.3"
129129
- "latest"
130130
runner:
131-
- runs-on: "esp32"
131+
- runs-on: '["self-hosted", "linux", "docker", "esp32"]'
132132
marker: "generic"
133133
target: "esp32"
134-
- runs-on: "ESP32-ETHERNET-KIT"
134+
- runs-on: '["self-hosted", "linux", "ESP32-ETHERNET-KIT"]'
135135
marker: "ethernet"
136136
target: "esp32"
137-
- runs-on: "spi_nand_flash"
137+
- runs-on: '["self-hosted", "linux", "docker", "spi_nand_flash"]'
138138
marker: "spi_nand_flash"
139139
target: "esp32"
140140
env:
141141
TEST_RESULT_NAME: test_results_${{ matrix.runner.target }}_${{ matrix.runner.marker }}_${{ matrix.idf_ver }}
142142
TEST_RESULT_FILE: test_results_${{ matrix.runner.target }}_${{ matrix.runner.marker }}_${{ matrix.idf_ver }}.xml
143-
runs-on: [self-hosted, linux, docker, "${{ matrix.runner.runs-on }}"]
143+
runs-on: ${{ fromjson(matrix.runner.runs-on) }}
144144
container:
145145
image: python:3.11-bookworm
146146
options: --privileged # Privileged mode has access to serial ports
@@ -153,7 +153,7 @@ jobs:
153153
- name: Install Python packages
154154
env:
155155
PIP_EXTRA_INDEX_URL: "https://dl.espressif.com/pypi/"
156-
run: pip install --prefer-binary cryptography pytest-embedded pytest-embedded-serial-esp pytest-embedded-idf pytest-custom_exit_code
156+
run: pip install --prefer-binary cryptography pytest-embedded pytest-embedded-serial-esp pytest-embedded-idf pytest-custom_exit_code rangehttpserver
157157
- name: Run apps
158158
run: |
159159
python3 .github/get_pytest_args.py --target=${{ matrix.runner.target }} -v 'build_info*.json' pytest-args.txt

‎esp_encrypted_img/examples/pre_encrypted_ota/CMakeLists.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# For more information about build system see
2+
# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
3+
# The following five lines of boilerplate have to be in your project's
4+
# CMakeLists in this exact order for cmake to work correctly
5+
cmake_minimum_required(VERSION 3.16)
6+
7+
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
8+
project(pre_encrypted_ota)

‎esp_encrypted_img/examples/pre_encrypted_ota/README.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
2+
| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- |
3+
4+
# Encrypted Binary OTA
5+
6+
This example demonstrates OTA updates with pre-encrypted binary using `esp_encrypted_img` component's APIs and tool.
7+
8+
Pre-encrypted firmware binary must be hosted on OTA update server.
9+
This firmware will be fetched and then decrypted on device before being flashed.
10+
This allows firmware to remain `confidential` on the OTA update channel irrespective of underlying transport (e.g., non-TLS).
11+
12+
* **NOTE:** Pre-encrypted OTA is a completely different scheme from Flash Encryption. Pre-encrypted OTA helps in ensuring the confidentiality of the firmware on the network channel, whereas Flash Encryption is intended for encrypting the contents of the ESP32's off-chip flash memory.
13+
14+
> [!CAUTION]
15+
> Using the Pre-encrypted Binary OTA provides confidentiality of the firmware, but it does not ensure authenticity of the firmware. For ensuring that the firmware is coming from trusted source, please consider enabling secure boot feature along with the Pre-encrypted binary OTA. Please refer to security guide in the ESP-IDF docs for more details.
16+
17+
## ESP Encrypted Image Abstraction Layer
18+
19+
This example uses `esp_encrypted_img` component hosted at [idf-extra-components/esp_encrypted_img](https://github.com/espressif/idf-extra-components/blob/master/esp_encrypted_img) and available though the [IDF component manager](https://components.espressif.com/component/espressif/esp_encrypted_img).
20+
21+
Please refer to its documentation [here](https://github.com/espressif/idf-extra-components/blob/master/esp_encrypted_img/README.md) for more details.
22+
23+
24+
## How to use the example
25+
26+
To create self-signed certificate and key, refer to README.md in upper level 'examples' directory. This certificate should be flashed with binary as it will be used for connection with server.
27+
28+
### Creating RSA key for encryption
29+
30+
You can generate a public and private RSA key pair using following commands:
31+
32+
`openssl genrsa -out rsa_key/private.pem 3072`
33+
34+
This generates a 3072-bit RSA key pair, and writes them to a file.
35+
36+
Private key is required for decryption process and is used as input to the `esp_encrypted_img` component. Private key can either be embedded into the firmware or stored in NVS.
37+
38+
Encrypted image generation tool will derive public key (from private key) and use it for encryption purpose.
39+
40+
* **NOTE:** We highly recommend the use of flash encryption or NVS encryption to protect the RSA Private Key on the device.
41+
* **NOTE:** RSA key provided in the example is for demonstration purpose only. We recommend to create a new key for production applications.
42+
43+
## Build and Flash example
44+
45+
```
46+
idf.py build flash
47+
```
48+
49+
* An encrypted image is automatically generated by build system. Upload the generated encrypted image (`build/pre_encrypted_ota_secure.bin`) to a server for performing OTA update.
50+
51+
52+
## Configuration
53+
54+
Refer the README.md in the parent directory for the setup details.

‎esp_encrypted_img/examples/pre_encrypted_ota/main/CMakeLists.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
idf_build_get_property(project_dir PROJECT_DIR)
2+
idf_component_register(SRCS "pre_encrypted_ota.c"
3+
INCLUDE_DIRS "."
4+
EMBED_TXTFILES ${project_dir}/server_certs/ca_cert.pem
5+
${project_dir}/rsa_key/private.pem)
6+
7+
create_esp_enc_img(${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin
8+
${project_dir}/rsa_key/private.pem ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}_secure.bin app)

‎esp_encrypted_img/examples/pre_encrypted_ota/main/Kconfig.projbuild

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
menu "Example Configuration"
2+
3+
config EXAMPLE_FIRMWARE_UPGRADE_URL
4+
string "firmware upgrade url endpoint"
5+
default "https://192.168.0.3:8070/hello_world.bin"
6+
help
7+
URL of server which hosts the encrypted firmware image.
8+
9+
config EXAMPLE_FIRMWARE_UPGRADE_URL_FROM_STDIN
10+
bool
11+
default y if EXAMPLE_FIRMWARE_UPGRADE_URL = "FROM_STDIN"
12+
13+
config EXAMPLE_SKIP_COMMON_NAME_CHECK
14+
bool "Skip server certificate CN fieldcheck"
15+
default n
16+
help
17+
This allows you to skip the validation of OTA server certificate CN field.
18+
19+
config EXAMPLE_SKIP_VERSION_CHECK
20+
bool "Skip firmware version check"
21+
default n
22+
help
23+
This allows you to skip the firmware version check.
24+
25+
config EXAMPLE_OTA_RECV_TIMEOUT
26+
int "OTA Receive Timeout"
27+
default 5000
28+
help
29+
Maximum time for reception
30+
31+
config EXAMPLE_ENABLE_PARTIAL_HTTP_DOWNLOAD
32+
bool "Enable partial HTTP download"
33+
default n
34+
help
35+
This enables use of Range header in esp_https_ota component.
36+
Firmware image will be downloaded over multiple HTTP requests.
37+
38+
config EXAMPLE_HTTP_REQUEST_SIZE
39+
int "HTTP request size"
40+
default MBEDTLS_SSL_IN_CONTENT_LEN
41+
depends on EXAMPLE_ENABLE_PARTIAL_HTTP_DOWNLOAD
42+
help
43+
This options specifies HTTP request size. Number of bytes specified
44+
in this option will be downloaded in single HTTP request.
45+
endmenu

‎esp_encrypted_img/examples/pre_encrypted_ota/main/idf_component.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
dependencies:
2+
espressif/esp_encrypted_img:
3+
version: "^2.0.1"
4+
override_path: ../../../
5+
protocol_examples_common:
6+
path: ${IDF_PATH}/examples/common_components/protocol_examples_common

0 commit comments

Comments
 (0)