coreHTTP mutual authentication demo - FreeRTOS
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


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.


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.


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


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.

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

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.