mirror of
https://github.com/yuzu-emu/mbedtls
synced 2024-11-25 04:38:59 +00:00
132 lines
6 KiB
Markdown
132 lines
6 KiB
Markdown
# HTTPS file downloader (TLS client example)
|
|
|
|
This application downloads a file from an HTTPS server (mbed.org) and looks for a specific string in that file.
|
|
|
|
This example is implemented as a logic class (HelloHTTPS) wrapping a TCP socket and a TLS context. The logic class handles all events, leaving the main loop to just check if the process has finished.
|
|
|
|
## Pre-requisites
|
|
|
|
To build and run this example the requirements below are necessary:
|
|
|
|
* A computer with the following software installed:
|
|
* [CMake](http://www.cmake.org/download/).
|
|
* [yotta](https://github.com/ARMmbed/yotta). Please note that **yotta has its own set of dependencies**, listed in the [installation instructions](http://armmbed.github.io/yotta/#installing-on-windows).
|
|
* [Python](https://www.python.org/downloads/).
|
|
* [ARM GCC toolchain](https://launchpad.net/gcc-arm-embedded).
|
|
* A serial terminal emulator (e.g. screen, pySerial, cu).
|
|
* An [FRDM-K64F](http://developer.mbed.org/platforms/FRDM-K64F/) development board, or another board that has an Ethernet port and is supported by mbed OS (in that case you'll have to substitute frdm-k64f-gcc with the appropriate target below).
|
|
* An Ethernet connection to the internet.
|
|
* An Ethernet cable.
|
|
* A micro-USB cable.
|
|
* If your OS is Windows, please follow the installation instructions [for the serial port driver](https://developer.mbed.org/handbook/Windows-serial-configuration).
|
|
|
|
## Getting started
|
|
|
|
1. Connect the FRDM-K64F to the internet using the ethernet cable.
|
|
|
|
2. Connect the FRDM-K64F to the computer with the micro-USB cable, being careful to use the micro-usb port labeled "OpenSDA".
|
|
|
|
3. Navigate to the mbedtls directory supplied with your release and open a terminal.
|
|
|
|
4. Set the yotta target:
|
|
|
|
```
|
|
yotta target frdm-k64f-gcc
|
|
```
|
|
|
|
5. Check that there are no missing dependencies:
|
|
|
|
```
|
|
$ yt ls
|
|
```
|
|
|
|
If there are, yotta will list them in the terminal. Please install them before proceeding.
|
|
|
|
5. Build mbedtls and the examples. This will take a long time if it is the first time:
|
|
|
|
```
|
|
$ yt build
|
|
```
|
|
|
|
7. Copy `build/frdm-k64f-gcc/test/mbedtls-test-example-tls-client.bin` to your mbed board and wait until the LED next to the USB port stops blinking.
|
|
|
|
8. Start the serial terminal emulator and connect to the virtual serial port presented by FRDM-K64F. For settings, use 115200 baud, 8N1, no flow control. **Warning:** for this example, the baud rate is not the default 9600, it is 115200.
|
|
|
|
9. Press the reset button on the board.
|
|
|
|
10. The output in the terminal window should look like:
|
|
|
|
```
|
|
{timeout;120}}
|
|
{{host_test_name;default}}
|
|
{{description;mbed TLS example HTTPS client}}
|
|
{{test_id;MBEDTLS_EX_HTTPS_CLIENT}}
|
|
{{start}}
|
|
|
|
|
|
Client IP Address is 192.168.0.2
|
|
Connecting to developer.mbed.org:443
|
|
developer.mbed.org address: 217.140.101.20
|
|
TLS connection to developer.mbed.org established
|
|
Server certificate:
|
|
cert. version : 3
|
|
serial number : 11:21:4E:4B:13:27:F0:89:21:FB:70:EC:3B:B5:73:5C:FF:B9
|
|
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 : 2015-03-05 10:31:02
|
|
expires on : 2016-03-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 469 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: Mon, 17 Aug 2015 11:46:19 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: Mon, 17 Aug 2015 21:46:19 GMT
|
|
X-Upstream-L3: 172.17.42.1:8080
|
|
X-Upstream-L2: developer-sjc-cyan-1-nginx
|
|
X-Upstream-L1-next-hop: 217.140.101.22:8001
|
|
X-Upstream-L1: developer-sjc-cyan-border-nginx
|
|
|
|
Hello world!
|
|
{{success}}
|
|
{{end}}
|
|
```
|
|
|
|
## Debugging the TLS connection
|
|
|
|
If you are experiencing problems with this example, you should first rule out network issues by making sure the [simple HTTP file downloader example](https://github.com/ARMmbed/mbed-example-network-private/tree/maste r/test/helloworld-tcpclient) for the TCP module works as expected. If not, please follow the debug instructions for this example.
|
|
|
|
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:
|
|
|
|
* 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.
|
|
|
|
If the TLS connection is failing with an error similar to:
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
it 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 `mbed.org` switches to a new CA when updating its certificate). Alternatively, this could mean someone is performing a man-in-the-middle attack on your connection. You can ignore this error and proceed with the connection anyway by changing the definition of `UNSAFE` near the top of the file from 0 to 1. **Warning:** this removes all security against an active attacker, use at your own risk, for debugging only!
|