HTTP and HTTPS library for Mbed OS 5

Dependents:   MQTTGateway2 MQTTGatewayK64 http-example-wnc GuardRoom ... more

For the example program, see: sandbox/http-example.

This library is used to make HTTP and HTTPS calls from Mbed OS 5 applications.

HTTP Request API

NetworkInterface* network = /* obtain a NetworkInterface object */

const char body[] = "{\"hello\":\"world\"}";

HttpRequest* request = new HttpRequest(network, HTTP_POST, "");
request->set_header("Content-Type", "application/json");
HttpResponse* response = request->send(body, strlen(body));
// if response is NULL, check response->get_error()

printf("status is %d - %s\n", response->get_status_code(), response->get_status_message());
printf("body is:\n%s\n", response->get_body_as_string().c_str());

delete request; // also clears out the response


// pass in the root certificates that you trust, there is no central CA registry in Mbed OS
const char SSL_CA_PEM[] = "-----BEGIN CERTIFICATE-----\n"
    /* rest of the CA root certificates */;

NetworkInterface* network = /* obtain a NetworkInterface object */

const char body[] = "{\"hello\":\"world\"}";

HttpsRequest* request = new HttpsRequest(network, SSL_CA_PEM, HTTP_GET "");
HttpResponse* response = request->send();
// if response is NULL, check response->get_error()

printf("status is %d - %s\n", response->get_status_code(), response->get_status_message());
printf("body is:\n%s\n", response->get_body().c_str());

delete request;

Note: You can get the root CA for a domain easily from Firefox. Click on the green padlock, click More information > Security > View certificate > Details. Select the top entry in the 'Certificate Hierarchy' and click Export.... This gives you a PEM file. Add the content of the PEM file to your root CA list (here's an image).

Mbed TLS Entropy configuration

If your target does not have a built-in TRNG, or other entropy sources, add the following macros to your mbed_app.json file to disable entropy:

    "macros": [

Note that this is not secure, and you should not deploy this device into production with this configuration.

Memory usage

Small requests where the body of the response is cached by the library (like the one found in main-http.cpp), require 4K of RAM. When the request is finished they require 1.5K of RAM, depending on the size of the response. This applies both to HTTP and HTTPS. If you need to handle requests that return a large response body, see 'Dealing with large body'.

HTTPS requires additional memory: on FRDM-K64F about 50K of heap space (at its peak). This means that you cannot use HTTPS on devices with less than 128K of memory, asyou also need to reserve memory for the stack and network interface.

Dealing with large response body

By default the library will store the full request body on the heap. This works well for small responses, but you'll run out of memory when receiving a large response body. To mitigate this you can pass in a callback as the last argument to the request constructor. This callback will be called whenever a chunk of the body is received. You can set the request chunk size in the HTTP_RECEIVE_BUFFER_SIZE macro (see mbed_lib.json for the definition) although it also depends on the buffer size ofthe underlying network connection.

void body_callback(const char* data, uint32_t data_len) {
    // do something with the data

HttpRequest* req = new HttpRequest(network, HTTP_GET, "", &body_callback);
req->send(NULL, 0);

Dealing with a large request body

If you cannot load the full request into memory, you can pass a callback into the send function. Through this callback you can feed in chunks of the request body. This is very useful if you want to send files from a file system.

const void * get_chunk(uint32_t* out_size) {
    // set the value of out_size (via *out_size = 10) to the size of the buffer
    // return the buffer

    // if you don't have any more data, set *out_size to 0

HttpRequest* req = new HttpRequest(network, HTTP_POST, "");

Socket re-use

By default the library opens a new socket per request. This is wasteful, especially when dealing with TLS requests. You can re-use sockets like this:


TCPSocket* socket = new TCPSocket();

nsapi_error_t open_result = socket->open(network);
// check open_result

nsapi_error_t connect_result = socket->connect("", 80);
// check connect_result

// Pass in `socket`, instead of `network` as first argument
HttpRequest* req = new HttpRequest(socket, HTTP_GET, "");


TLSSocket* socket = new TLSSocket();

nsapi_error_t r;
// make sure to check the return values for the calls below (should return NSAPI_ERROR_OK)
r = socket->open(network);
r = socket->set_root_ca_cert(SSL_CA_PEM);
r = socket->connect("", 443);

// Pass in `socket`, instead of `network` as first argument, and omit the `SSL_CA_PEM` argument
HttpsRequest* get_req = new HttpsRequest(socket, HTTP_GET, "");

Request logging

To make debugging easier you can log the raw request body that goes over the line. This also works with chunked encoding.

uint8_t *request_buffer = (uint8_t*)calloc(2048, 1);
req->set_request_log_buffer(request_buffer, 2048);

// after the request is done:
printf("\n----- Request buffer -----\n");
for (size_t ix = 0; ix < req->get_request_log_buffer_length(); ix++) {
    printf("%02x ", request_buffer[ix]);

Integration tests

Integration tests are located in the TESTS folder and are ran through Greentea. Instructions on how to run the tests are in http-example.

Mbed OS 5.10 or lower

If you want to use this library on Mbed OS 5.10 or lower, you need to add the TLSSocket library to your project. This library is included in Mbed OS 5.11 and up.

Tested on

  • K64F with Ethernet.
  • NUCLEO_F411RE with ESP8266.
  • ODIN-W2 with WiFi.
  • K64F with Atmel 6LoWPAN shield.
  • DISCO-L475VG-IOT01A with WiFi.
  • Mbed Simulator.
Jan Jongboom
Mon Aug 12 11:45:31 2019 +0200
Fix parsed url leaking memory if path is empty

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jan Jongboom 0:910f5949759f 1 /*
Jan Jongboom 0:910f5949759f 2 * PackageLicenseDeclared: Apache-2.0
Jan Jongboom 0:910f5949759f 3 * Copyright (c) 2017 ARM Limited
Jan Jongboom 0:910f5949759f 4 *
Jan Jongboom 0:910f5949759f 5 * Licensed under the Apache License, Version 2.0 (the "License");
Jan Jongboom 0:910f5949759f 6 * you may not use this file except in compliance with the License.
Jan Jongboom 0:910f5949759f 7 * You may obtain a copy of the License at
Jan Jongboom 0:910f5949759f 8 *
Jan Jongboom 0:910f5949759f 9 *
Jan Jongboom 0:910f5949759f 10 *
Jan Jongboom 0:910f5949759f 11 * Unless required by applicable law or agreed to in writing, software
Jan Jongboom 0:910f5949759f 12 * distributed under the License is distributed on an "AS IS" BASIS,
Jan Jongboom 0:910f5949759f 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Jan Jongboom 0:910f5949759f 14 * See the License for the specific language governing permissions and
Jan Jongboom 0:910f5949759f 15 * limitations under the License.
Jan Jongboom 0:910f5949759f 16 */
Jan Jongboom 0:910f5949759f 17
Jan Jongboom 0:910f5949759f 18 #ifndef _MBED_HTTPS_REQUEST_H_
Jan Jongboom 0:910f5949759f 19 #define _MBED_HTTPS_REQUEST_H_
Jan Jongboom 0:910f5949759f 20
Jan Jongboom 0:910f5949759f 21 #include <string>
Jan Jongboom 0:910f5949759f 22 #include <vector>
Jan Jongboom 0:910f5949759f 23 #include <map>
Jan Jongboom 31:b3730a2c4f39 24 #include "http_request_base.h"
Jan Jongboom 31:b3730a2c4f39 25 #include "TLSSocket.h"
Jan Jongboom 0:910f5949759f 26
Jan Jongboom 20:0e63d6a93c02 27 #ifndef HTTP_RECEIVE_BUFFER_SIZE
Jan Jongboom 20:0e63d6a93c02 28 #define HTTP_RECEIVE_BUFFER_SIZE 8 * 1024
Jan Jongboom 20:0e63d6a93c02 29 #endif
Jan Jongboom 20:0e63d6a93c02 30
Jan Jongboom 0:910f5949759f 31 /**
Jan Jongboom 0:910f5949759f 32 * \brief HttpsRequest implements the logic for interacting with HTTPS servers.
Jan Jongboom 0:910f5949759f 33 */
Jan Jongboom 31:b3730a2c4f39 34 class HttpsRequest : public HttpRequestBase {
Jan Jongboom 0:910f5949759f 35 public:
Jan Jongboom 0:910f5949759f 36 /**
Jan Jongboom 0:910f5949759f 37 * HttpsRequest Constructor
Jan Jongboom 0:910f5949759f 38 * Initializes the TCP socket, sets up event handlers and flags.
Jan Jongboom 0:910f5949759f 39 *
Jan Jongboom 31:b3730a2c4f39 40 * @param[in] network The network interface
Jan Jongboom 0:910f5949759f 41 * @param[in] ssl_ca_pem String containing the trusted CAs
Jan Jongboom 0:910f5949759f 42 * @param[in] method HTTP method to use
Jan Jongboom 0:910f5949759f 43 * @param[in] url URL to the resource
Jan Jongboom 0:910f5949759f 44 * @param[in] body_callback Callback on which to retrieve chunks of the response body.
Jan Jongboom 0:910f5949759f 45 If not set, the complete body will be allocated on the HttpResponse object,
Jan Jongboom 0:910f5949759f 46 which might use lots of memory.
Jan Jongboom 0:910f5949759f 47 */
Jan Jongboom 31:b3730a2c4f39 48 HttpsRequest(NetworkInterface* network,
Jan Jongboom 0:910f5949759f 49 const char* ssl_ca_pem,
Jan Jongboom 0:910f5949759f 50 http_method method,
Jan Jongboom 0:910f5949759f 51 const char* url,
Jan Jongboom 31:b3730a2c4f39 52 Callback<void(const char *at, uint32_t length)> body_callback = 0)
Jan Jongboom 31:b3730a2c4f39 53 : HttpRequestBase(NULL, body_callback)
Jan Jongboom 0:910f5949759f 54 {
Jan Jongboom 0:910f5949759f 55 _parsed_url = new ParsedUrl(url);
Jan Jongboom 0:910f5949759f 56 _request_builder = new HttpRequestBuilder(method, _parsed_url);
Jan Jongboom 0:910f5949759f 57 _response = NULL;
Jan Jongboom 0:910f5949759f 58
Jan Jongboom 31:b3730a2c4f39 59 _socket = new TLSSocket();
Jan Jongboom 31:b3730a2c4f39 60 ((TLSSocket*)_socket)->open(network);
Jan Jongboom 31:b3730a2c4f39 61 ((TLSSocket*)_socket)->set_root_ca_cert(ssl_ca_pem);
Jan Jongboom 31:b3730a2c4f39 62 _we_created_socket = true;
Jan Jongboom 11:96e4dcb9c0c2 63 }
Jan Jongboom 0:910f5949759f 64
Jan Jongboom 11:96e4dcb9c0c2 65 /**
Jan Jongboom 11:96e4dcb9c0c2 66 * HttpsRequest Constructor
Jan Jongboom 11:96e4dcb9c0c2 67 * Sets up event handlers and flags.
Jan Jongboom 11:96e4dcb9c0c2 68 *
Jan Jongboom 11:96e4dcb9c0c2 69 * @param[in] socket A connected TLSSocket
Jan Jongboom 11:96e4dcb9c0c2 70 * @param[in] method HTTP method to use
Jan Jongboom 11:96e4dcb9c0c2 71 * @param[in] url URL to the resource
Jan Jongboom 11:96e4dcb9c0c2 72 * @param[in] body_callback Callback on which to retrieve chunks of the response body.
Jan Jongboom 11:96e4dcb9c0c2 73 If not set, the complete body will be allocated on the HttpResponse object,
Jan Jongboom 11:96e4dcb9c0c2 74 which might use lots of memory.
Jan Jongboom 11:96e4dcb9c0c2 75 */
Jan Jongboom 11:96e4dcb9c0c2 76 HttpsRequest(TLSSocket* socket,
Jan Jongboom 11:96e4dcb9c0c2 77 http_method method,
Jan Jongboom 11:96e4dcb9c0c2 78 const char* url,
Jan Jongboom 31:b3730a2c4f39 79 Callback<void(const char *at, uint32_t length)> body_callback = 0)
Jan Jongboom 31:b3730a2c4f39 80 : HttpRequestBase(socket, body_callback)
Jan Jongboom 11:96e4dcb9c0c2 81 {
Jan Jongboom 11:96e4dcb9c0c2 82 _parsed_url = new ParsedUrl(url);
Jan Jongboom 11:96e4dcb9c0c2 83 _body_callback = body_callback;
Jan Jongboom 11:96e4dcb9c0c2 84 _request_builder = new HttpRequestBuilder(method, _parsed_url);
Jan Jongboom 11:96e4dcb9c0c2 85 _response = NULL;
Jan Jongboom 11:96e4dcb9c0c2 86
Jan Jongboom 31:b3730a2c4f39 87 _we_created_socket = false;
Jan Jongboom 0:910f5949759f 88 }
Jan Jongboom 0:910f5949759f 89
Jan Jongboom 31:b3730a2c4f39 90 virtual ~HttpsRequest() {}
Jan Jongboom 11:96e4dcb9c0c2 91
Jan Jongboom 0:910f5949759f 92 protected:
Jan Jongboom 31:b3730a2c4f39 93 virtual nsapi_error_t connect_socket(char *host, uint16_t port) {
Jan Jongboom 31:b3730a2c4f39 94 return ((TLSSocket*)_socket)->connect(host, port);
Jan Jongboom 23:15fa2726f793 95 }
Jan Jongboom 0:910f5949759f 96 };
Jan Jongboom 0:910f5949759f 97
Jan Jongboom 0:910f5949759f 98 #endif // _MBED_HTTPS_REQUEST_H_