Quality RTOS & Embedded Software

NOTE: The HTTPS library and documentation are part of the FreeRTOS LTS Roadmap. These libraries are fully functional, but undergoing optimizations or refactoring to improve memory usage, modularity, documentation, demo usability, or test coverage. They are available on GitHub or part of the LTS Development Snapshot download

HTTPS Client Demo (with TLS – Mutual Authentication)

Note: We recommend to always use mutual authentication in building any Internet of Things (IoT) application. The demo on this page is only meant for educational purposes and demonstrates HTTP communication prior to introducing encryption and authentication. It is not intended to be suitable for production use.


The HTTPS Client demo project shows you how to establish a connection to a public HTTPS server using TLS with mutual authentication between the client and the server.  Except for the addition of client authentication by the server, this demo has the same functionality as the HTTP Client demo with Server Authentication. The 3 HTTPS example projects documented on these pages introduce the concepts described in the “TLS Introduction” section one at a time. The first example demonstrates unencrypted HTTP communication. The second example builds on the first to introduce weak server authentication. The third example (this page) builds on the second example to introduce strong mutual authentication to AWS IoT. Most public internet servers do not authenticate the client that is connecting. The HTTPS Client demo project uses the FreeRTOS Windows port, so it can be built and evaluated with the free Community version of Visual Studio on Windows without the need for any particular MCU hardware.

Source Code Organization

The demo project is called https_tls_mutual_auth_demo.sln and can be found on Github in the following directory:


The source code is organized in the same manner as the basic HTTP Client demo (without TLS).

Configure the Demo Project

This demo project is configured in the same way as the Basic HTTP Client demo (without TLS).

Configure the AWS IoT Demo Profile

The Mutual Authentication HTTPS demo requires client authentication in addition to the server authentication required in the HTTPS with TLS (Server Auth) demo.  This demo will showcase a connection to AWS (Amazon Web Services) IoT.  Additional steps are required to acquire and set up credentials using existing tools provided by AWS. After you complete the setup steps below, the configuration can be reused with other AWS IoT related demos (coming in a future release) such as the Mutual Authentication MQTT demo. For enhanced security, AWS IoT does not support plaintext and server side only authentication. See Security in AWS. Follow the steps below for configuring your connection to AWS.
  1. Set up an Amazon Web Services (AWS) account:
  2. Accounts and permissions are set using AWS Identity and Access Management (IAM). IAM allows you to manage the permissions for each user. By default, no users have permissions until granted by the root owner.
    • To add an IAM user to your AWS account, see the IAM User Guide.
    • Set permissions for your AWS account to access FreeRTOS and AWS IoT by adding the policies below:
        • AmazonFreeRTOSFullAccess
        • AWSIoTFullAccess
    • To attach the AmazonFreeRTOSFullAccess policy to your IAM user:

      1. Browse to the IAM console, and from the navigation pane, choose Users.
      2. Enter your user name in the search text box, and then choose it from the list.
      3. Choose Add permissions.
      4. Choose Attach existing policies directly.
      5. In the search box, enter AmazonFreeRTOSFullAccess, choose it from the list, and then choose Next: Review.
      6. Choose Add permissions.

      To attach the AWSIoTFullAccess policy to your IAM user:

      1. Browse to the IAM console and, from the navigation pane, choose Users.
      2. Enter your user name in the search text box, and then choose it from the list.
      3. Choose Add permissions.
      4. Choose Attach existing policies directly.
      5. In the search box, enter AWSIoTFullAccess, choose it from the list, and then choose Next: Review.
      6. Choose Add permissions.
  1. Register a device as an AWS IoT thing with the AWS Command Line Interface (CLI) or AWS IoT Console.  AWS CLI allows you to perform configurations through the command line instead of through the AWS IoT Console interface.  For more information on setting up CLI, please view additional documentation here.  The AWS IoT console provides a user interface for you to setup a device manually.
    • Option 1 (recommended): Set up through the AWS Command-Line Interface (CLI):
      1. Download and Install the AWS CLI on your computer.
      2. Install boto3 with pip: pip install boto3
      3. Continue with the steps in Quickly Configuring the AWS CLI to set it up with your AWS account information
      4. Register a device with the provided python script.  The script sets up the MQTT broker (using the “thing” name you entered), downloads the private key, and writes the credentials to FreeRTOS-Plus\Demo\FreeRTOS_IoT_Libraries\include\aws_iot_demo_profile.h.
        1. In the file tools\aws_config_quick_start\configure.json change the "$thing_name" to your MQTT client ID. The thing name you enter should be enclosed within double quotes (""), and contain a combination of letters, numbers, semicolons (:), underscores (_), and hyphens (-) only.
        2. To finish setup, open a terminal, navigate to the tools\aws_config_quick_start directory and run: python SetupAWS.py setup
        3. If you used python3 for AWS CLI installation, run: python3 SetupAWS.py setup
    • Option 2: Manually setup a thing through the AWS IoT Console:
      1. Add a device to AWS IoT Console
        1. Follow the steps in creating an IoT thing, private key, and certificate for your device to register an AWS IoT.  Take note of your thing name and AWS IoT endpoint, and download the certificate and key associated with your thing. To find your AWS IoT endpoint:
          1. Browse to the AWS IoT console.
          2. In the navigation pane, choose Settings.
          Your AWS IoT endpoint is displayed as the Endpoint. It should look like <account-number>-ats.iot.<us-east-1>.amazonaws.com.
      2. Once you have completed the setup on the service side, you need to configure credentials for AWS IoT credentials on the client side. The file aws_iot_demo_profile.h holds the information you need to connect your FreeRTOS project to AWS IoT, including endpoints, credentials, and keys set to the appropriate values.  Setup the credentials through the Certificate Configurator by following the steps below:
        1. In a browser window, open tools/aws_config_offline/CertificateConfigurator.html.
        2. Under Thing Name, enter the Thing name you registered on AWS IoT.
        3. Under AWS IoT Thing Endpoint, enter your AWS IoT endpoint.
        4. Under Certificate PEM file, choose the <ID>-certificate.pem.crt that you downloaded from the AWS IoT console.
        5. Under Private Key PEM file, choose the <ID>-private.pem.key that you downloaded from the AWS IoT console.
        6. Choose Generate and save aws_iot_demo_profile.h, and then save the file in FreeRTOS-Plus\Demo\FreeRTOS_IoT_Libraries\include. This overwrites the existing file in the directory.

Build the Demo Project

This demo project is built in the same way as the basic HTTP Client demo (without TLS).
  • Open the \FreeRTOS-Plus\Demo\FreeRTOS_IoT_Libraries\https\https_tls_mutual_auth\https_tls_mutual_auth.sln Visual Studio solution file from within the Visual Studio IDE.


This demo provides the same functionality as the basic HTTP Client demo with the addition of connecting with TLS to a public HTTPS server. For details on the additional functionality, please view the basic HTTP Client demo (without TLS).

To Connect to the HTTPS Server (with mutual authentication)

The function prvHTTPSConnect() demonstrates how to establish a TLS connection to a HTTPS server with a clean session. It uses the FreeRTOS+TCP network interface that is implemented in the file FreeRTOS-Plus\Source\FreeRTOS-IoT-Libraries-LTS-Beta1\abstractions\platform\freertos\iot_network_freertos.c. The definition of prvHTTPConnect() is shown below:
static void prvHTTPSConnect( void )
  IotHttpsReturnCode_t xHTTPSClientResult;

  /* Establish the connection to the HTTPS server - It is a blocking call and
   * will return only when the connection is complete or a timeout occurs. */
  xHTTPSClientResult = IotHttpsClient_Connect( &( xHTTPSConnection ),
                                               &( xConnectionInfo ) );
  configASSERT( xHTTPSClientResult == IOT_HTTPS_OK );

Where xConnectionInfo is defined as:

static const IotHttpsConnectionInfo_t xConnectionInfo =
  /* No connection to the HTTPS server has been established yet and we want to
   * establish a new connection. */
  .pAddress = httpsexampleHTTPS_SERVER_ADDRESS,
  .addressLen = sizeof( httpsexampleHTTPS_SERVER_ADDRESS ) - 1,
  .port = httpsexampleHTTPS_SERVER_PORT,
  .userBuffer.pBuffer = ucHTTPSConnectionUserBuffer,
  .userBuffer.bufferLen = sizeof( ucHTTPSConnectionUserBuffer ),

  /* Use FreeRTOS+TCP network. */

  /* The HTTPS Client library uses TLS by default as indicated by the "S"
   * postfixed to "HTTP" in the name of the library and its types and
   * functions. There are no configurations in the flags to enable TLS. */
  .flags = 0,

  /* Optional TLS extensions. For this demo, they are disabled. */
  .pAlpnProtocols = NULL,
  .alpnProtocolsLen = 0,

  /* Provide the certificate for authenticating the server. */
  .pCaCert = httpsexampleHTTPS_SERVER_CERTIFICATE,
  .caCertLen = sizeof( httpsexampleHTTPS_SERVER_CERTIFICATE ),

  /* The HTTPS server at httpbin.org:443 does not require client certificates,
   * but AWS IoT does.
   * If the server were to require a client certificate, the following members
   * need to be set. */
  .pClientCert = httpsexampleCLIENT_CERTIFICATE_PEM,
  .clientCertLen = sizeof( httpsexampleCLIENT_CERTIFICATE_PEM ),
  .pPrivateKey = httpsexampleCLIENT_PRIVATE_KEY_PEM,
  .privateKeyLen = sizeof( httpsexampleCLIENT_PRIVATE_KEY_PEM )
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.