periodic update 03/22/2021 11:11 PDT

Author: robhath

doc_source/portingguide/afr-porting-pkcs.md

@@ -1,13 +1,12 @@
 # Porting the corePKCS11 library<a name="afr-porting-pkcs"></a>
 
-FreeRTOS uses the open standard PKCS \#11 “CryptoKi” API as the abstraction layer for cryptographic operations, including:
-+ Signing and verifying\.
-+ Storage and enumeration of X\.509 certificates\.
-+ Storage and management of cryptographic keys\.
+The corePKCS11 library contains a software\-based mock implementation of the PKCS \#11 interface \(API\) that uses the cryptographic functionality provided by Mbed TLS\. Storing private keys in general\-purpose flash memory can be convenient in evaluation and rapid prototyping scenarios\. In production scenarios, to reduce the threats of data theft and device duplication, we recommend that you use dedicated cryptographic hardware\. Cryptographic hardware includes components with features that prevent cryptographic secret keys from being exported\. 
 
-For more information, see [PKCS \#11 Cryptographic Token Interface Base Specification](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html)\.
+To use dedicated cryptographic hardware with FreeRTOS, port the PKCS \#11 API for the hardware you are using\. Generally, vendors for secure cryptoprocessors, such as Trusted Platform Module \(TPM\), Hardware Security Module \(HSM\), Secure Element, or any other type of secure hardware enclave, distribute a PKCS \#11 implementation with the hardware\. You can add the library to CMake and your IDE project, compile it and run the PKCS \#11 test suite\.
 
-Storing private keys in general\-purpose flash memory can be convenient in evaluation and rapid prototyping scenarios\. In production scenarios, to reduce the threats of data theft and device duplication, we recommend that you use dedicated cryptographic hardware\. Cryptographic hardware includes components with features that prevent cryptographic secret keys from being exported\. To use dedicated cryptographic hardware with FreeRTOS, you need to port the PKCS \#11 API to the hardware\. For information about the FreeRTOS corePKCS11 library, see [FreeRTOS corePKCS11 Library](https://docs.aws.amazon.com/freertos/latest/userguide/security-pkcs.html) in the *FreeRTOS User Guide*\.
+This section describes how to use the FreeRTOS corePKCS11 library as the basis of your own port of the PKCS \#11 API\. Only a subset of the PKCS \#11 standard is implemented, with a focus on operations involving asymmetric keys, random number generation, and hashing\. PKCS \#11 API calls are made by the TLS helper interface in order to perform TLS client authentication during `SOCKETS_Connect`\. PKCS \#11 API calls are also made by our one\-time developer provisioning workflow to import a TLS client certificate and private key for authentication to the AWS IoT MQTT broker\. Those two use cases, provisioning and TLS client authentication, require implementation of only a small subset of the PKCS \#11 interface standard\.
+
+For information about the FreeRTOS corePKCS11 library, see [FreeRTOS corePKCS11 Library](https://docs.aws.amazon.com/freertos/latest/userguide/security-pkcs.html) in the *FreeRTOS User Guide*\.
 
 ## Prerequisites<a name="porting-prereqs-pkcs"></a>
 
@@ -23,19 +22,19 @@ To port the corePKCS11 library, you need the following:
 
 **To port the corePKCS11 library**
 
-1. Port the PKCS \#11 API functions\.
+1. Port the PKCS \#11 API functions implemented by corePKCS11\.
 
    The PKCS \#11 API is dependent on the implementation of cryptographic primitives, such as SHA256 hashing and Elliptic Curve Digital Signature Algorithm \(ECDSA\) signing\.
 
-   The FreeRTOS implementation of PKCS \#11 uses the cryptographic primitives implemented in the mbedTLS library\. FreeRTOS includes a port for mbedTLS\. If your target hardware offloads crypto to a separate module, or if you want to use a software implementation of the cryptographic primitives other than mbedTLS, you need to modify the existing PKCS \#11 port\.
+   The FreeRTOS implementation of PKCS \#11 uses the cryptographic primitives implemented in the mbedTLS library\. FreeRTOS includes a port for mbedTLS\. If your target hardware offloads crypto to a separate module, or if you want to use a software implementation of the cryptographic primitives other than mbedTLS, you need to modify the existing PKCS \#11 implementation\.
 
-1. Port the PKCS \# 11 Platform Abstraction Layer \(PAL\) for device\-specific certificate and key storage\.
+1. Port the corePKCS11 Platform Abstraction Layer \(PAL\) for device\-specific certificate and key storage\.
 
    If you decide to use the FreeRTOS implementation of PKCS \#11, little customization is required to read and write cryptographic objects to non\-volatile memory \(NVM\), such as onboard flash memory\.
 
-   Cryptographic objects should be stored in a section of NVM that is not initialized and is not erased on device reprogramming\. Users of the PKCS \#11 library should be able to provision devices with credentials, and then reprogram the device with a new application that accesses these credentials through the PKCS \#11 interface\.
+   Cryptographic objects should be stored in a section of NVM that is not initialized and is not erased on device reprogramming\. Users of the corePKCS11 library should be able to provision devices with credentials, and then reprogram the device with a new application that accesses these credentials through the corePKCS11 interface\.
 
-   PKCS \#11 PAL ports must provide a location to store:
+   corePKCS11 PAL ports must provide a location to store:
    + The device client certificate\. 
    + The device client private key\.
    + The device client public key\.
@@ -101,7 +100,7 @@ To define a library's portable layer target in `CMakeLists.txt`, follow the inst
 
 The `CMakeLists.txt` template list file under `freertos/vendors/vendor/boards/board/CMakeLists.txt` includes example portable layer target definitions\. You can uncomment the definition for the library that you are porting, and modify it to fit your platform\.
 
-See the following example portable layer target definition for the corePKCS11 library that uses the mbedTLS\-based software implementation of PKCS \#11 and supplies a port\-specific PKCS \#11 PAL file\.
+See the following example portable layer target definition for the corePKCS11 library that uses the mbedTLS\-based software implementation of PKCS \#11 and supplies a port\-specific corePKCS11 PAL file\.
 
 ```
 # PKCS11
@@ -139,6 +138,6 @@ After you set up the library in the IDE project, you need to configure some othe
 
 ## Validation<a name="pkcs-validation"></a>
 
-To officially qualify a device for FreeRTOS, you need to validate the device's ported source code with AWS IoT Device Tester\. Follow the instructions in [ Using AWS IoT Device Tester for FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) in the FreeRTOS User Guide to set up Device Tester for port validation\. To test a specific library's port, the correct test group must be enabled in the `device.json` file in the Device Tester `configs` folder\.
+To officially qualify a device for FreeRTOS, you need to validate the device's ported source code with AWS IoT Device Tester\. Follow the instructions in [Using AWS IoT Device Tester for FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) in the FreeRTOS User Guide to set up Device Tester for port validation\. To test a specific library's port, the correct test group must be enabled in the `device.json` file in the Device Tester `configs` folder\.
 
 After you finish porting the corePKCS11 library to your device, you can start porting the TLS library\. See [Porting the TLS library](afr-porting-tls.md) for instructions\.

doc_source/portingguide/index.md

@@ -1,7 +1,7 @@
 # FreeRTOS Porting Guide
 
 -----
-*****Copyright © 2021 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.*****
+*****Copyright ©  Amazon Web Services, Inc. and/or its affiliates. All rights reserved.*****
 
 -----
 Amazon's trademarks and trade dress may not be used in 

doc_source/qualificationguide/index.md

@@ -1,7 +1,7 @@
 # FreeRTOS Qualification Guide
 
 -----
-*****Copyright © 2021 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.*****
+*****Copyright ©  Amazon Web Services, Inc. and/or its affiliates. All rights reserved.*****
 
 -----
 Amazon's trademarks and trade dress may not be used in 

doc_source/userguide/afr-bridgekeeper-dt-bt.md

@@ -16,6 +16,8 @@ To test the BLE capabilities of the device under test \(DUT\), you must have a R
 **To set up your Raspberry Pi to run BLE tests**
 
 1. Download the custom [Yocto image](https://docs.aws.amazon.com/freertos/latest/userguide/afr/IDT_AFR_BLE_RaspberryPi_1.0.0.rpi-sdimg) that contains the software required to perform the tests\.
+**Note**  
+The Yocto image should only be used for testing with AWS IoT Device Tester for FreeRTOS and not for any other purpose\.
 
 1. Flash the yocto image onto the SD card for Raspberry Pi\.
 

doc_source/userguide/afr-device-defender-library.md

@@ -8,4 +8,12 @@ You can use the AWS IoT Device Defender library to send security metrics from yo
 
 The library is written in C and designed to be compliant with [ISO C90](https://en.wikipedia.org/wiki/ANSI_C#C90) and [MISRA C:2012](https://www.misra.org.uk/MISRAHome/MISRAC2012/tabid/196/Default.aspx)\. The library has no dependencies on any additional libraries other than the standard C library\. It also doesn’t have any platform dependencies, such as threading or synchronization\. It can be used with any MQTT library and any [JSON](https://freertos.org/json/json-terminology.html) or [CBOR](https://cbor.io/) library\. The library has [proofs](https://www.cprover.org/cbmc/) showing safe memory use and no heap allocation, making it suitable for IoT microcontrollers, but also fully portable to other platforms\.
 
-The AWS IoT Device Defender library can be freely used and is distributed under the [MIT open source license](https://freertos.org/a00114.html)\.
+The AWS IoT Device Defender library can be freely used and is distributed under the [MIT open source license](https://freertos.org/a00114.html)\.
+
+
+****  
+
+| Code Size of AWS IoT Device Defender \(example generated with GCC for ARM Cortex\-M\) | File | With \-O1 Optimisation | With \-Os Optimisation | 
+| --- | --- | --- | --- | 
+| defender\.c | 1\.1K | 0\.6K | 
+| Total estimate | 1\.1K | 0\.6K | 

doc_source/userguide/backoffalgorithm-library.md

@@ -10,15 +10,10 @@ The library is written in C and designed to be compliant with [ISO C90](https://
 
 This library can be freely used and is distributed under the [MIT open source license](https://freertos.org/a00114.html)\.
 
-```
------------------------------------------------------------------------
-| Code Size of backoffAlgorithm                                       |
-|     (example generated with [GCC for ARM Cortex\-M](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads/9-2019-q4-major))                   |
-|---------------------------------------------------------------------|
-| File                | With -O1 Optimisation | With -Os Optimisation |
-|---------------------|-----------------------|-----------------------|
-| backoff_algorithm.c | 0.1K                  | 0.1K                  | 
-|---------------------|-----------------------|-----------------------|
-| Total estimate      | 0.1K                  | 0.1K                  |
------------------------------------------------------------------------
-```
+
+****  
+
+| Code Size of backoffAlgorithm \(example generated with GCC for ARM Cortex\-M\) | File | With \-O1 Optimisation | With \-Os Optimisation | 
+| --- | --- | --- | --- | 
+| backoff\_algorithm\.c | 0\.1K | 0\.1K | 
+| Total estimate | 0\.1K | 0\.1K | 

doc_source/userguide/core-http-demo.md

@@ -1,5 +1,7 @@
 # coreHTTP demos<a name="core-http-demo"></a>
 
+These demos can help you learn how to use the coreHTTP library\.
+
 **Topics**
 + [coreHTTP mutual authentication demo](core-http-ma-demo.md)
 + [coreHTTP basic Amazon S3 upload demo](core-http-s3-upload-demo.md)

doc_source/userguide/core-http.md

@@ -14,18 +14,11 @@ When using HTTP connections in IoT applications, we recommend that you use a sec
 
 This library can be freely used and is distributed under the [MIT open source license](https://freertos.org/a00114.html)\.
 
-```
----------------------------------------------------------------------------
-| Code Size of coreHTTP                                                   |
-|     (example generated with [GCC for ARM Cortex\-M](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads/9-2019-q4-major))                       |
-|-------------------------------------------------------------------------|
-| File                    | With -O1 Optimisation | With -Os Optimisation |
-|-------------------------|-----------------------|-----------------------|
-| core-http_client.c      | 3.0K                  | 2.4K                  |
-|-------------------------|-----------------------|-----------------------|
-| http_parser.c           | 15.7K                 | 13.0K                 |
-|   (third-party utility) |                       |                       |
-|-------------------------|-----------------------|-----------------------|
-| Total estimate          | 18.7K                 | 15.4K                 |
----------------------------------------------------------------------------
-```
+
+****  
+
+| Code Size of coreHTTP \(example generated with GCC for ARM Cortex\-M\) | File | With \-O1 Optimisation | With \-Os Optimisation | 
+| --- | --- | --- | --- | 
+| core\_http\_client\.c | 3\.1K | 2\.5K | 
+| http\_parser\.c \(third\-party utility\) | 15\.7K | 13\.0K | 
+| Total estimate | 18\.8K | 15\.5K | 

doc_source/userguide/coremqtt.md

@@ -21,19 +21,12 @@ When using MQTT connections in IoT applications, we recommended that you use a s
 
 This MQTT library doesn't have platform dependencies, such as threading or synchronization\. This library does have [proofs](https://www.cprover.org/cbmc/) that demonstrate safe memory use and no heap allocation, which makes it suitable for IoT microcontrollers, but also fully portable to other platforms\. It can be freely used, and is distributed under the [MIT open source license](https://freertos.org/a00114.html)\.
 
-```
----------------------------------------------------------------------------
-| Code Size of coreMQTT                                                   |
-|     (example generated with [GCC for ARM Cortex\-M](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads/9-2019-q4-major))                       |
-|-------------------------------------------------------------------------|
-| File                    | With -O1 Optimisation | With -Os Optimisation |
-|-------------------------|-----------------------|-----------------------|
-| core_mqtt.c             | 3.0K                  | 2.6K                  |
-|-------------------------|-----------------------|-----------------------|
-| core_mqtt_state.c       | 1.4K                  | 1.1K                  |
-|-------------------------|-----------------------|-----------------------|
-| core_mqtt_serializer.c  | 2.5K                  | 2.0K                  |
-|-------------------------|-----------------------|-----------------------|
-| Total estimate          | 6.9K                  | 5.7K                  |
----------------------------------------------------------------------------
-```
+
+****  
+
+| Code Size of coreMQTT \(example generated with GCC for ARM Cortex\-M\) | File | With \-O1 Optimisation | With \-Os Optimisation | 
+| --- | --- | --- | --- | 
+| core\_mqtt\.c | 3\.0K | 2\.6K | 
+| core\_mqtt\_state\.c | 1\.4K | 1\.1K | 
+| core\_mqtt\_serializer\.c | 2\.5K | 2\.0K | 
+| Total estimate | 6\.9K | 5\.7K | 

doc_source/userguide/create-ota-user-policy.md

@@ -41,6 +41,7 @@ To grant your IAM user the required permissions, create an OTA user policy and t
                    "s3:PutBucketVersioning",
                    "s3:GetBucketLocation",
                    "s3:GetObjectVersion",
+                   "s3:ListBucketVersions",
                    "acm:ImportCertificate",
                    "acm:ListCertificates",
                    "iot:*",

doc_source/userguide/dev-tester-prereqs.md

@@ -17,9 +17,9 @@ where <FREERTOS\_RELEASE\_VERSION> is a version of FreeRTOS \(for example, 20200
 Windows has a path length limitation of 260 characters\. The path structure of FreeRTOS is many levels deep, so if you are using Windows, keep your file paths under the 260\-character limit\. For example, clone FreeRTOS to `C:\FreeRTOS` rather than `C:\Users\username\programs\projects\myproj\FreeRTOS\`\.
 
 ## LTS Qualification \(Qualification for FreeRTOS that uses LTS libraries\)<a name="lts-qualification-dev-tester-afr"></a>
-+ In order for your microcontroller to be designated as supporting the long\-term support \(LTS\) version of FreeRTOS in the AWS Partner Device Catalog, you must provide a manifest file\. For more information, see the [ FreeRTOS Qualification Checklist](https://docs.aws.amazon.com/freertos/latest/qualificationguide/afq-checklist.html) in the *FreeRTOS Qualification Guide*\.
-+ In order to validate that your microcontroller supports the LTS version of FreeRTOS and qualify it for submission to the AWS Partner Device Catalog, you must use AWS IoT Device Tester \(IDT\) for FreeRTOS v4\.0\.0\.
-+ At this time, support for LTS based versions of FreeRTOS is limited to the 202012\.00 version of FreeRTOS\. 
++ In order for your microcontroller to be designated as supporting long\-term support \(LTS\) based versions of FreeRTOS in the AWS Partner Device Catalog, you must provide a manifest file\. For more information, see the [ FreeRTOS Qualification Checklist](https://docs.aws.amazon.com/freertos/latest/qualificationguide/afq-checklist.html) in the *FreeRTOS Qualification Guide*\.
++ At this time, in order to validate that your microcontroller supports LTS based versions of FreeRTOS and qualify it for submission to the AWS Partner Device Catalog, you must use AWS IoT Device Tester \(IDT\) with FreeRTOS Qualification \(FRQ\) test suite version v1\.4\.x\.
++ At this time, support for LTS based versions of FreeRTOS is limited to the 202012\.xx version of FreeRTOS\. 
 
 ## Download IDT for FreeRTOS<a name="download-dev-tester-afr"></a>