Skip to content

Add mbed TLS benchmark example #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 20, 2016
Merged

Add mbed TLS benchmark example #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2460702
Add mbed TLS benchmark example
Jul 8, 2016
3fdace0
Fix benchmark code and documentation
Jul 19, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 23 additions & 93 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,121 +1,51 @@
# HTTPS File Download Example for TLS Client on mbed OS
# mbed TLS Examples on mbedOS

This application downloads a file from an HTTPS server (developer.mbed.org) and looks for a specific string in that file.
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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the specific documentations refer back to this one for the instructions setting up the environment, we may want to move this line in the monitoring the application section and also provide links to the specific Readme.md files.

## Required hardware
# Getting started

## Required hardware
* An [FRDM-K64F](http://developer.mbed.org/platforms/FRDM-K64F/) development board.
* A micro-USB cable.
* An Ethernet cable and connection to the internet.

## Required software
* [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)
* [Serial port monitor](https://developer.mbed.org/handbook/SerialPC#host-interface-and-terminal-applications).

## Getting started

1. Clone [this](https://github.com/ARMmbed/mbed-tls-sample) repository.
## Building and running the examples

2. Open a command line tool and navigate to the project’s directory.
1. Clone the repository containing the collection of examples:
```
$ git clone https://github.com/ARMmbed/mbed-os-example-tls
```

3. Update `mbed-os` sources using the `mbed update` command.
1. Open a command line tool and navigate to one of the project’s subdirectories.

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.
1. Update `mbed-os` sources using the `mbed deploy` command.

5. Connect the FRDM-K64F to the internet using the Ethernet cable.
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.

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.
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.

7. Drag the binary `.build/K64F/GCC_ARM/mbed-tls-sample.bin` to the board to flash the application.
1. Drag the binary `.build/K64F/GCC_ARM/<EXAMPLE>.bin` to the board to flash the application.

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.
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.

9. Press the **RESET** button on the board to run the program.
1. Press the **RESET** button on the board to run the program.

## Monitoring the application

Please browse the subdirectories for specific documentation.
* [Benchmark](./benchmark/README.md)

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:

* 115200 baud (not 9600).
* 8N1.
* No flow control.

After pressing the **RESET** button on the board, the output in the terminal window should be similar to this:

{{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
Starting DNS lookup for developer.mbed.org
DNS Response Received:
developer.mbed.org: 217.140.101.30
Connecting to 217.140.101.30:443
Connected to 217.140.101.30:443
Starting the TLS handshake...
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 473 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: Tue, 18 Aug 2015 18:34:04 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, 19 Aug 2015 04:34:04 GMT
X-Upstream-L3: 172.17.42.1:8080
X-Upstream-L2: developer-sjc-indigo-2-nginx
X-Upstream-L1-next-hop: 217.140.101.86:8001
X-Upstream-L1: developer-sjc-indigo-border-nginx

Hello world!
{{success}}
{{end}}

## Debugging the TLS connection

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.


The TLS connection can fail 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

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!
After pressing the **RESET** button on the board, you should be able to observe the application's output.

## Debugging mbed TLS

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.
45 changes: 45 additions & 0 deletions benchmark/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# mbed TLS Benchmark example on mbed OS

This application benchmarks the various cryptographic primitives offered by mbed TLS.

# Getting started

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These three sections may be replaced something like this:
"Set up your environment if you haven't done it already. For instructions read the main readme."

Set up your environment if you have not done so already. For instructions, refer to the [main readme](../README.md).

## Monitoring the application

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

```
SHA-256 : 1673 Kb/s, 70 cycles/byte
SHA-512 : 546 Kb/s, 215 cycles/byte
AES-CBC-128 : 1428 Kb/s, 82 cycles/byte
AES-CBC-192 : 1260 Kb/s, 93 cycles/byte
AES-CBC-256 : 1127 Kb/s, 104 cycles/byte
AES-GCM-128 : 486 Kb/s, 242 cycles/byte
AES-GCM-192 : 464 Kb/s, 253 cycles/byte
AES-GCM-256 : 445 Kb/s, 264 cycles/byte
AES-CCM-128 : 610 Kb/s, 192 cycles/byte
AES-CCM-192 : 547 Kb/s, 214 cycles/byte
AES-CCM-256 : 496 Kb/s, 237 cycles/byte
CTR_DRBG (NOPR) : 1139 Kb/s, 102 cycles/byte
CTR_DRBG (PR) : 826 Kb/s, 142 cycles/byte
HMAC_DRBG SHA-256 (NOPR) : 193 Kb/s, 611 cycles/byte
HMAC_DRBG SHA-256 (PR) : 170 Kb/s, 695 cycles/byte
RSA-2048 : 28 ms/ public
RSA-2048 : 953 ms/private
RSA-4096 : 93 ms/ public
RSA-4096 : 5327 ms/private
ECDSA-secp384r1 : 451 ms/sign
ECDSA-secp256r1 : 304 ms/sign
ECDSA-secp384r1 : 863 ms/verify
ECDSA-secp256r1 : 594 ms/verify
ECDHE-secp384r1 : 829 ms/handshake
ECDHE-secp256r1 : 566 ms/handshake
ECDHE-Curve25519 : 533 ms/handshake
ECDH-secp384r1 : 407 ms/handshake
ECDH-secp256r1 : 281 ms/handshake
ECDH-Curve25519 : 268 ms/handshake

DONE
```
Loading