mbed-os-examples / Mbed OS mbed-os-example-tls-tls-client

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!

Files at this revision

API Documentation at this revision

Revision 76:b8c07be20122, committed 2018-07-19

Comitter:
mbed_official
Date:
Thu Jul 19 09:00:06 2018 +0100
Parent:
75:98d7217a443d
Child:
77:6a727b3c3ef1
Commit message:
Merge pull request #174 from RonEld/seperate_server_name

Separate server name
.
Commit copied from https://github.com/ARMmbed/mbed-os-example-tls

Changed in this revision

HelloHttpsClient.cpp Show annotated file Show diff for this revision Revisions of this file
HelloHttpsClient.h Show annotated file Show diff for this revision Revisions of this file
easy-connect.lib Show annotated file Show diff for this revision Revisions of this file
main.cpp Show annotated file Show diff for this revision Revisions of this file 
--- a/HelloHttpsClient.cpp	Mon Jul 16 16:45:19 2018 +0100
+++ b/HelloHttpsClient.cpp	Thu Jul 19 09:00:06 2018 +0100
@@ -70,10 +70,12 @@
 const char *HelloHttpsClient::HTTP_OK_STR = "200 OK";
 
 HelloHttpsClient::HelloHttpsClient(const char *in_server_name,
+                                   const char *in_server_addr,
                                    const uint16_t in_server_port,
                                    mbedtls_platform_context* in_platform_ctx) :
     socket(),
     server_name(in_server_name),
+    server_addr(in_server_addr),
     server_port(in_server_port),
     /* The platform context is passed just in case any crypto calls need it.
      * Please refer to https://github.com/ARMmbed/mbedtls/issues/1200 for more
@@ -114,12 +116,12 @@
         return ret;
 
     /* Start a connection to the server */
-    if ((ret = socket.connect(server_name, server_port)) != NSAPI_ERROR_OK) {
+    if ((ret = socket.connect(server_addr, server_port)) != NSAPI_ERROR_OK) {
         mbedtls_printf("socket.connect() returned %d\n", ret);
         return ret;
     }
     mbedtls_printf("Successfully connected to %s at port %u\n",
-                   server_name, server_port);
+                   server_addr, server_port);
 
     /* Start the TLS handshake */
     mbedtls_printf("Starting the TLS handshake...\n");

--- a/HelloHttpsClient.h	Mon Jul 16 16:45:19 2018 +0100
+++ b/HelloHttpsClient.h	Thu Jul 19 09:00:06 2018 +0100
@@ -56,11 +56,14 @@
      * Construct an HelloHttpsClient instance
      *
      * \param[in]   in_server_name
+     *              The server host name
+     * \param[in]   in_server_addr
      *              The server domain/IP address
      * \param[in]   in_server_port
      *              The server port
      */
     HelloHttpsClient(const char *in_server_name,
+                     const char *in_server_addr,
                      const uint16_t in_server_port,
                      mbedtls_platform_context* in_platform_ctx);
 
@@ -192,9 +195,14 @@
     TCPSocket socket;
 
     /**
+     * The server host name to contact
+     */
+    const char *server_name;
+
+    /**
      * The domain/IP address of the server to contact
      */
-    const char *server_name;
+    const char *server_addr;
     /**
      * The port number to use in the connection
      */

--- a/easy-connect.lib	Mon Jul 16 16:45:19 2018 +0100
+++ b/easy-connect.lib	Thu Jul 19 09:00:06 2018 +0100
@@ -1,1 +1,1 @@
-https://github.com/ARMmbed/easy-connect/#6b2cce9f7cefd02e0503d6307ab5433b6197716d
+https://github.com/ARMmbed/easy-connect/#5b52b5fa56c623d5853c5daf266b34986a0c20cc

--- a/main.cpp	Mon Jul 16 16:45:19 2018 +0100
+++ b/main.cpp	Thu Jul 19 09:00:06 2018 +0100
@@ -40,6 +40,7 @@
 
 /* Domain/IP address of the server to contact */
 const char SERVER_NAME[] = "os.mbed.com";
+const char SERVER_ADDR[] = "os.mbed.com";
 
 /* Port used to connect to the server */
 const int SERVER_PORT = 443;
@@ -73,8 +74,9 @@
 #endif /* MBEDTLS_MAJOR_VERSION */
 
     /* Allocate a HTTPS client */
-    client = new (std::nothrow) HelloHttpsClient(SERVER_NAME, SERVER_PORT,
+    client = new (std::nothrow) HelloHttpsClient(SERVER_NAME, SERVER_ADDR, SERVER_PORT,
                                                  &platform_ctx);
+
     if (client == NULL) {
         mbedtls_printf("Failed to allocate HelloHttpsClient object\n"
                        "\nFAIL\n");