The esp_secure_cert_mgr provides a simplified interface to access the PKI credentials of a device pre-provisioned with the
Espressif Provisioning Service. It provides the set of APIs that are required to access the contents of
the esp_secure_cert
partition.
A demo example has also been provided with the esp_secure_cert_mgr
, more details can be found out
in the example README
esp_secure_cert_mgr
in your projectThere are two ways to include esp_secure_cert_mgr
in your project:
i) Add esp_secure_cert_mgr
to your project with help of IDF component manager:
ii) Add esp_secure_cert_mgr
as an extra component in your project.
esp_secure_cert_mgr
with: git clone https://github.com/espressif/esp_secure_cert_mgr.git
esp_secure_cert_mgr
in ESP-IDF
with setting EXTRA_COMPONENT_DIRS
in CMakeLists.txt/Makefile of your project.For reference see Optional Project Variablesesp_secure_cert_mgr
in your projectesp_secure_cert_mgr
. Please include the file in your project to make use of the available APIs. The file also contains more details about the available APIs.With the Espressif Pre-Provisioning Service, the ESP modules are pre-provisioned with an encrypted RSA private key and respective X509 public certificate before they are shipped out to you. The PKI credentials can then be registered with the cloud service to establish a secure TLS channel for communication. With the pre-provisioning taking place in the factory, it provides a hassle-free PKI infrastructure to the Makers. You may use this repository to set up your test modules to validate that your firmware works with the pre-provisioned modules that you ordered through Espressif's pre-provisioning service.
When a device is pre-provisioned that means the PKI credentials are generated for the device. The PKI credentials are then stored in a partition named esp_secure_cert.
The esp_secure_cert
partition can be generated on host with help of configure_esp_secure_cert.py utility, more details about the utility can be found in the tools/README.
For esp devices that support DS peripheral, the pre-provisioning is done by leveraging the security benefit of the DS peripheral. In that case, all of the data which is present in the esp_secure_cert partition is completely secure.
When the device is pre-provisioned with help of the DS peripheral then by default the partition primarily contains the following data:
As listed above, the data only contains the public certificates and the encrypted private key and hence it is completely secure in itself. There is no need to further encrypt this data with any additional security algorithm.
The esp_secure_cert partition uses TLV format by default. Please take a look at the format document for more details.
esp_secure_cert_free_*
APIs for TLV configuration.-Wstrict-prototypes
CFLAG.cust_flash_tlv
as the default flash format.cust_flash
, nvs
.esp_secure_cert
partitionesp_secure_cert_get_*_addr
API, the contents can now be obtained through esp_secure_cert_get_*
API.esp_secure_cert_get_*
API:
The API now accepts char **buffer
instead of char *buffer
. It will allocate the required memory dynamically and directly if necessary and provide the respective pointer.The sample app demonstrates the use of APIs from esp_secure_cert_mgr to retrieve the contents of the esp_secure_cert partition. The example can also be used to verify the validity of the contents from the esp_secure_cert partition.
Before project configuration and build, be sure to set the correct chip target using idf.py set-target <chip_name>
.
The esp_secure_cert partition needs to be generated and flashed first with help of configure_esp_secure_cert.py script. See tools/README.md for more details.
Please ensure that appropriate type of esp_secure_cert partition has been set in your projects partitions.csv
file. Please refer the "esp_secure_cert partition" section in the component README for more details.
Build the project and flash it to the board, then run the monitor tool to view the serial output:
idf.py -p PORT flash monitor
(Replace PORT with the name of the serial port to use.)
(To exit the serial monitor, type Ctrl-]
.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
I (331) sample_app: Device Cert:
Length: 1233
-----BEGIN CERTIFICATE-----
.
.
-----END CERTIFICATE-----
I (441) sample_app: CA Cert:
Length: 1285
-----BEGIN CERTIFICATE-----
.
.
-----END CERTIFICATE-----
I (561) sample_app: Successfuly obtained ciphertext, ciphertext length is 1200
I (571) sample_app: Successfuly obtained initialization vector, iv length is 16
I (571) sample_app: RSA length is 2048
I (581) sample_app: Efuse key id 1
I (581) sample_app: Successfully obtained the ds context
I (831) sample_app: Ciphertext validated succcessfully
pre_prov
partitionFew of the modules which were pre-provisioned initially had the name of the pre-provisioning partition as pre_prov
. For the modules which have pre-provisioning partition of name esp_secure_cert
this part can be ignored.
pre_prov
partition of type cust_flash, please update the line refering to esp_secure_cert
partition in the partitions.csv with following:pre_prov, 0x3F, , 0xD000, 0x6000,
pre_prov
partition of type nvs.Copy to Clipboard
idf.py add-dependency "espressif/esp_secure_cert_mgr^2.3.1"
To create a project from this example, run:
Copy to Clipboard
idf.py create-project-from-example "espressif/esp_secure_cert_mgr^2.3.1:esp_secure_cert_app"
Copy to Clipboard
Copy to Clipboard