Mbed TLS Examples on Mbed OS

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.

Getting started

Required hardware

• Any Mbed OS capable development board such as those listed here, which have an entropy source integrated into Mbed TLS. The single example that does not need an entropy source is hashing. The tls-client example should also have a network interface supported on your board.
• A micro-USB cable.

If your board has no hardware entropy source or its entropy source is not integrated with Mbed TLS, but you want to try these examples anyway, then you may want to consider compiling Mbed TLS without real entropy sources.

Warning! Without entropy sources Mbed TLS does not provide any security whatsoever. If you still want to compile Mbed TLS without entropy sources, then consult the section "How to test without entropy sources" in the Mbed TLS Porting Guide.

Required software

• Mbed CLI - to build the example program. To learn how to build Mbed OS applications with Mbed CLI, see the user guide
• Serial port monitor.

An alternative to Mbed CLI is to use the Mbed Online Compiler. In this case, you need to import the example projects from Mbed developer to your Mbed Online Compiler session using the links below:

• authcrypt
• benchmark
• hashing
• tls-client

Building and running the examples

The following example shows how to build and run on FRDM-K64F, but it should work on any Mbed OS capable device.

1. Clone the repository containing the collection of examples:

   $ git clone https://github.com/ARMmbed/mbed-os-example-tls
   

2. Open a command line tool and navigate to one of the project’s subdirectories.

3. Update mbed-os sources using the mbed deploy command.

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

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

6. Drag the binary BUILD/K64F/GCC_ARM/<EXAMPLE>.bin to the board to flash the application.

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

8. Press the RESET button on the board to run the program.

Monitoring the application

Please browse the subdirectories for specific documentation.

• authcrypt: performs authenticated encryption and authenticated decryption of a buffer.
• benchmark: benchmarks the various cryptographic primitives offered by Mbed TLS.
• hashing: performs hashing of a buffer with SHA-256 using various APIs.
• tls-client: downloads a file from an HTTPS server (os.mbed.com) and looks for a specific string in that file.

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 and connect to the virtual serial port presented by your board. Use the following settings:

• 9600 baud.
• 8N1.
• No flow control.

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.

License and contributions

The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see contributing.md for more info.

This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide.