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 basic TLS – only Server Authentication)

Notice: 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 uses the FreeRTOS Windows port, enabling it to be built and evaluated with the free Community version of Visual Studio on Windows, so without the need for any particular MCU hardware.  This demo establishes a connection to a public internet HTTPS server using TLS.  Other than the addition of TLS, this demo has the same functionality as the basic HTTP Client demo.

The example projects documented on this page introduces the concepts described in the “TLS Introduction” section. The first example demonstrates unencrypted HTTP communication, the second example (this page) builds on the first to introduce weak server authentication, and the third example builds on the second to introduce strong mutual authentication. Most public internet servers do not authenticate the client that is connecting.

This demo is intended to be used as a learning exercise only. Do NOT send any confidential information from your device to the HTTPS server.  The HTTPS server is publicly accessible and does not have the same security standards as many industry provided HTTPS servers.  The HTTPS server is hosted by a 3rd party that is not affiliated with FreeRTOS.  It may be unavailable at any time, and it is not maintained by FreeRTOS.

Note: http://httpbin.org is an open source HTTP test server that supports HTTP/1.1.  You can find more information at https://github.com/postmanlabs/httpbin.

Source Code Organization

The demo project is called https_basic_tls_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).

Configuring the Demo Project

The demo project is configured in the same manner as the basic HTTP Client demo (without TLS).

Configuring the HTTPS Server Connection

HTTPS Server (Web Hosted) The demo project is pre-configured to communicate with the publicly hosted HTTPS server at “httpbin.org” – so the network to which the demo is connected must have a DHCP service and internet access.  Note public HTTPS servers can be slow. If you would like to connect to a different secure public server then:
  1. Open FreeRTOS-Plus\Demo\FreeRTOS-IoT-Libraries-LTS-Beta1\https\https_basic_tls_server_auth\DemoTasks\SimpleHTTPSOverTLSExamples.c.
  2. Edit the following lines to be correct for your chosen server:#define httpsexampleHTTPS_SERVER_ADDRESS "httpbin.org" #define httpsexampleHTTPS_SERVER_PORT 443
  3. Edit the following lines to be correct for your chosen server:#define httpsexampleHTTPS_SERVER_CERTIFICATE
  4. The new server needs to support GET, HEAD, and PUT and POST of random data. Update the following lines for the correct path to perform these methods: #define httpsexampleHTTPS_GET_PATH "/ip" #define httpsexampleHTTPS_HEAD_PATH "/ip" #define httpsexampleHTTPS_PUT_PATH "/put" #define httpsexampleHTTPS_POST_PATH "/post"

Building the Demo Project

The 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_basic_tls_server_auth\https_basic_tls_demo.sln Visual Studio solution file from within the Visual Studio IDE


The 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).

Connecting to the HTTPS Server (with TLS)

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 which is implemented in the file FreeRTOS-Plus\Source\FreeRTOS-IoT-Libraries-LTS-Beta1io\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 = NULL,
  .clientCertLen = 0,
  .pPrivateKey = NULL,
  .privateKeyLen = 0
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.