espressif/esp_secure_cert_mgr

readme

# ESP Secure Certificate Manager

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](https://github.com/espressif/esp_secure_cert_mgr/blob/main/examples/esp_secure_cert_app/README.md)

## Usage Guidelines

### 1) Include `esp_secure_cert_mgr` in your project
There 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:
* The component is hosted at https://components.espressif.com/component/espressif/esp_secure_cert_mgr. Please use the same link to obtain the latest available version of the component along with the instructions on how to add it to your project.
* Additional details about using a component through IDF component manager can be found [here](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html#using-with-a-project)

ii) Add `esp_secure_cert_mgr` as an extra component in your project.

* Download `esp_secure_cert_mgr` with:
```
    git clone https://github.com/espressif/esp_secure_cert_mgr.git
```
* Include  `esp_secure_cert_mgr` in `ESP-IDF` with setting `EXTRA_COMPONENT_DIRS` in CMakeLists.txt/Makefile of your project.For reference see [Optional Project Variables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#optional-project-variables)

### 2) Use the public API provided by `esp_secure_cert_mgr` in your project
* The file [esp_secure_cert_read.h](https://github.com/espressif/esp_secure_cert_mgr/blob/main/include/esp_secure_cert_read.h) contains the public APIs provided by the `esp_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.

## What is Pre-Provisioning?

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.

## ESP Secure Cert Partition

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](https://github.com/espressif/esp_secure_cert_mgr/blob/main/tools/configure_esp_secure_cert.py) utility, more details about the utility can be found in the [tools/README](https://github.com/espressif/esp_secure_cert_mgr/tree/main/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:
1) Device certificate: It is the public key/ certificate for the device's private key. It is used in TLS authentication.
2) CA certificate: This is the certificate of the CA which is used to sign the device cert.
3) Ciphertext: This is the encrypted private key of the device. The ciphertext is encrypted using the DS peripheral, thus it is completely safe to store on the flash.

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.

### Partition Format

The *esp_secure_cert* partition uses TLV format by default. Please take a look at the [format document](https://github.com/espressif/esp_secure_cert_mgr/tree/main/docs/format.md) for more details.

changelog

# This file contains the list of changes across different versions

## v2.4.1
* Added a new API `esp_secure_cert_get_tlv_info` for obtaining TLV information
* Added `esp_secure_cert_free_tlv_info` API for freeing TLV information.
* Added `esp_secure_cert_iterate_to_next_tlv` API for iterating the TLV entries
* Updated the API documentation for available `esp_secure_cert_get_*` APIs

## v2.4.0 (yanked)
* Added support for multiple entries of the same type by adding a new field called subtype.
* Fixed API for obtaining CA cert for the legacy flash formats (9b091ee)

### Yank explanation
This version was later yanked due to following reason.

* The API `esp_secure_cert_tlv_get_addr` which was made public in this version has incorrect documentation and the respective free API was not present.
* The changes in this version also modifiy the behaviour of existing APIs to obtain the TLV entry of latest subtype. While no current users shall be affected, this may cause inconsistency in the available API usage going forward.

Please note that the yanked version does not affect any of existing users. The yanking is done due to future API usage considerations and to avoid any possible inconsistencies.

## v2.3.1
* Make esp_secure_cert_get_key_type API available for DS peripheral case as well.

## v2.3.0
* Added support to obtain the priv key type
* Added support for getting the efuse key id for priv key

## v2.2.0
* tools: Support DER encoded private keys when creating secure cert partition on host
### Breaking changes in v2.2.0
* Updated the order of arguments for esp_pbkdf2_hmac_sha256 API to match it with corresponding mbedTLS API

## v2.1.0
* Added support for HMAC based ECDSA key derivation with PBKDF2-HMAC-SHA256
* Fixed build failure when example is setup through component manager

## v2.0.8
* Fix for supporting IDF v4.3

## v2.0.7
* Updated documentation regarding TLV format
* Fixed priv_key free API when HMAC based encryption scheme is enabled.

## v2.0.6
* Added HMAC based encryption scheme to protect private key data
* Added support for private key validation in the esp_secure_cert_app
* Added support of configurable esp_secure_cert partition offset in for configure_esp_secure_cert.py utility

## v2.0.5
* Fixed targets in Kconfig to reflect DS Peripheral compatibility

## v2.0.4
* Add implementation of `esp_secure_cert_free_*` APIs for TLV configuration.

## v2.0.3
* Added C linkage so that C++ code can find the definitions for secure cert APIs.
* Minor documentation fixes.

## v2.0.2
* Updated reference to the new esp_partition component (IDFv5.0)

## v2.0.1
* Added fixes for build failures with `-Wstrict-prototypes` CFLAG.
* Added fix for build failure with toolchain change in IDFv4.x and IDFv5.x

## v2.0.0
* Added esp-secure-cert-tool to PyPi.
* Restructure esp-secure-cert-tool
### Breaking changes in v2.0.0
* Added the support for TLV format for storing data in esp_secure_cert partition.
* Make the TLV `cust_flash_tlv` as the default flash format.
* Marked all the supported flash formats before TLV as legacy: `cust_flash`, `nvs`.
* esp_secure_cert_app: Updated the partition table for the example

## v1.0.3
* esp_secure_cert API now Dynamically identify the type of partitionand access the data accordingly
* esp_secure_cert_app: Enable support for target esp32
* Added tests based on qemu
* Added priv_key functionality to the configure_esp_secure_cert.py script.
### Breaking changes in v1.0.3
* Removed all the configuration options related to selecting the type of `esp_secure_cert` partition
* Remove `esp_secure_cert_get_*_addr` API, the contents can now be obtained through `esp_secure_cert_get_*` API.
* Remove APIs to obain the contents of the DS contexts e.g. efuse key id, ciphertext, iv etc. The contents can be accesed from inside the DS context which can be obtained through respective API.
* Breaking change in the `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.

                                        
                                        # ESP Secure Certificate Application

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.

## Requirements
* The device must be pre-provisioned and have an *esp_secure_cert* partition.

## How to use the example
Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
### Configure the project

* The *esp_secure_cert* partition needs to be generated and flashed first with help of [configure_esp_secure_cert.py](https://github.com/espressif/esp_secure_cert_mgr/blob/main/tools/configure_esp_secure_cert.py) script. See [tools/README.md](https://github.com/espressif/esp_secure_cert_mgr/blob/main/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](https://github.com/espressif/esp_secure_cert_mgr#readme) for more details.

### Build and Flash

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.

### Example Output
```
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
```

## Additional configurations for `pre_prov` partition
Few 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.

* For modules with `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,
```
* No change is necessary for `pre_prov` partition of type *nvs*.