Skip to content

Commit

Permalink
Merge branch 'docs/add-migration-guide' into 'master'
Browse files Browse the repository at this point in the history 
Adds Migration Guide and updates README

See merge request app-frameworks/esp-aws-iot!48
  • Loading branch information
@avsheth
avsheth committed Jan 17, 2023
2 parents 82f5eaa + 4918e2c commit f7f742c
Show file tree
Hide file tree
Showing 3 changed files with 126 additions and 92 deletions.
27 changes: 27 additions & 0 deletions MigrationGuide.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Migration Guide for esp-aws-iot Releases

## esp-aws-iot Release 202012.04-LTS (23rd August 2022) to esp-aws-iot Release 202210.01-LTS (14th January 2023)

1. Change in `NetworkContext` struct

- "Pem" has been removed from member names, the new member names are as follows: `pcServerRootCA`, `pcClientCert`, `pcClientKey`.
- `pcServerRootCASize`, `pcClientCertSize`, `pcClientKeySize` members have been added.
- It is now required to set these `*Size` members in addition to the pointers to the certificates.

**Example:**

**Old Code Snippet**:
```c
pNetworkContext->pcClientCertPem = client_cert_pem_start;
```

**New Code Snippet**:
```c
pNetworkContext->pcClientCert = client_cert_start;
pNetworkContext->pcClientCertSize = client_cert_end - client_cert_start;
```

2. This releases includes a version >=v2.0.0 of the `coreMQTT` library.
Please refer to the [coreMQTT Migration Guide](https://github.com/FreeRTOS/coreMQTT/blob/main/MigrationGuide.md) for more details.

3. The `*_USE_DS_PERIPHERAL` and `*_USE_SECURE_ELEMENT` config options have been removed and no longer need to be set while using `coreMQTT` and `coreHTTP` libraries.
102 changes: 99 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,114 @@ This SDK enables AWS IoT cloud connectivity with ESP32-based platforms using the
```
git clone -b "<name_of_the_release_branch>" --recursive https://github.com/espressif/esp-aws-iot
```
For example: To clone just `release/202012.04-LTS`, you may run:
For example: To clone just `release/202210.01-LTS`, you may run:
```
git clone -b "release/202012.04-LTS" --recursive https://github.com/espressif/esp-aws-iot
git clone -b "release/202210.01-LTS" --recursive https://github.com/espressif/esp-aws-iot
```
- Please refer to https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html for setting up ESP-IDF
- ESP-IDF can be downloaded from https://github.com/espressif/esp-idf/
- This SDK supports `release/v5.0`, `release/v4.4` and `release/v4.3` of ESP-IDF.
- Please set your branch to the IDF release that you would like to use, and pull in the latest changes.
> **Note**: Please read [Support Policy](#support-policy) below for more details.
- Please refer to the [example README](examples/README.md) for more information on setting up examples.
- For a production-ready starting point for making applications that connect to AWS IoT Core using `esp-aws-iot`, refer to the [reference example](https://github.com/FreeRTOS/iot-reference-esp32c3).
- Please refer to the [Security Guide](examples/ota/SecurityGuide.md) for steps to enable Security Features on your Espressif chip.
- This SDK supports multiple ways to securely store the PKI credentials.
- The default method is to use PKI credentials which are embedded in the binary, using the certs from the `certs/` in every example.
- For using Secure Element (ATECC608A), you will need to use [esp-cryptoauthlib](https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf).
- The Security Guide includes detailed steps and pointers to configure and use the Digital Signature Peripheral on supported chips.
- The Security Guide includes detailed steps and pointers to configure and use the Digital Signature Peripheral on supported chips, using [esp_secure_cert_mgr](https://components.espressif.com/components/espressif/esp_secure_cert_mgr).
## Supported SoCs
The following table shows esp-aws-iot support with the ESP-IDF support of Espressif SoCs:
![alt text][supported] and ![alt text][unsupported] denote supported and unsupported status, respectively.
<table>
<thead>
<tr align="center">
<th rowspan="2">SoC</th>
<th rowspan="2">Supported IDF Version</th>
<th colspan="2">esp-aws-iot Release</th>
</tr>
<tr align="center">
<th>202012.04-LTS</th>
<th>202210.01-LTS</th>
</tr>
</thead>
<tbody>
<tr align="center">
<td rowspan="3">ESP32</td>
<td>IDF v4.3</td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td>IDF v4.4</td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td>IDF v5.0</td>
<td></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td rowspan="3">ESP32-S2</td>
<td>IDF v4.3</td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td>IDF v4.4</td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td>IDF v5.0</td>
<td></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td rowspan="3">ESP32-C3</td>
<td>IDF v4.3</td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td>IDF v4.4</td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td>IDF v5.0</td>
<td></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td rowspan="2">ESP32-S3</td>
<td>IDF v4.4</td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td>IDF v5.0</td>
<td></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
<tr align="center">
<td>ESP32-C2</td>
<td>IDF v5.0</td>
<td></td>
<td><img src="https://img.shields.io/badge/-supported-green"/></a></td>
</tr>
</tbody>
</table>
[supported]: https://img.shields.io/badge/-supported-green "supported"
[unsupported]: https://img.shields.io/badge/-unsupported-red "unsupported"
## Support Policy
IDF version support for esp-aws-iot releases is based on [IDF Release Support Schedule](https://github.com/espressif/esp-idf#esp-idf-release-support-schedule).
For example, support for IDF v4.3 for Release 202210.01-LTS will expire on 15th Dec 2023.
89 changes: 0 additions & 89 deletions libraries/corePKCS11/port/iot_crypto.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,95 +96,6 @@ typedef struct SignatureVerificationState
}
#endif /* ifdef CONFIG_MEDTLS_USE_AFR_MEMORY */

/*-----------------------------------------------------------*/
/*--------- mbedTLS threading functions for FreeRTOS --------*/
/*--------------- See MBEDTLS_THREADING_ALT -----------------*/
/*-----------------------------------------------------------*/

/**
* @brief Implementation of mbedtls_mutex_init for thread-safety.
*
*/
// void aws_mbedtls_mutex_init( mbedtls_threading_mutex_t * mutex )
// {
// mutex->mutex = xSemaphoreCreateMutex();

// if( mutex->mutex != NULL )
// {
// mutex->is_valid = 1;
// }
// else
// {
// mutex->is_valid = 0;
// CRYPTO_PRINT( ( "Failed to initialize mbedTLS mutex.\r\n" ) );
// }
// }

// /**
// * @brief Implementation of mbedtls_mutex_free for thread-safety.
// *
// */
// void aws_mbedtls_mutex_free( mbedtls_threading_mutex_t * mutex )
// {
// if( mutex->is_valid == 1 )
// {
// vSemaphoreDelete( mutex->mutex );
// mutex->is_valid = 0;
// }
// }

// /**
// * @brief Implementation of mbedtls_mutex_lock for thread-safety.
// *
// * @return 0 if successful, MBEDTLS_ERR_THREADING_MUTEX_ERROR if timeout,
// * MBEDTLS_ERR_THREADING_BAD_INPUT_DATA if the mutex is not valid.
// */
// int aws_mbedtls_mutex_lock( mbedtls_threading_mutex_t * mutex )
// {
// int ret = MBEDTLS_ERR_THREADING_BAD_INPUT_DATA;

// if( mutex->is_valid == 1 )
// {
// if( xSemaphoreTake( mutex->mutex, portMAX_DELAY ) )
// {
// ret = 0;
// }
// else
// {
// ret = MBEDTLS_ERR_THREADING_MUTEX_ERROR;
// CRYPTO_PRINT( ( "Failed to obtain mbedTLS mutex.\r\n" ) );
// }
// }

// return ret;
// }

// /**
// * @brief Implementation of mbedtls_mutex_unlock for thread-safety.
// *
// * @return 0 if successful, MBEDTLS_ERR_THREADING_MUTEX_ERROR if timeout,
// * MBEDTLS_ERR_THREADING_BAD_INPUT_DATA if the mutex is not valid.
// */
// int aws_mbedtls_mutex_unlock( mbedtls_threading_mutex_t * mutex )
// {
// int ret = MBEDTLS_ERR_THREADING_BAD_INPUT_DATA;

// if( mutex->is_valid == 1 )
// {
// if( xSemaphoreGive( mutex->mutex ) )
// {
// ret = 0;
// }
// else
// {
// ret = MBEDTLS_ERR_THREADING_MUTEX_ERROR;
// CRYPTO_PRINT( ( "Failed to unlock mbedTLS mutex.\r\n" ) );
// }
// }

// return ret;
// }

/*-----------------------------------------------------------*/

/**
Expand Down

0 comments on commit f7f742c

Please sign in to comment.