Repository files navigation

• Overview
  • License
  • Features
    • coreMQTT
    • coreHTTP
    • coreJSON
    • corePKCS11
    • AWS IoT Device Shadow
    • AWS IoT Jobs
    • AWS IoT Device Defender
    • AWS IoT Over-the-air Update Library
    • AWS IoT Fleet Provisoning
    • AWS SigV4
    • backoffAlgorithm
  • Sending metrics to AWS IoT
• Versioning
• Releases and Documentation
  • 202211.00
  • 202108.00
  • 202103.00
  • 202012.01
  • 202011.00
  • 202009.00
  • v3.1.5
• Porting Guide for 202009.00 and newer releases
  • Porting coreMQTT
  • Porting coreHTTP
  • Porting AWS IoT Device Shadow
  • Porting AWS IoT Device Defender
  • Porting AWS IoT Over-the-air Update
• Migration guide from v3.1.5 to 202009.00 and newer releases
  • MQTT Migration
  • Shadow Migration
  • Jobs Migration
• Branches
  • main
  • v4_beta_deprecated
• Getting Started
  • Cloning
  • Configuring Demos
    • Prerequisites
      • Build Dependencies
    • AWS IoT Account Setup
    • Configuring mutual authentication demos of MQTT and HTTP
    • Configuring AWS IoT Device Defender and AWS IoT Device Shadow demos
    • Configuring the AWS IoT Fleet Provisioning demo
    • Configuring the S3 demos
    • Setup for AWS IoT Jobs demo
    • Setup for the Greengrass local auth demo
    • Prerequisites for the AWS Over-The-Air Update (OTA) demos
    • Scheduling an OTA Update Job
  • Building and Running Demos
    • Build a single demo
    • Build all configured demos
    • Running corePKCS11 demos
    • Alternative option of Docker containers for running demos locally
      • Installing Mosquitto to run MQTT demos locally
      • Installing httpbin to run HTTP demos locally
• Generating Documentation

The AWS IoT Device SDK for Embedded C (C-SDK) is a collection of C source files under theMIT open source license that can be used in embedded applications to securely connect IoT devices toAWS IoT Core. It contains MQTT client, HTTP client, JSON Parser, AWS IoT Device Shadow, AWS IoT Jobs, and AWS IoT Device Defender libraries. This SDK is distributed in source form, and can be built into customer firmware along with application code, other libraries and an operating system (OS) of your choice. These libraries are only dependent on standard C libraries, so they can be ported to various OS's - from embedded Real Time Operating Systems (RTOS) to Linux/Mac/Windows. You can find sample usage of C-SDK libraries on POSIX systems using OpenSSL (e.g.Linux demos in this repository), and onFreeRTOS using mbedTLS (e.g.FreeRTOS demos inFreeRTOS repository).

For the latest release of C-SDK, please see the section forReleases and Documentation.

C-SDK includes libraries that are part of theFreeRTOS 202210.01 LTS release. Learn more about the FreeRTOS 202210.01 LTS libraries byclicking here.

The C-SDK libraries are licensed under theMIT open source license.

C-SDK simplifies access to various AWS IoT services. C-SDK has been tested to work withAWS IoT Core and an open source MQTT broker to ensure interoperability. The AWS IoT Device Shadow, AWS IoT Jobs, and AWS IoT Device Defender libraries are flexible to work with any MQTT client and JSON parser. The MQTT client and JSON parser libraries are offered as choices without being tightly coupled with the rest of the SDK. C-SDK contains the following libraries:

ThecoreMQTT library provides the ability to establish an MQTT connection with a broker over a customer-implemented transport layer, which can either be a secure channel like a TLS session (mutually authenticated or server-only authentication) or a non-secure channel like a plaintext TCP connection. This MQTT connection can be used for performing publish operations to MQTT topics and subscribing to MQTT topics. The library provides a mechanism to register customer-defined callbacks for receiving incoming PUBLISH, acknowledgement and keep-alive response events from the broker. The library has been refactored for memory optimization and is compliant with theMQTT 3.1.1 standard. It has no dependencies on any additional libraries other than the standard C library, a customer-implemented network transport interface, and optionally a customer-implemented platform time function. The refactored design embraces different use-cases, ranging from resource-constrained platforms using only QoS 0 MQTT PUBLISH messages to resource-rich platforms using QoS 2 MQTT PUBLISH over TLS connections.

See memory requirements for the latest releasehere.

ThecoreHTTP library provides the ability to establish an HTTP connection with a server over a customer-implemented transport layer, which can either be a secure channel like a TLS session (mutually authenticated or server-only authentication) or a non-secure channel like a plaintext TCP connection. The HTTP connection can be used to make "GET" (include range requests), "PUT", "POST" and "HEAD" requests. The library provides a mechanism to register a customer-defined callback for receiving parsed header fields in an HTTP response. The library has been refactored for memory optimization, and is a client implementation of a subset of theHTTP/1.1 standard.

See memory requirements for the latest releasehere.

ThecoreJSON library is a JSON parser that strictly enforces theECMA-404 JSON standard. It provides a function to validate a JSON document, and a function to search for a key and return its value. A search can descend into nested structures using a compound query key. A JSON document validation also checks for illegal UTF8 encodings and illegal Unicode escape sequences.

See memory requirements for the latest releasehere.

ThecorePKCS11 library is an implementation of the PKCS #11 interface (API) that makes it easier to develop applications that rely on cryptographic operations. Only a subset of thePKCS #11 v2.4 standard has been implemented, with a focus on operations involving asymmetric keys, random number generation, and hashing.

The Cryptoki or PKCS #11 standard defines a platform-independent API to manage and use cryptographic tokens. The name, "PKCS #11", is used interchangeably to refer to the API itself and the standard which defines it.

The PKCS #11 API is useful for writing software without taking a dependency on any particular implementation or hardware. By writing against the PKCS #11 standard interface, code can be used interchangeably with multiple algorithms, implementations and hardware.

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.The purpose of corePKCS11 mock is therefore to provide a PKCS #11 implementation that allows for rapid prototyping and development before switching to a cryptoprocessor specific PKCS #11 implementation in production devices.

Since the PKCS #11 interface is defined as part of the PKCS #11specification replacing corePKCS11 with another implementationshould require little porting effort, as the interface will not change. The system tests distributed in corePKCS11 repository can be leveraged to verify the behavior of a different implementation is similar to corePKCS11.

See memory requirements for the latest releasehere.

TheAWS IoT Device Shadow library enables you to store and retrieve the current state one or more shadows of every registered device. A device’s shadow is a persistent, virtual representation of your device that you can interact with from AWS IoT Core even if the device is offline. The device state is captured in its "shadow" is represented as aJSON document. The device can send commands over MQTT to get, update and delete its latest state as well as receive notifications over MQTT about changes in its state. The device’s shadow(s) are uniquely identified by the name of the corresponding "thing", a representation of a specific device or logical entity on the AWS Cloud. SeeManaging Devices with AWS IoT for more information on IoT "thing". This library supports named shadows, a feature of the AWS IoT Device Shadow service that allows you to create multiple shadows for a single IoT device. More details about AWS IoT Device Shadow can be found inAWS IoT documentation.

The AWS IoT Device Shadow library has no dependencies on 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 library (seedemos with coreMQTT and coreJSON).

See memory requirements for the latest releasehere.

TheAWS IoT Jobs library enables you to interact with the AWS IoT Jobs service which notifies one or more connected devices of a pending “Job”. A Job can be used to manage your fleet of devices, update firmware and security certificates on your devices, or perform administrative tasks such as restarting devices and performing diagnostics. For documentation of the service, please see theAWS IoT Developer Guide. Interactions with the Jobs service use the MQTT protocol. This library provides an API to compose and recognize the MQTT topic strings used by the Jobs service.

The AWS IoT Jobs library has no dependencies on 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 library (seedemos withlibmosquitto and coreJSON).

See memory requirements for the latest releasehere.

TheAWS IoT Device Defender library enables you to interact with the AWS IoT Device Defender service to continuously monitor security metrics from devices for deviations from what you have defined as appropriate behavior for each device. If something doesn’t look right, AWS IoT Device Defender sends out an alert so you can take action to remediate the issue. More details about Device Defender can be found inAWS IoT Device Defender documentation. This library supports custom metrics, a feature that helps you monitor operational health metrics that are unique to your fleet or use case. For example, you can define a new metric to monitor the memory usage or CPU usage on your devices.

The AWS IoT Device Defender library has no dependencies on 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 library (seedemos with coreMQTT and coreJSON).

See memory requirements for the latest releasehere.

TheAWS IoT Over-the-air Update (OTA) library enables you to manage the notification of a newly available update, download the update, and perform cryptographic verification of the firmware update. Using the OTA library, you can logically separate firmware updates from the application running on your devices. You can also use the library to send other files (e.g. images, certificates) to one or more devices registered with AWS IoT. More details about OTA library can be found inAWS IoT Over-the-air Update documentation.

The AWS IoT Over-the-air Update library has a dependency oncoreJSON for parsing of JSON job document andtinyCBOR for decoding encoded data streams, other than the standard C library. It can be used with any MQTT library, HTTP library, and operating system (e.g. Linux, FreeRTOS) (seedemos with coreMQTT and coreHTTP over Linux).

See memory requirements for the latest releasehere.

TheAWS IoT Fleet Provisioning library enables you to interact with theAWS IoT Fleet Provisioning MQTT APIs in order to provison IoT devices without preexisting device certificates. With AWS IoT Fleet Provisioning, devices can securely receive unique device certificates from AWS IoT when they connect for the first time. For an overview of all provisioning options offered by AWS IoT, seedevice provisioning documentation. For details about Fleet Provisioning, refer to theAWS IoT Fleet Provisioning documentation.

See memory requirements for the latest releasehere.

TheAWS SigV4 library enables you to sign HTTP requests withSignature Version 4 Signing Process. Signature Version 4 (SigV4) is the process to add authentication information to HTTP requests to AWS services. For security, most requests to AWS must be signed with an access key. The access key consists of an access key ID and secret access key.

See memory requirements for the latest releasehere.

ThebackoffAlgorithm library is a utility library to calculate backoff period using an exponential backoff with jitter algorithm for retrying network operations (like failed network connection with server). This library uses the "Full Jitter" strategy for the exponential backoff with jitter algorithm. More information about the algorithm can be seen in theExponential Backoff and Jitter AWS blog.

Exponential backoff with jitter is typically used when retrying a failed connection or network request to the server. An exponential backoff with jitter helps to mitigate the failed network operations with servers, that are caused due to network congestion or high load on the server, by spreading out retry requests across multiple devices attempting network operations. Besides, in an environment with poor connectivity, a client can get disconnected at any time. A backoff strategy helps the client to conserve battery by not repeatedly attempting reconnections when they are unlikely to succeed.

The backoffAlgorithm library has no dependencies on libraries other than the standard C library.

See memory requirements for the latest releasehere.

When establishing a connection with AWS IoT, users can optionally report the Operating System, Hardware Platform and MQTT client version information of their device to AWS. This information can help AWS IoT provide faster issue resolution and technical support. If users want to report this information, they can send a specially formatted string (see below) in the username field of the MQTT CONNECT packet.

Format

The format of the username string with metrics is:

<Actual_Username>?SDK=<OS_Name>&Version=<OS_Version>&Platform=<Hardware_Platform>&MQTTLib=<MQTT_Library_name>@<MQTT_Library_version>

Where

• <Actual_Username> is the actual username used for authentication, if username and password are used for authentication. When username and password based authentication is not used, thisis an empty value.
• <OS_Name> is the Operating System the application is running on (e.g. Ubuntu)
• <OS_Version> is the version number of the Operating System (e.g. 20.10)
• <Hardware_Platform> is the Hardware Platform the application is running on (e.g. RaspberryPi)
• <MQTT_Library_name> is the MQTT Client library being used (e.g. coreMQTT)
• <MQTT_Library_version> is the version of the MQTT Client library being used (e.g. 1.1.0)

Example

• Actual_Username = “iotuser”, OS_Name = Ubuntu, OS_Version = 20.10, Hardware_Platform_Name = RaspberryPi, MQTT_Library_Name = coremqtt, MQTT_Library_version = 1.1.0. If username is not used, then “iotuser” can be removed.

/* Username string: * iotuser?SDK=Ubuntu&Version=20.10&Platform=RaspberryPi&MQTTLib=coremqtt@1.1.0 */#define OS_NAME                   "Ubuntu"#define OS_VERSION                "20.10"#define HARDWARE_PLATFORM_NAME    "RaspberryPi"#define MQTT_LIB                  "coremqtt@1.1.0"#define USERNAME_STRING           "iotuser?SDK=" OS_NAME "&Version=" OS_VERSION "&Platform=" HARDWARE_PLATFORM_NAME "&MQTTLib=" MQTT_LIB#define USERNAME_STRING_LENGTH    ( ( uint16_t ) ( sizeof( USERNAME_STRING ) - 1 ) )MQTTConnectInfo_t connectInfo;connectInfo.pUserName = USERNAME_STRING;connectInfo.userNameLength = USERNAME_STRING_LENGTH;mqttStatus = MQTT_Connect( pMqttContext, &connectInfo, NULL, CONNACK_RECV_TIMEOUT_MS, pSessionPresent );

C-SDK releases will now follow a date based versioning scheme with the format YYYYMM.NN, where:

• Y represents the year.
• M represents the month.
• N represents the release order within the designated month (00 being the first release).

For example, a second release in June 2021 would be 202106.01. Although the SDK releases have moved to date-based versioning, each library within the SDK will still retain semantic versioning. In semantic versioning, the version number itself (X.Y.Z) indicates whether the release is a major, minor, or point release. You can use the semantic version of a library to assess the scope and impact of a new release on your application.

All of the released versions of the C-SDK libraries are available as git tags. For example, the last release of the v3 SDK version is available attag 3.1.5.

API documentation of 202211.00 release

This release includes an update to how theCoverity static analysis scans are performed. There is now atools/coverity/README.md file in each library with instructions on how to perform a scan with 0MISRA coding standard warnings or errors.

Additionally, this release brings in major version upgrades tocoreMQTT andcoreHTTP. It also brings in minor version upgrades to all other libraries.

API documentation of 202108.00 release

This release introduces the refactoredAWS IoT Fleet Provisioning library and the newAWS SigV4 library.

Additionally, this release brings minor version updates in theAWS IoT Over-the-Air Update andcorePKCS11 libraries.

API documentation of 202103.00 release

This release includes amajor update to the APIs of the AWS IoT Over-the-air Update library.

Additionally, AWS IoT Device Shadow library introduces aminor update by adding support for named shadow, a feature of the AWS IoT Device Shadow service that allows you to create multiple shadows for a single IoT device. AWS IoT Jobs library introduces aminor update by introducing macros for$next job ID and compile-time generation of topic strings. AWS IoT Device Defender library introduces aminor update that adds macros to API for custom metrics feature of AWS IoT Device Defender service.

corePKCS11 also introduces apatch update by removing thepkcs11configPAL_DESTROY_SUPPORTED config and mbedTLS platform abstraction layer ofDestroyObject. Lastly, no code changes are introduced for backoffAlgorithm, coreHTTP, coreMQTT, and coreJSON; however, patch updates are made to improve documentation and CI.

API documentation of 202012.01 release

This release includesAWS IoT Over-the-air Update(Release Candidate),backoffAlgorithm, andPKCS #11 libraries. Additionally, there is a major update to the coreJSON and coreHTTP APIs. All libraries continue to undergo code quality checks (e.g. MISRA-C compliance), and Coverity static analysis. In addition, all libraries except AWS IoT Over-the-air Update and backoffAlgorithm undergo validation of memory safety with the C Bounded Model Checker (CBMC) automated reasoning tool.

API documentation of 202011.00 release

This release includes refactored HTTP client, AWS IoT Device Defender, and AWS IoT Jobs libraries. Additionally, there is a major update to the coreJSON API. All libraries continue to undergo code quality checks (e.g. MISRA-C compliance), Coverity static analysis, and validation of memory safety with the C Bounded Model Checker (CBMC) automated reasoning tool.

API documentation of 202009.00 release

This release includes refactored MQTT, JSON Parser, and AWS IoT Device Shadow libraries for optimized memory usage and modularity. These libraries are included in the SDK viaGit submoduling. These libraries have gone through code quality checks including verification that no function has aGNU Complexity score over 8, and checks against deviations from mandatory rules in theMISRA coding standard. Deviations from the MISRA C:2012 guidelines are documented underMISRA Deviations. These libraries have also undergone both static code analysis fromCoverity static analysis, and validation of memory safety and data structure invariance through theCBMC automated reasoning tool.

If you are upgrading from v3.x API of the C-SDK to the 202009.00 release, please refer toMigration guide from v3.1.5 to 202009.00 and newer releases. If you are using the C-SDK v4_beta_deprecated branch, note that we will continue to maintain this branch for critical bug fixes and security patches but will not add new features to it. See the C-SDK v4_beta_deprecated branchREADME for additional details.

Details availablehere.

All libraries depend on the ISO C90 standard library and additionally on thestdint.h library for fixed-width integers, includinguint8_t,int8_t,uint16_t,uint32_t andint32_t, and constant macros likeUINT16_MAX. If your platform does not support thestdint.h library, definitions of the mentioned fixed-width integer types will be required for porting any C-SDK library to your platform.

Guide for porting coreMQTT library to your platform is availablehere.

Guide for porting coreHTTP library is availablehere.

Guide for porting AWS IoT Device Shadow library is availablehere.

Guide for porting AWS IoT Device Defender library is availablehere.

Guide for porting OTA library to your platform is availablehere.

Migration guide for MQTT library is availablehere.

Migration guide for Shadow library is availablehere.

Migration guide for Jobs library is availablehere.

Themain branch hosts the continuous development of the AWS IoT Embedded C SDK (C-SDK) libraries. Please be aware that the development at the tip of the main branch is continuously in progress, and may have bugs. Consider using thetagged releases of the C-SDK for production ready software.

Thev4_beta_deprecated branch contains a beta version of the C-SDK libraries, which is now deprecated. This branch was earlier named as v4_beta, and was renamed to v4_beta_deprecated. The libraries in this branch will not be released. However, critical bugs will be fixed and tested. No new features will be added to this branch.

This repository usesGit Submodules to bring in the C-SDK libraries (eg, MQTT ) and third-party dependencies (eg, mbedtls for POSIX platform transport layer).Note: If you download the ZIP file provided by GitHub UI, you will not get the contents of the submodules (The ZIP file is also not a valid git repository). If you download from the202012.00 Release Page page, you will get the entire repository (including the submodules) in the ZIP file, aws-iot-device-sdk-embedded-c-202012.00.zip.To clone the latest commit to main branch using HTTPS:

git clone --recurse-submodules https://github.com/aws/aws-iot-device-sdk-embedded-C.git

Using SSH:

git clone --recurse-submodules git@github.com:aws/aws-iot-device-sdk-embedded-C.git

If you have downloaded the repo without using the--recurse-submodules argument, you need to run:

git submodule update --init --recursive

When building with CMake, submodules are also recursively cloned automatically. However,-DBUILD_CLONE_SUBMODULES=0can be passed as a CMake flag to disable this functionality. This is useful when you'd like to build CMake while using adifferent commit from a submodule.

The libraries in this SDK are not dependent on any operating system. However, the demos for the libraries in this SDK are built and tested on a Linux platform. The demos build withCMake, a cross-platform build tool.

• CMake 3.2.0 or any newer version for utilizing the build system of the repository.
• C90 compiler such as gcc
  • Due to the use of mbedtls in corePKCS11, a C99 compiler is required if building the PKCS11 demos.
• Although not a part of the ISO C90 standard,stdint.h is required for fixed-width integer types that includeuint8_t,int8_t,uint16_t,uint32_t andint32_t, and constant macros likeUINT16_MAX, whilestdbool.h is required for boolean parameters in coreMQTT. For compilers that do not provide these header files,coreMQTT provides the filesstdint.readme andstdbool.readme, which can be renamed tostdint.h andstdbool.h, respectively, to provide the required type definitions.
• A supported operating system. The ports provided with this repo are expected to work with all recent versions of the following operating systems, although we cannot guarantee the behavior on all systems.
  • Linux system with POSIX sockets, threads, RT, and timer APIs. (We have tested on Ubuntu 18.04).

The follow table shows libraries that need to be installed in your system to run certain demos. If a dependency isnot installed and cannot be built from source, demos that require that dependency will be excludedfrom the defaultall target.

You need to setup an AWS account and access the AWS IoT console for running the AWS IoT Device Shadow library, AWS IoT Device Defender library, AWS IoT Jobs library,AWS IoT OTA library and coreHTTP S3 download demos.Also, the AWS account can be used for running the MQTT mutual auth demo against AWS IoT broker.Note that running the AWS IoT Device Defender, AWS IoT Jobs and AWS IoT Device Shadow library demos require the setup of a Thing resource for the device running the demo.Follow the links to:

• Setup an AWS account.
• Sign-in to the AWS IoT Console after setting up the AWS account.
• Create a Thing resource.

The MQTT Mutual Authentication and AWS IoT Shadow demos include example AWS IoT policy documents to run each respective demo with AWS IoT. You may use theMQTT Mutual auth andShadow example policies by replacing[AWS_REGION] and[AWS_ACCOUNT_ID] with the strings of your region and account identifier. While the IoT Thing name and MQTT client identifier do not need to match for the demos to run, the example policies have the Thing name and client identifier identical as perAWS IoT best practices.

It can be very helpful to also have theAWS Command Line Interface tooling installed.

You can pass the following configuration settings as command line options in order to run the mutual auth demos. Make sure to run the following command in the root directory of the C-SDK:

## optionally find your-aws-iot-endpoint from the command lineaws iot describe-endpoint --endpoint-type iot:Data-ATScmake -S. -Bbuild-DAWS_IOT_ENDPOINT="<your-aws-iot-endpoint>" -DCLIENT_CERT_PATH="<your-client-certificate-path>" -DCLIENT_PRIVATE_KEY_PATH="<your-client-private-key-path>"

In order to set these configurations manually, editdemo_config.h indemos/mqtt/mqtt_demo_mutual_auth/ anddemos/http/http_demo_mutual_auth/ to#define the following:

• SetAWS_IOT_ENDPOINT to your custom endpoint. This is found on theSettings page of the AWS IoT Console and has a format ofABCDEFG1234567.iot.<aws-region>.amazonaws.com where<aws-region> can be an AWS region likeus-east-2.
  • Optionally, it can also be found with the AWS CLI commandaws iot describe-endpoint --endpoint-type iot:Data-ATS.
• SetCLIENT_CERT_PATH to the path of the client certificate downloaded when setting up the device certificate inAWS IoT Account Setup.
• SetCLIENT_PRIVATE_KEY_PATH to the path of the private key downloaded when setting up the device certificate inAWS IoT Account Setup.

It is possible to configureROOT_CA_CERT_PATH to any PEM-encoded Root CA Certificate.However, this is optional because CMake will download and set it toAmazonRootCA1.pem when unspecified.If unspecified, the default Root CA path will be interpreted relative to where the demo binary is executed.For many demos, you can change this path by modifying it in the correspondingdemo_config.h.

To build the AWS IoT Device Defender and AWS IoT Device Shadow demos, you can pass the following configuration settings as command line options. Make sure to run the following command in the root directory of the C-SDK:

cmake -S. -Bbuild -DAWS_IOT_ENDPOINT="<your-aws-iot-endpoint>" -DROOT_CA_CERT_PATH="<your-path-to-amazon-root-ca>" -DCLIENT_CERT_PATH="<your-client-certificate-path>" -DCLIENT_PRIVATE_KEY_PATH="<your-client-private-key-path>" -DTHING_NAME="<your-registered-thing-name>"

An Amazon Root CA certificate can be downloaded fromhere.

In order to set these configurations manually, editdemo_config.h in the demo folder to#define the following:

• SetAWS_IOT_ENDPOINT to your custom endpoint. This is found on theSettings page of the AWS IoT Console and has a format ofABCDEFG1234567.iot.us-east-2.amazonaws.com.
• SetROOT_CA_CERT_PATH to the path of the root CA certificate downloaded when setting up the device certificate inAWS IoT Account Setup.
• SetCLIENT_CERT_PATH to the path of the client certificate downloaded when setting up the device certificate inAWS IoT Account Setup.
• SetCLIENT_PRIVATE_KEY_PATH to the path of the private key downloaded when setting up the device certificate inAWS IoT Account Setup.
• SetTHING_NAME to the name of the Thing created inAWS IoT Account Setup.

To build the AWS IoT Fleet Provisioning Demo, you can pass the following configuration settings as command line options. Make sure to run the following command in the root directory of the C-SDK:

cmake -S. -Bbuild -DAWS_IOT_ENDPOINT="<your-aws-iot-endpoint>" -DROOT_CA_CERT_PATH="<your-path-to-amazon-root-ca>" -DCLAIM_CERT_PATH="<your-claim-certificate-path>" -DCLAIM_PRIVATE_KEY_PATH="<your-claim-private-key-path>" -DPROVISIONING_TEMPLATE_NAME="<your-template-name>" -DDEVICE_SERIAL_NUMBER="<your-serial-number>"

An Amazon Root CA certificate can be downloaded fromhere.

To create a provisioning template and claim credentials, sign into your AWS account and visithere. Make sure to enable the "Use the AWS IoT registry to manage your device fleet" option. Onceyou have created the template and credentials, modify the claim certificate's policy to match thesample policy.

In order to set these configurations manually, editdemo_config.h in the demo folder to#define the following:

• SetAWS_IOT_ENDPOINT to your custom endpoint. This is found on theSettings page of the AWS IoT Console and has a format ofABCDEFG1234567.iot.us-east-2.amazonaws.com.
• SetROOT_CA_CERT_PATH to the path of the root CA certificate downloaded when setting up the device certificate inAWS IoT Account Setup.
• SetCLAIM_CERT_PATH to the path of the claim certificate downloaded when setting up the template and claim credentials.
• SetCLAIM_PRIVATE_KEY_PATH to the path of the private key downloaded when setting up the template and claim credentials.
• SetPROVISIONING_TEMPLATE_NAME to the name of the provisioning template created.
• SetDEVICE_SERIAL_NUMBER to an arbitrary string representing a device identifier.

You can pass the following configuration settings as command line options in order to run the S3 demos. Make sure to run the following command in the root directory of the C-SDK:

cmake -S. -Bbuild -DS3_PRESIGNED_GET_URL="s3-get-url" -DS3_PRESIGNED_PUT_URL="s3-put-url"

S3_PRESIGNED_PUT_URL is only needed for the S3 upload demo.

In order to set these configurations manually, editdemo_config.h indemos/http/http_demo_s3_download_multithreaded, anddemos/http/http_demo_s3_upload to#define the following:

• SetS3_PRESIGNED_GET_URL to a S3 presigned URL with GET access.
• SetS3_PRESIGNED_PUT_URL to a S3 presigned URL with PUT access.

You can generate the presigned urls usingdemos/http/common/src/presigned_urls_gen.py. More info can be foundhere.

Refer thisdemos/http/http_demo_s3_download/README.md to follow the steps needed to configure and run the S3 Download HTTP Demo using SigV4 Library that generates the authorization HTTP header needed to authenticate the HTTP requests send to S3.

1. The demo requires the Linux platform to contain curl and libmosquitto. On a Debian platform, these dependencies can be installed with:

    apt install curl libmosquitto-dev

If the platform does not contain thelibmosquitto library, the demo will build the library from source.

libmosquitto 1.4.10 or any later version of the first major release is required to run this demo.

2. A job that specifies the URL to download for the demo needs to be created on the AWS account for the Thing resource that will be used by the demo.The job can be created directly from theAWS IoT console or using the aws cli tool.

The following creates a job that specifies a Linux Kernel link for downloading.

 aws iot create-job \        --job-id 'job_1' \        --targets arn:aws:iot:us-west-2:<account-id>:thing/<thing-name> \        --document '{"url":"https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.8.5.tar.xz"}'

For setting up the Greengrass local auth demo, seethe README in the demo folder.

1. To perform a successful OTA update, you need to complete the prerequisites mentionedhere.
2. A code signing certificate is required to authenticate the update. A code signing certificate based on the SHA-256 ECDSA algorithm will work with the current demos. An example of how to generate this kind of certificate can be foundhere.
3. The code signing certificate can be either baked into firmware as a string, or stored as a file.
   1. For baked in certificate method, copy the certificate to signingcredentialSIGNING_CERTIFICATE_PEM inota_pal_posix.c.
   2. For file storage method, store the certificate as a file and supply the file path in "Path name of code signing certificate on device" field when creating the OTA job in AWS IoT Console.

After you build and run the initial executable you will have to create another executable and schedule an OTA update job with this image.

1. Increase the version of the application by setting macroAPP_VERSION_BUILD indemos/ota/ota_demo_core_[mqtt/http]/demo_config.h to a different version than what is running.
2. Rebuild the application using thebuild steps below into a different directory, saybuild-dir-2.
3. Rename the demo executable to reflect the change, e.g.mv ota_demo_core_mqtt ota_demo_core_mqtt2
4. Create an OTA job:
   1. Go to theAWS IoT Core console.
   2. Manage → Jobs → Create → Create a FreeRTOS OTA update job → Select the corresponding name for your device from the thing list.
   3. Sign a new firmware → Create a new profile → Select any SHA-ECDSA signing platform → Upload the code signing certificate(from prerequisites) and provide its path on the device.
   4. Select the image → Select the bucket you created during theprerequisite steps → Upload the binarybuild-dir-2/bin/ota_demo2.
   5. The path on device should be the absolute path to place the executable and the binary name: e.g./home/ubuntu/aws-iot-device-sdk-embedded-C-staging/build-dir/bin/ota_demo_core_mqtt2.
   6. Select the IAM role created during theprerequisite steps.
   7. Create the Job.
5. Run the initial executable again with the following command:sudo ./ota_demo_core_mqtt orsudo ./ota_demo_core_http.
6. After the initial executable has finished running, go to the directory where the downloaded firmware image resides which is the path name used when creating an OTA job.
7. Change the permissions of the downloaded firmware to make it executable, as it may be downloaded with read (user default) permissions only:chmod 775 ota_demo_core_mqtt2
8. Run the downloaded firmware image with the following command:sudo ./ota_demo_core_mqtt2

Before building the demos, ensure you have installed theprerequisite software. On Ubuntu 18.04 and 20.04,gcc,cmake, and OpenSSL can be installed with:

sudo apt install build-essential cmake libssl-dev

• Go to the root directory of the C-SDK.
• Runcmake to generate the Makefiles:cmake -S . -Bbuild && cd build
• Choose a demo from the list below or alternatively, runmake help | grep demo:

defender_demohttp_demo_basic_tlshttp_demo_mutual_authhttp_demo_plaintexthttp_demo_s3_downloadhttp_demo_s3_download_multithreadedhttp_demo_s3_uploadjobs_demo_mosquittomqtt_demo_basic_tlsmqtt_demo_mutual_authmqtt_demo_plaintextmqtt_demo_serializermqtt_demo_subscription_managerota_demo_core_httpota_demo_core_mqttpkcs11_demo_management_and_rngpkcs11_demo_mechanisms_and_digestspkcs11_demo_objectspkcs11_demo_sign_and_verifyshadow_demo_main

• Replacedemo_name with your desired demo then build it:make demo_name
• Go to thebuild/bin directory and run any demo executables from there.

• Go to the root directory of the C-SDK.
• Runcmake to generate the Makefiles:cmake -S . -Bbuild && cd build
• Run this command to build all configured demos:make
• Go to thebuild/bin directory and run any demo executables from there.

The corePKCS11 demos do not require any AWS IoT resources setup, and are standalone. The demos build upon each other to introduce concepts in PKCS #11 sequentially. Below is the recommended order.

1. pkcs11_demo_management_and_rng
2. pkcs11_demo_mechanisms_and_digests
3. pkcs11_demo_objects
4. pkcs11_demo_sign_and_verify
   1. Please note that this demo requires the private and public key generated frompkcs11_demo_objects to be in the directory the demo is executed from.

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.shsh get-docker.sh

The following instructions have been tested on an Ubuntu 18.04 environment with Docker and OpenSSL installed.

1. Download the official Docker image for Mosquitto 1.6.14. This version is deliberately chosen so that the Docker container can load certificates from the host system.Any version after 1.6.14 will drop privileges as soon as the configuration file has been read (before TLS certificates are loaded).

   docker pull eclipse-mosquitto:1.6.14

2. If a Mosquitto broker with TLS communication needs to be run, ignore this step and proceed to the next step. A Mosquitto broker with plain text communication can be run by executing the command below.

   docker run -it -p 1883:1883 --name mosquitto-plain-text eclipse-mosquitto:1.6.14

3. SetBROKER_ENDPOINT defined indemos/mqtt/mqtt_demo_plaintext/demo_config.h tolocalhost.

   Ignore the remaining steps unless a Mosquitto broker with TLS communication also needs to be run.

4. For TLS communication with Mosquitto broker, server and CA credentials need to be created. Use OpenSSL commands to generate the credentials for the Mosquitto server.

   Note: Make sure to use different Common Name (CN) detail between the CA and server certificates; otherwise, SSL handshake fails with exactly same Common Name (CN) detail in both the certificates.

   # Generate CA key and certificate. Provide the Subject field information as appropriate for CA certificate.openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout ca.key -out ca.crt

   # Generate server key and certificate.# Provide the Subject field information as appropriate for Server certificate. Make sure the Common Name (CN) field is different from the root CA certificate.openssl req -nodes -sha256 -new -keyout server.key -out server.csr# Sign with the CA cert.openssl x509 -req -sha256 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365

5. Create a mosquitto.conf file to use port 8883 (for TLS communication) and providing path to the generated credentials.

   port 8883cafile /mosquitto/config/ca.crtcertfile /mosquitto/config/server.crtkeyfile /mosquitto/config/server.key# Use this option for TLS mutual authentication (where client will provide CA signed certificate)#require_certificate truetls_version tlsv1.2#use_identity_as_username true

6. Run the docker container from the local directory containing the generated credential and mosquitto.conf files.

   docker run -it -p 8883:8883 -v$(pwd):/mosquitto/config/ --name mosquitto-basic-tls eclipse-mosquitto:1.6.14

7. Updatedemos/mqtt/mqtt_demo_basic_tls/demo_config.h to the following:SetBROKER_ENDPOINT tolocalhost.SetROOT_CA_CERT_PATH to the absolute path of the CA certificate created in step 4. for the local Mosquitto server.

Run httpbin through port 80:

docker pull kennethreitz/httpbindocker run -p 80:80 kennethreitz/httpbin

SERVER_HOST defined indemos/http/http_demo_plaintext/demo_config.h can now be set tolocalhost.

To runhttp_demo_basic_tls,download ngrok in order to create an HTTPS tunnel to the httpbin server currently hosted on port 80:

./ngrok http 80# May have to use ./ngrok.exe depending on OS or filename of the executable

ngrok will provide an https link that can be substituted indemos/http/http_demo_basic_tls/demo_config.h and has a format ofhttps://ABCDEFG12345.ngrok.io.

SetSERVER_HOST indemos/http/http_demo_basic_tls/demo_config.h to the https link provided by ngrok, withouthttps:// preceding it.

You must also download the Root CA certificate provided by the ngrok https link and setROOT_CA_CERT_PATH indemos/http/http_demo_basic_tls/demo_config.h to the file path of the downloaded certificate.

Note: For pre-generated documentation, please visitReleases and Documentation section.

The Doxygen references were created using Doxygen version 1.9.2. To generate the Doxygen pages, use the provided Python script attools/doxygen/generate_docs.py. Please ensure that each of the library submodules underlibraries/standard/ andlibraries/aws/ are cloned before using this script.

cd<CSDK_ROOT>git submodule update --init --recursive --checkoutpython3 tools/doxygen/generate_docs.py

The generated documentation landing page is located atdocs/doxygen/output/html/index.html.