Hello world example of a TLS client: fetch an HTTPS page. The canonical source for this example lives at https://github.com/ARMmbed/mbed-os-example-tls

HTTPS File Download Example for TLS Client on mbed OS

This application downloads a file from an HTTPS server (developer.mbed.org) and looks for a specific string in that file.

Getting started

Building with mbed CLI

If you'd like to use mbed CLI to build this, then you should set up your environment if you have not done so already. For instructions, refer to the main readme. The instructions here relate to using the developer.mbed.org Online Compiler

Import the program in to the Online Compiler, select your board from the drop down in the top right hand corner and then compile the application. Once it has built, you can drag and drop the binary onto your device.

Required hardware

This example also requires an Ethernet cable an connection to the internet additional to the hardware requirements in the main readme.

Monitoring the application

NOTE: Make sure that the Ethernet cable is plugged in correctly before running the application.

The output in the terminal window should be similar to this:

terminal output

Using Ethernet LWIP
Client IP Address is
Connecting with developer.mbed.org
Starting the TLS handshake...
TLS connection to developer.mbed.org established
Server certificate:
    cert. version     : 3
    serial number     : 11:21:B8:47:9B:21:6C:B1:C6:AF:BC:5D:0C:19:52:DC:D7:C3
    issuer name       : C=BE, O=GlobalSign nv-sa, CN=GlobalSign Organization Validation CA - SHA256 - G2
    subject name      : C=GB, ST=Cambridgeshire, L=Cambridge, O=ARM Ltd, CN=*.mbed.com
    issued  on        : 2016-03-03 12:26:08
    expires on        : 2017-04-05 10:31:02
    signed using      : RSA with SHA-256
    RSA key size      : 2048 bits
    basic constraints : CA=false
    subject alt name  : *.mbed.com, mbed.org, *.mbed.org, mbed.com
    key usage         : Digital Signature, Key Encipherment
    ext key usage     : TLS Web Server Authentication, TLS Web Client Authentication
Certificate verification passed

HTTPS: Received 439 chars from server
HTTPS: Received 200 OK status ... [OK]
HTTPS: Received 'Hello world!' status ... [OK]
HTTPS: Received message:

HTTP/1.1 200 OK
Server: nginx/1.7.10
Date: Wed, 20 Jul 2016 10:00:35 GMT
Content-Type: text/plain
Content-Length: 14
Connection: keep-alive
Last-Modified: Fri, 27 Jul 2012 13:30:34 GMT
Accept-Ranges: bytes
Cache-Control: max-age=36000
Expires: Wed, 20 Jul 2016 20:00:35 GMT
X-Upstream-L2: developer-sjc-indigo-1-nginx
Strict-Transport-Security: max-age=31536000; includeSubdomains

Hello world!

Debugging the TLS connection

To print out more debug information about the TLS connection, edit the file `main.cpp` and change the definition of `DEBUG_LEVEL` (near the top of the file) from 0 to a positive number:

  • Level 1 only prints non-zero return codes from SSL functions and information about the full certificate chain being verified.
  • Level 2 prints more information about internal state updates.
  • Level 3 is intermediate.
  • Level 4 (the maximum) includes full binary dumps of the packets.

The TLS connection can fail with an error similar to:

error message

    mbedtls_ssl_write() failed: -0x2700 (-9984): X509 - Certificate verification failed, e.g. CRL, CA or signature check failed
    Failed to fetch /media/uploads/mbed_official/hello.txt from developer.mbed.org:443

This probably means you need to update the contents of the SSL_CA_PEM constant (this can happen if you modify HTTPS_SERVER_NAME, or when developer.mbed.org switches to a new CA when updating its certificate).

Another possible reason for this error is a proxy providing a different certificate. Proxies can be used in some network configurations or for performing man-in-the-middle attacks. If you choose to ignore this error and proceed with the connection anyway, you can change the definition of UNSAFE near the top of the file from 0 to 1.

Warning: this removes all security against a possible active attacker, so use at your own risk or for debugging only!

Mon Nov 18 14:00:49 2019 +0000
Merge pull request #264 from dgreen-arm/point-master-at-mbed-os-master

Point master branch at Mbed OS master
Commit copied from https://github.com/ARMmbed/mbed-os-example-tls

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 12:1ae41c231014 1 /*
mbed_official 66:ce8709d9912c 2 * Copyright (C) 2006-2018, Arm Limited, All Rights Reserved
mbed_official 12:1ae41c231014 3 * SPDX-License-Identifier: Apache-2.0
mbed_official 12:1ae41c231014 4 *
mbed_official 12:1ae41c231014 5 * Licensed under the Apache License, Version 2.0 (the "License"); you may
mbed_official 12:1ae41c231014 6 * not use this file except in compliance with the License.
mbed_official 12:1ae41c231014 7 * You may obtain a copy of the License at
mbed_official 12:1ae41c231014 8 *
mbed_official 12:1ae41c231014 9 * http://www.apache.org/licenses/LICENSE-2.0
mbed_official 12:1ae41c231014 10 *
mbed_official 12:1ae41c231014 11 * Unless required by applicable law or agreed to in writing, software
mbed_official 12:1ae41c231014 12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
mbed_official 12:1ae41c231014 13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
mbed_official 12:1ae41c231014 14 * See the License for the specific language governing permissions and
mbed_official 12:1ae41c231014 15 * limitations under the License.
mbed_official 12:1ae41c231014 16 *
mbed_official 50:b6870173bcac 17 * This file is part of Mbed TLS (https://tls.mbed.org)
mbed_official 12:1ae41c231014 18 */
mbed_official 5:8275e4cee0d5 19
mbed_official 12:1ae41c231014 20 #if !defined(MBEDTLS_ENTROPY_HARDWARE_ALT) && \
mbed_official 12:1ae41c231014 21 !defined(MBEDTLS_ENTROPY_NV_SEED) && !defined(MBEDTLS_TEST_NULL_ENTROPY)
mbed_official 12:1ae41c231014 22 #error "This hardware does not have an entropy source."
mbed_official 12:1ae41c231014 23 #endif /* !MBEDTLS_ENTROPY_HARDWARE_ALT && !MBEDTLS_ENTROPY_NV_SEED &&
mbed_official 12:1ae41c231014 24 * !MBEDTLS_TEST_NULL_ENTROPY */
mbed_official 12:1ae41c231014 25
mbed_official 21:2089b3620a63 26 #if !defined(MBEDTLS_SHA1_C)
mbed_official 12:1ae41c231014 27 #define MBEDTLS_SHA1_C
mbed_official 21:2089b3620a63 28 #endif /* !MBEDTLS_SHA1_C */
mbed_official 5:8275e4cee0d5 29
mbed_official 12:1ae41c231014 30 /*
mbed_official 12:1ae41c231014 31 * This value is sufficient for handling 2048 bit RSA keys.
mbed_official 12:1ae41c231014 32 *
mbed_official 12:1ae41c231014 33 * Set this value higher to enable handling larger keys, but be aware that this
mbed_official 12:1ae41c231014 34 * will increase the stack usage.
mbed_official 12:1ae41c231014 35 */
mbed_official 93:eeb015d879ec 36 #undef MBEDTLS_MPI_MAX_SIZE
mbed_official 12:1ae41c231014 37 #define MBEDTLS_MPI_MAX_SIZE 256
mbed_official 5:8275e4cee0d5 38
mbed_official 95:d282bc7f32e4 39 /* This macro determines whether Mbed TLS uses its own legacy crypto library
mbed_official 95:d282bc7f32e4 40 * or an implementation of the PSA Crypto API such as Mbed Crypto.
mbed_official 95:d282bc7f32e4 41 *
mbed_official 95:d282bc7f32e4 42 * To confirm the use of PSA Crypto, you may enable debugging by setting
mbed_official 95:d282bc7f32e4 43 * HELLO_HTTPS_CLIENT_DEBUG_LEVEL in HelloHttpsClient.h and look for
mbed_official 95:d282bc7f32e4 44 * PSA-related debugging output on the serial line.
mbed_official 95:d282bc7f32e4 45 *
mbed_official 95:d282bc7f32e4 46 * Uncomment this to use the PSA Crypto API. */
mbed_official 95:d282bc7f32e4 47 //#define MBEDTLS_USE_PSA_CRYPTO
mbed_official 95:d282bc7f32e4 48
mbed_official 12:1ae41c231014 49 #define MBEDTLS_MPI_WINDOW_SIZE 1