|
1 | | -# HTTPS File Download Example for TLS Client on mbed OS |
| 1 | +# mbed TLS Examples on mbedOS |
2 | 2 |
|
3 | | -This application downloads a file from an HTTPS server (developer.mbed.org) and looks for a specific string in that file. |
| 3 | +This repository contains a collection of mbed TLS example applications based on mbed OS. Each subdirectory contains a separate example meant for building as an executable. |
4 | 4 |
|
5 | | -## Required hardware |
| 5 | +# Getting started |
6 | 6 |
|
| 7 | +## Required hardware |
7 | 8 | * An [FRDM-K64F](http://developer.mbed.org/platforms/FRDM-K64F/) development board. |
8 | 9 | * A micro-USB cable. |
9 | | -* An Ethernet cable and connection to the internet. |
10 | 10 |
|
11 | 11 | ## Required software |
12 | 12 | * [mbed CLI](https://github.com/ARMmbed/mbed-cli) - to build the example program. To learn how to build mbed OS applications with mbed CLI, see the [user guide](https://github.com/ARMmbed/mbed-cli/blob/master/README.md) |
13 | 13 | * [Serial port monitor](https://developer.mbed.org/handbook/SerialPC#host-interface-and-terminal-applications). |
14 | 14 |
|
15 | | -## Getting started |
16 | | - |
17 | | -1. Clone [this](https://github.com/ARMmbed/mbed-tls-sample) repository. |
| 15 | +## Building and running the examples |
18 | 16 |
|
19 | | -2. Open a command line tool and navigate to the project’s directory. |
| 17 | +1. Clone the repository containing the collection of examples: |
| 18 | + ``` |
| 19 | + $ git clone https://github.com/ARMmbed/mbed-os-example-tls |
| 20 | + ``` |
20 | 21 |
|
21 | | -3. Update `mbed-os` sources using the `mbed update` command. |
| 22 | +1. Open a command line tool and navigate to one of the project’s subdirectories. |
22 | 23 |
|
23 | | -4. Build the application by selecting the board and build toolchain using the command `mbed compile -m K64F -t GCC_ARM -c -j0`. mbed-cli builds a binary file under the project’s `.build` directory. |
| 24 | +1. Update `mbed-os` sources using the `mbed deploy` command. |
24 | 25 |
|
25 | | -5. Connect the FRDM-K64F to the internet using the Ethernet cable. |
| 26 | +1. Build the application by selecting the board and build toolchain using the command `mbed compile -m K64F -t GCC_ARM`. mbed-cli builds a binary file under the project’s `.build` directory. |
26 | 27 |
|
27 | | -6. Connect the FRDM-K64F to the computer with the micro-USB cable, being careful to use the **OpenSDA** connector on the target board. The board is listed as a mass-storage device. |
| 28 | +1. Connect the FRDM-K64F to the computer with the micro-USB cable, being careful to use the **OpenSDA** connector on the target board. The board is listed as a mass-storage device. |
28 | 29 |
|
29 | | -7. Drag the binary `.build/K64F/GCC_ARM/mbed-tls-sample.bin` to the board to flash the application. |
| 30 | +1. Drag the binary `.build/K64F/GCC_ARM/<EXAMPLE>.bin` to the board to flash the application. |
30 | 31 |
|
31 | | -8. The board is automatically programmed with the new binary. A flashing LED on it indicates that it is still working. When the LED stops blinking, the board is ready to work. |
| 32 | +1. The board is automatically programmed with the new binary. A flashing LED on it indicates that it is still working. When the LED stops blinking, the board is ready to work. |
32 | 33 |
|
33 | | -9. Press the **RESET** button on the board to run the program. |
| 34 | +1. Press the **RESET** button on the board to run the program. |
34 | 35 |
|
35 | 36 | ## Monitoring the application |
36 | 37 |
|
| 38 | +Please browse the subdirectories for specific documentation. |
| 39 | +* [Benchmark](./benchmark/README.md) |
| 40 | +
|
37 | 41 | The application prints debug messages over the serial port, so you can monitor its activity with a serial terminal emulator. Start the [serial terminal emulator](https://developer.mbed.org/handbook/Terminals) and connect to the [virtual serial port](https://developer.mbed.org/handbook/SerialPC#host-interface-and-terminal-applications) presented by FRDM-K64F. Use the following settings: |
38 | 42 |
|
39 | 43 | * 115200 baud (not 9600). |
40 | 44 | * 8N1. |
41 | 45 | * No flow control. |
42 | 46 |
|
43 | | -After pressing the **RESET** button on the board, the output in the terminal window should be similar to this: |
44 | | - |
45 | | - {{timeout;120}} |
46 | | - {{host_test_name;default}} |
47 | | - {{description;mbed TLS example HTTPS client}} |
48 | | - {{test_id;MBEDTLS_EX_HTTPS_CLIENT}} |
49 | | - {{start}} |
50 | | - |
51 | | - Client IP Address is 192.168.0.2 |
52 | | - Starting DNS lookup for developer.mbed.org |
53 | | - DNS Response Received: |
54 | | - developer.mbed.org: 217.140.101.30 |
55 | | - Connecting to 217.140.101.30:443 |
56 | | - Connected to 217.140.101.30:443 |
57 | | - Starting the TLS handshake... |
58 | | - TLS connection to developer.mbed.org established |
59 | | - Server certificate: |
60 | | - cert. version : 3 |
61 | | - serial number : 11:21:4E:4B:13:27:F0:89:21:FB:70:EC:3B:B5:73:5C:FF:B9 |
62 | | - issuer name : C=BE, O=GlobalSign nv-sa, CN=GlobalSign Organization Validation CA - SHA256 - G2 |
63 | | - subject name : C=GB, ST=Cambridgeshire, L=Cambridge, O=ARM Ltd, CN=*.mbed.com |
64 | | - issued on : 2015-03-05 10:31:02 |
65 | | - expires on : 2016-03-05 10:31:02 |
66 | | - signed using : RSA with SHA-256 |
67 | | - RSA key size : 2048 bits |
68 | | - basic constraints : CA=false |
69 | | - subject alt name : *.mbed.com, *.mbed.org, mbed.org, mbed.com |
70 | | - key usage : Digital Signature, Key Encipherment |
71 | | - ext key usage : TLS Web Server Authentication, TLS Web Client Authentication |
72 | | - Certificate verification passed |
73 | | - |
74 | | - HTTPS: Received 473 chars from server |
75 | | - HTTPS: Received 200 OK status ... [OK] |
76 | | - HTTPS: Received 'Hello world!' status ... [OK] |
77 | | - HTTPS: Received message: |
78 | | - |
79 | | - HTTP/1.1 200 OK |
80 | | - Server: nginx/1.7.10 |
81 | | - Date: Tue, 18 Aug 2015 18:34:04 GMT |
82 | | - Content-Type: text/plain |
83 | | - Content-Length: 14 |
84 | | - Connection: keep-alive |
85 | | - Last-Modified: Fri, 27 Jul 2012 13:30:34 GMT |
86 | | - Accept-Ranges: bytes |
87 | | - Cache-Control: max-age=36000 |
88 | | - Expires: Wed, 19 Aug 2015 04:34:04 GMT |
89 | | - X-Upstream-L3: 172.17.42.1:8080 |
90 | | - X-Upstream-L2: developer-sjc-indigo-2-nginx |
91 | | - X-Upstream-L1-next-hop: 217.140.101.86:8001 |
92 | | - X-Upstream-L1: developer-sjc-indigo-border-nginx |
93 | | - |
94 | | - Hello world! |
95 | | - {{success}} |
96 | | - {{end}} |
97 | | - |
98 | | -## Debugging the TLS connection |
99 | | - |
100 | | -To print out more debug information about the TLS connection, edit the file `source/main.cpp` and change the definition of `DEBUG_LEVEL` (near the top of the file) from 0 to a positive number: |
101 | | - |
102 | | -* Level 1 only prints non-zero return codes from SSL functions and information about the full certificate chain being verified. |
103 | | - |
104 | | -* Level 2 prints more information about internal state updates. |
105 | | - |
106 | | -* Level 3 is intermediate. |
107 | | - |
108 | | -* Level 4 (the maximum) includes full binary dumps of the packets. |
109 | | - |
110 | | - |
111 | | -The TLS connection can fail with an error similar to: |
112 | | - |
113 | | - mbedtls_ssl_write() failed: -0x2700 (-9984): X509 - Certificate verification failed, e.g. CRL, CA or signature check failed |
114 | | - Failed to fetch /media/uploads/mbed_official/hello.txt from developer.mbed.org:443 |
115 | | - |
116 | | -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). |
117 | | - |
118 | | -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. |
119 | | - |
120 | | -**Warning:** this removes all security against a possible active attacker, so use at your own risk or for debugging only! |
| 47 | +After pressing the **RESET** button on the board, you should be able to observe the application's output. |
| 48 | +
|
| 49 | +## Debugging mbed TLS |
121 | 50 |
|
| 51 | +To optionally print out more debug information, edit the `main.cpp` for the sample and change the definition of `DEBUG_LEVEL` (near the top of the file) from 0 to a positive number between 1 and 4. |
0 commit comments