coreHTTP mutual authentication demo - FreeRTOS
IntroductionFunctionalitySource code organizationConnecting to the Amazon IoT HTTP serverSending an HTTP request and receiving the response
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

coreHTTP mutual authentication demo

Important

This demo is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you start here when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the Amazon-FreeRTOS Github Repository Migration Guide.

Introduction

The coreHTTP (Mutual Authentication) demo project shows you how to establish a connection to an HTTP server using TLS with mutual authentication between the client and the server. This demo uses an mbedTLS-based transport interface implementation to establish a server- and client-authenticated TLS connection, and demonstrates a request response workflow in HTTP.

Note

To set up and run the FreeRTOS demos, follow the steps in Getting Started with FreeRTOS.

Functionality

This demo creates a single application task with examples that show how to complete the following:

  • Connect to the HTTP server on the Amazon IoT endpoint.

  • Send a POST request.

  • Receive the response.

  • Disconnect from the server.

After you complete these steps, the demo generates output similar to the following screenshot.

Log output showing Amazon IoT demo initialization, TLS session establishment, HTTP POST requests, and memory metrics indicating successful demo completion.

The Amazon IoT console generates output similar to the following screenshot.

Amazon IoT console showing "Hello from Amazon IoT console" message published to a topic on November 20, 2020 at 19:09:09 UTC.

Source code organization

The demo source file is named http_demo_mutual_auth.c and can be found in the freertos/demos/coreHTTP/ directory and on the GitHub website.

Connecting to the Amazon IoT HTTP server

The connectToServerWithBackoffRetries function attempts to make a mutually authenticated TLS connection to the Amazon IoT HTTP server. If the connection fails, it retries after a timeout. The timeout value exponentially increases until the maximum number of attempts is reached or the maximum timeout value is reached. The RetryUtils_BackoffAndSleep function provides exponentially increasing timeout values and returns RetryUtilsRetriesExhausted when the maximum number of attempts have been reached. The connectToServerWithBackoffRetries function returns a failure status if the TLS connection to the broker can't be established after the configured number of attempts.

Sending an HTTP request and receiving the response

The prvSendHttpRequest function demonstrates how to send a POST request to the Amazon IoT HTTP server. For more information on making a request to the REST API in Amazon IoT, see Device communication protocols - HTTPS. The response is received with the same coreHTTP API call, HTTPClient_Send.