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 10.2.203.43
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-L3: 172.17.0.3:80
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!

Revisions of mbed-os.lib

Revision Date Message Actions
55:33095a875ab0 2018-01-02 Merge pull request #139 from ARMmbed/mbed-os-5.7.0-oob File  Diff  Annotate
53:f8f870f572b0 2017-12-04 Merge pull request #132 from adbridge/master File  Diff  Annotate
52:b22178490e3e 2017-11-22 Merge pull request #131 from adbridge/master File  Diff  Annotate
51:bef91d415b35 2017-11-21 Merge pull request #130 from adbridge/master File  Diff  Annotate
48:bc15de2d00db 2017-11-07 Merge pull request #127 from adbridge/master File  Diff  Annotate
46:3091c2387c57 2017-10-24 Merge pull request #124 from 0xc0170/master File  Diff  Annotate
45:42fad9edd56c 2017-10-09 Merge pull request #121 from adbridge/master File  Diff  Annotate
44:a1dff81a34dc 2017-10-02 Merge pull request #120 from adbridge/master File  Diff  Annotate
43:3c67414f345e 2017-09-29 Merge pull request #119 from andresag01/master File  Diff  Annotate
42:5236ebc3d12a 2017-09-20 Merge pull request #117 from andresag01/change-mbed-server-address File  Diff  Annotate
41:6fdcfbaef261 2017-08-30 Merge pull request #113 from adbridge/master File  Diff  Annotate
40:173959655eff 2017-08-17 Merge pull request #112 from andresag01/fix-hw-accel-failure File  Diff  Annotate
39:33ff7af3cd4f 2017-08-03 Merge pull request #110 from 0xc0170/master File  Diff  Annotate
38:3ef3e6b59e3e 2017-07-18 Merge pull request #108 from 0xc0170/master File  Diff  Annotate
37:2ab87c335df4 2017-07-11 Merge pull request #99 from adbridge/master File  Diff  Annotate
36:fd4d8cbf1e73 2017-06-22 Merge pull request #97 from adbridge/master File  Diff  Annotate
35:2f3200841ab4 2017-06-20 Merge pull request #96 from adbridge/master File  Diff  Annotate
34:9b147beb7989 2017-06-07 Merge pull request #89 from adbridge/master File  Diff  Annotate
32:7f535dfb1fb7 2017-05-26 Merge pull request #85 from adbridge/master File  Diff  Annotate
31:305d46f8446a 2017-05-10 Merge pull request #83 from adbridge/master File  Diff  Annotate
30:5e6843a55b68 2017-04-27 Merge pull request #82 from 0xc0170/master File  Diff  Annotate
29:ab5f4d8151ab 2017-04-11 Merge pull request #81 from adbridge/master File  Diff  Annotate
28:630c5497364b 2017-04-03 Merge pull request #78 from 0xc0170/master File  Diff  Annotate
27:f52b73d94bc3 2017-03-17 Merge pull request #72 from ARMmbed/oob-test-mbed-os-5.4.1 File  Diff  Annotate
26:82d3d714e6fe 2017-03-09 Merge pull request #64 from andresag01/oob_test_mbed-os-5.4 File  Diff  Annotate
25:04dfadb2ddc5 2017-03-01 Merge pull request #50 from adbridge/master File  Diff  Annotate
24:c7f5fe68a574 2017-02-15 Merge pull request #48 from 0xc0170/master File  Diff  Annotate
23:8dfc26a40e62 2017-01-31 Merge pull request #44 from adbridge/master File  Diff  Annotate
19:78aa08a4676d 2017-01-16 Merge pull request #39 from adbridge/master File  Diff  Annotate
18:88d17db9cad2 2017-01-04 Merge pull request #37 from adbridge/master File  Diff  Annotate
17:05377fa05603 2016-12-21 Merge pull request #36 from adbridge/master File  Diff  Annotate
16:6938416b4d53 2016-12-16 Update mbed-os.lib to point to the updated mbed-os-5.3.0 version of File  Diff  Annotate
15:5c6a203ff133 2016-12-15 Merge pull request #35 from ARMmbed/mbed-os-5.3.0 File  Diff  Annotate
14:339320b096c5 2016-10-28 Updating mbed-os to mbed-os-5.2.1 File  Diff  Annotate
13:b7c627487d5a 2016-10-24 Updating mbed-os to mbed-os-5.2.0 File  Diff  Annotate
12:1ae41c231014 2016-10-21 Updating mbed-os to mbed-os-5.2.0-rc4 File  Diff  Annotate
11:bbdd078dac9e 2016-10-05 Updating mbed-os to mbed-os-5.1.5 File  Diff  Annotate
10:f4fc50022e71 2016-09-16 Updating mbed-os to mbed-os-5.1.4 File  Diff  Annotate
8:50d4701593ad 2016-08-20 Updating mbed-os to mbed-os-5.1.2 File  Diff  Annotate
7:d55d5e6aed50 2016-08-19 Updating mbed-os to mbed-os-5.1.1 File  Diff  Annotate
6:3cca7629501b 2016-08-05 Updating mbed-os to mbed-os-5.1.0 File  Diff  Annotate
4:880181829f9a 2016-08-03 Updating mbed-os to mbed-os-5.1.0-rc5 File  Diff  Annotate
3:f899889c22af 2016-07-30 Updating mbed-os to mbed-os-5.1.0-rc4 File  Diff  Annotate
1:29b9860f1cac 2016-07-28 Update example home repo at https://github.com/ARMmbed/mbed-os-example-tls File  Diff  Annotate
0:fc70c47eecb4 2016-07-27 Update example home repo at The canonical source for this example lives at https://github.com/ARMmbed/mbed-os-example-tls File  Diff  Annotate