AWS coreHTTP

This module provides the AWS coreHTTP library.

Overview

The AWS coreHTTP library can be used to send HTTP and HTTPS requests. The documentation for the library can be found at the following link: coreHTTP.

Features

• Secure and Non-secure HTTP requests
• Mutually authenticated connections

Configuration

Memory Usage

The AWS coreHTTP stack relies on dynamic memory allocation for thread/task creation as well as other uses. It is recommended to tweak the thread stack configuration values based on usage. Notable values are:

FreeRTOS Thread

• General|Minimal Stack Size
• Memory Allocation|Total Heap Size

FreeRTOS Plus TCP

• Stack size in words (not bytes)

Usage Notes

• A transport interface is required to use the CoreHTTP library (https://www.freertos.org/network-interface.html).
• For FSP, a transport interface over MbedTLS is provided. This transport interface can connect to RA ethernet, WiFi, and cellular modules via sockets wrappers for each module.
• TLS_FreeRTOS_Connect should be used before calling any CoreHTTP APIs. See the example for more information.

Limitations

• MbedTLS must be initialized and key provisioning must be done before starting a secure connection.

Examples

HTTPS GET request

/* Certificate copied from https://www.amazontrust.com/repository/AmazonRootCA1.pem */
static const char g_server_certificate[] = "-----BEGIN CERTIFICATE-----\n"                                      \
                                           "MIIDQTCCAimgAwIBAgITBmyfz5m/jAo54vB4ikPmljZbyjANBgkqhkiG9w0BAQsF\n" \
                                           "ADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6\n" \
                                           "b24gUm9vdCBDQSAxMB4XDTE1MDUyNjAwMDAwMFoXDTM4MDExNzAwMDAwMFowOTEL\n" \
                                           "MAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJv\n" \
                                           "b3QgQ0EgMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJ4gHHKeNXj\n" \
                                           "ca9HgFB0fW7Y14h29Jlo91ghYPl0hAEvrAIthtOgQ3pOsqTQNroBvo3bSMgHFzZM\n" \
                                           "9O6II8c+6zf1tRn4SWiw3te5djgdYZ6k/oI2peVKVuRF4fn9tBb6dNqcmzU5L/qw\n" \
                                           "IFAGbHrQgLKm+a/sRxmPUDgH3KKHOVj4utWp+UhnMJbulHheb4mjUcAwhmahRWa6\n" \
                                           "VOujw5H5SNz/0egwLX0tdHA114gk957EWW67c4cX8jJGKLhD+rcdqsq08p8kDi1L\n" \
                                           "93FcXmn/6pUCyziKrlA4b9v7LWIbxcceVOF34GfID5yHI9Y/QCB/IIDEgEw+OyQm\n" \
                                           "jgSubJrIqg0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMC\n" \
                                           "AYYwHQYDVR0OBBYEFIQYzIU07LwMlJQuCFmcx7IQTgoIMA0GCSqGSIb3DQEBCwUA\n" \
                                           "A4IBAQCY8jdaQZChGsV2USggNiMOruYou6r4lK5IpDB/G/wkjUu0yKGX9rbxenDI\n" \
                                           "U5PMCCjjmCXPI6T53iHTfIUJrU6adTrCC2qJeHZERxhlbI1Bjjt/msv0tadQ1wUs\n" \
                                           "N+gDS63pYaACbvXy8MWy7Vu33PqUXHeeE6V/Uq2V8viTO96LXFvKWlJbYK8U90vv\n" \
                                           "o/ufQJVtMVT8QtPHRh8jrdkPSHCa2XV4cdFyQzR1bldZwgJcJmApzyMZFo6IQ6XU\n" \
                                           "5MsI+yMRQ+hDKXJioaldXgjUkK642M4UwtBV8ob2xJNDd2ZhwLnoQdeXeGADbkpy\n" \
                                           "rqXRfboQnoZsG4q5WTP468SQvvG5\n"                                     \
                                           "-----END CERTIFICATE-----";

/* Default settings to use if DHCP fails. */
const uint8_t g_default_ip_address[4]  = {192, 168, 0, 100};
const uint8_t g_default_subnet_mask[4] = {255, 255, 255, 0};
const uint8_t g_default_gateway[4]     = {192, 168, 0, 1};
const uint8_t g_default_dns[4]         = {8, 8, 8, 8};

#if defined(ipconfigIPv4_BACKWARD_COMPATIBLE) && (ipconfigIPv4_BACKWARD_COMPATIBLE == 0)
static NetworkInterface_t xInterfaces[1];
static NetworkEndPoint_t  xEndPoints[1];

extern NetworkInterface_t * pxFillInterfaceDescriptor(BaseType_t xEMACIndex, NetworkInterface_t * pxInterface);

#endif

void https_example_entry (void * pvParameters)
{
    FSP_PARAMETER_NOT_USED(pvParameters);

    /* Initialize the crypto hardware acceleration. */
    mbedtls_platform_setup(NULL);

    /* In order to use the PKCS11 PAL, littlefs must be configured. */
    fsp_err_t fsp_err_status = RM_LITTLEFS_FLASH_Open(g_rm_littlefs0.p_ctrl, g_rm_littlefs0.p_cfg);
    assert(FSP_SUCCESS == fsp_err_status);

    /* Reformat littlefs to ensure that data flash is in a known state. */
    assert(0 == lfs_format(&g_rm_littlefs0_lfs, &g_rm_littlefs0_lfs_cfg));

    /* Mount littlefs. */
    assert(0 == lfs_mount(&g_rm_littlefs0_lfs, &g_rm_littlefs0_lfs_cfg));

    /*
     * Write the keys into data flash using the PKCS11 PAL so that they can be used during TLS setup
     * Note that in an application this will only be done when provisioning a device with a private key.
     * Once a device has been provisioned, the keys will persist in data flash.
     */
    ProvisioningParams_t params;
    params.pucClientPrivateKey       = (uint8_t *) g_client_private_key;
    params.pucClientCertificate      = (uint8_t *) g_client_certificate;
    params.ulClientPrivateKeyLength  = sizeof(g_client_private_key);
    params.ulClientCertificateLength = sizeof(g_client_certificate);
    params.pucJITPCertificate        = NULL;
    params.ulJITPCertificateLength   = 0;
    uint32_t err = (uint32_t) vAlternateKeyProvisioning(&params);
    assert(0 == err);

#if defined(ipconfigIPv4_BACKWARD_COMPATIBLE) && (ipconfigIPv4_BACKWARD_COMPATIBLE == 0)

    /* Initialize the interface descriptor. */
    pxFillInterfaceDescriptor(0, xInterfaces);
    FreeRTOS_FillEndPoint(xInterfaces,
                          xEndPoints,
                          g_default_ip_address,
                          g_default_subnet_mask,
                          g_default_gateway,
                          g_default_dns,
                          g_ether0.p_cfg->p_mac_address);

    /* Initialise the TCP/IP stack. */
    FreeRTOS_IPInit_Multi();
#else

    /* Start up the network stack. */
    FreeRTOS_IPInit(g_default_ip_address,
                    g_default_subnet_mask,
                    g_default_gateway,
                    g_default_dns,
                    g_ether0.p_cfg->p_mac_address);
#endif

#if defined(ipconfigIPv4_BACKWARD_COMPATIBLE) && (ipconfigIPv4_BACKWARD_COMPATIBLE == 0)
    while (pdFALSE == FreeRTOS_IsEndPointUp(xEndPoints))
#else
    while (pdFALSE == FreeRTOS_IsNetworkUp())
#endif
    {
        vTaskDelay(10);
    }

    NetworkCredentials_t xSocketsConfig = {0};
    TlsTransportStatus_t xNetworkStatus = TLS_TRANSPORT_SUCCESS;
    TlsTransportParams_t transport_params;

    /* Configure credentials for TLS authenticated session. */
    xSocketsConfig.pAlpnProtos = NULL;
    xSocketsConfig.disableSni  = false;
    xSocketsConfig.pRootCa     = (const unsigned char *) g_server_certificate;
    xSocketsConfig.rootCaSize  = sizeof(g_server_certificate);

    NetworkContext_t xNetworkContext = {0};

    /* Initialize network context */
    xNetworkContext.pParams = &transport_params;

    /* Attempt to create a authenticated TLS connection. */
    TLS_FreeRTOS_Connect(&xNetworkContext,
                         "postman-echo.com",
                         HTTPS_EXAMPLE_TLS_PORT,
                         &xSocketsConfig,
                         HTTPS_EXAMPLE_TIMEOUT,
                         HTTPS_EXAMPLE_TIMEOUT);
    assert(TLS_TRANSPORT_SUCCESS == xNetworkStatus);

    TransportInterface_t xTransportInterface;

    /* Define the transport interface. */
    xTransportInterface.pNetworkContext = &xNetworkContext;
    xTransportInterface.send            = TLS_FreeRTOS_send;
    xTransportInterface.recv            = TLS_FreeRTOS_recv;

    HTTPRequestInfo_t    xRequestInfo    = {0};
    HTTPRequestHeaders_t xRequestHeaders = {0};

    /* Configure a GET request. */
    xRequestInfo.pHost     = "postman-echo.com";
    xRequestInfo.hostLen   = strlen(xRequestInfo.pHost);
    xRequestInfo.pMethod   = HTTP_METHOD_GET;
    xRequestInfo.methodLen = strlen(HTTP_METHOD_GET);
    xRequestInfo.pPath     = "/get?arg1=val1&arg2=val2";
    xRequestInfo.pathLen   = strlen(xRequestInfo.pPath);
    xRequestInfo.reqFlags  = HTTP_REQUEST_KEEP_ALIVE_FLAG;

    /* Set the buffer used for storing request headers. */
    static uint8_t ucUserBuffer[HTTPS_EXAMPLE_USER_BUFFER_SIZE];
    xRequestHeaders.pBuffer   = ucUserBuffer;
    xRequestHeaders.bufferLen = sizeof(ucUserBuffer);

    /* Initialize the request. */
    HTTPStatus_t xHTTPStatus = HTTPClient_InitializeRequestHeaders(&xRequestHeaders, &xRequestInfo);
    assert(HTTPSuccess == xHTTPStatus);

    /* Reuse the user buffer for storing the response headers. */
    HTTPResponse_t xResponse = {0};
    xResponse.pBuffer   = ucUserBuffer;
    xResponse.bufferLen = sizeof(ucUserBuffer);

    /* Send the request. */
    xHTTPStatus = HTTPClient_Send(&xTransportInterface, &xRequestHeaders, (uint8_t *) NULL, 0, &xResponse, 0);
    assert(HTTPSuccess == xHTTPStatus);

    TLS_FreeRTOS_Disconnect(&xNetworkContext);

    /* The HTTPS request has completed. The result is stored in xResponse. */
}