Quality RTOS & Embedded Software

  Real time embedded FreeRTOS RSS feed  
NOTE: The HTTPS library and documentation are in the FreeRTOS Labs.  The libraries in the FreeRTOS Labs download directory are fully functional, but undergoing optimizations or refactoring to improve memory usage, modularity, documentation, demo usability, or test coverage.  They are available as part of the main download.

HTTPS Client Demo (with basic TLS – only Server Authentication)

Notice: It is our recommendation to always use strong mutual authentication in any Internet of Things (IoT) application. The first project is only provided to validate that HTTP communication can be established prior to introducing encryption and authentication, and to allow the HTTP packets to be observed using a network packet sniffer such as Wireshark for those who wish to do so. The first two projects are not intended to be examples suitable for production IoT use.  

 

Introduction

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 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\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

Functionality

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\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. */
  .pNetworkInterface = IOT_NETWORK_INTERFACE_FREERTOS,

  /* 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.