From df81924a7a968caccf26484be0955298a1b15465 Mon Sep 17 00:00:00 2001 From: Simon Butcher Date: Wed, 19 Aug 2015 19:33:27 +0100 Subject: [PATCH] Fixed issues in Yotta examples README's Fixed README's in Yotta examples and updated certificate reference in TLS Client. --- yotta/data/README.md | 24 ++++++++++++------------ yotta/data/example-authcrypt/README.md | 18 +++++++++--------- yotta/data/example-benchmark/README.md | 16 ++++++++-------- yotta/data/example-hashing/README.md | 19 ++++++++++--------- yotta/data/example-selftest/README.md | 18 +++++++++--------- yotta/data/example-tls-client/README.md | 25 +++++++++++++------------ yotta/data/example-tls-client/main.cpp | 7 +++++-- 7 files changed, 66 insertions(+), 61 deletions(-) diff --git a/yotta/data/README.md b/yotta/data/README.md index 10412a1e0..c737f2a67 100644 --- a/yotta/data/README.md +++ b/yotta/data/README.md @@ -1,30 +1,30 @@ # mbed TLS -mbed TLS (formerly known as PolarSSL) makes it trivially easy for developers to include cryptographic and SSL/TLS capabilities in their (embedded) products, facilitating this functionality with a minimal coding footprint. It offers an SSL library with an intuitive API and readable source code. +mbed TLS (formerly known as PolarSSL) makes it trivially easy for developers to include cryptographic and SSL/TLS capabilities in their embedded products, with a minimal code footprint. It offers an SSL library with an intuitive API and readable source code. -The Beta release of mbed TLS is an integration of mbed TLS in mbed OS. It is a testing preview only and **not suitable for deployment**: there is currently no source of random numbers, meaning no security at all for (D)TLS communication and other protocols that rely on random numbers. +The Beta release of mbed TLS integrates the mbed TLS library into mbed OS, mbed SDK and yotta. This is a preview release intended for evaluation only and is **not recommended for deployment**. This implementation currently implements no secure source of random numbers, weakening it's security. ## Sample programs This release includes the following examples: -1. [**TLS client:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-tls-client) found in `tests/example-tls-client`, downloads a file from an HTTPS server (mbed.org) and looks for a specific string in that file. +1. [**TLS client:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-tls-client) found in `test/example-tls-client`, downloads a test file from an HTTPS server and looks for a specific string in that file. -2. [**Self test:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-selftest) found in `tests/example-selftest`, tests different mbed TLS base functionalities. +2. [**Self test:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-selftest) found in `test/example-selftest`, tests different basic functions in the mbed TLS library. -3. [**Benchmark:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-benchmark) found in `tests/example-benchmark`, tests the time required to perform TLS base crypto functions. +3. [**Benchmark:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-benchmark) found in `test/example-benchmark`, measures the time taken to perform basic cryptographic functions used in the library. -These examples are integrated as yotta tests so that they are build automatically when you build mbed TLS. You'll find other examples in the various `tests/example-*` directories. +These examples are integrated as yotta tests so that they are built automatically when you build mbed TLS. You'll find other examples in the various `test/example-*` directories alongside these examples. ## Running TLS -Please follow the instructions in the [TLS client sample](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-tls-client). These include a list of prerequisites and an explanation of building mbed TLS with yotta. +Please follow the instructions in the [TLS client sample](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-tls-client) directory, to build and run the example. These include a list of prerequisites and an explanation of building mbed TLS with yotta. ## Configuring mbed TLS features -mbed TLS makes it easy to disable during the compilation any feature that is not needed for a particular project. The default configuration enables all modern and widely-used features, which should meet the need of any new project; it disables all features that are either older or less mainstrem, in order to keep the footprint low. The list of available compile flags is available in the fully documented [config.h file](https://github.com/ARMmbed/mbedtls/blob/development/include/mbedtls/config.h), present in the `mbedtls` directory of the yotta module. +mbed TLS makes it easy to disable any feature during compilation that isn't required for a particular project. The default configuration enables all modern and widely-used features which should meet the needs of new projects and disables all features that are older or less common, to minimise the code footprint. The list of available compilation flags is available in the fully documented [config.h file](https://github.com/ARMmbed/mbedtls/blob/development/include/mbedtls/config.h), present in the `mbedtls` directory of the yotta module. -Should you need to adjust those flags, you can provide your own configuration file with the suitable `#define` and `#undef` statements, to be included between the default definitions and the sanity checks. This file should be in your application's include directory and can be named freely; you just need to let mbed TLS know the name of the file, by using yotta's [configuration system](http://docs.yottabuild.org/reference/config.html). This name should go in your `config.json`, under mbedtls, as the key `user-config-file`, for example: +Should you need to adjust those flags, you can provide your own configuration file with suitable `#define` and `#undef` statements, to be included between the default definitions and the sanity checks. This file should be in your application's include directory and can be named freely; you just need to let mbed TLS know the name of the file, by using yotta's [configuration system](http://docs.yottabuild.org/reference/config.html). This name should go in your `config.json`, under mbedtls, as the key `user-config-file`, for example: { "mbedtls": { @@ -36,11 +36,11 @@ Please note you need to provide the exact name that will be used in the `#includ ## Contributing -We graciously accept bugs and contributions from the community. There are some requirements we need to fulfil in order to be able to integrate contributions in the main code: +We gratefully accept bugs and contributions from the community. There are some requirements we need to fulfil in order to be able to integrate contributions: -* Simple bug fixes to existing code do not contain copyright themselves and we can integrate those without any issue. The same goes for trivial contributions. +* Simple bug fixes to existing code do not contain copyright themselves and we can integrate without issue. The same s true of trivial contributions. -* For larger contributions, e.g. a new feature, the code possibly falls under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for that, which we will mail to you in case you submit a contribution or pull request that we deem this necessary for. +* For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will mail to you in case you submit a contribution or pull request that we deem this necessary for. To contribute, please: diff --git a/yotta/data/example-authcrypt/README.md b/yotta/data/example-authcrypt/README.md index 55186d19d..9641f8183 100644 --- a/yotta/data/example-authcrypt/README.md +++ b/yotta/data/example-authcrypt/README.md @@ -1,10 +1,10 @@ -# Authenticated encryption example +# Authenticated Encryption Example This application performs authenticated encryption and authenticated decryption of a buffer. It serves as a tutorial for the basic authenticated encryption functions of mbed TLS. ## Pre-requisites -To build and run this example the requirements below are necessary: +To build and run this example the following requirements are necessary: * A computer with the following software installed: * [CMake](http://www.cmake.org/download/). @@ -12,13 +12,13 @@ To build and run this example the requirements below are necessary: * [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 supported by mbed OS (in that case you'll have to substitute frdm-k64f-gcc with the appropriate target below). +* An [FRDM-K64F](http://developer.mbed.org/platforms/FRDM-K64F/) development board, or another board supported by mbed OS (in which case you'll have to substitute frdm-k64f-gcc with the appropriate target in the instructions below). * 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 computer with the micro-USB cable, being careful to use the micro-usb port labeled "OpenSDA". +1. Connect the FRDM-K64F to the computer with the micro-USB cable, being careful to use the "OpenSDA" connector on the target board. 2. Navigate to the mbedtls directory supplied with your release and open a terminal. @@ -31,15 +31,15 @@ To build and run this example the requirements below are necessary: 4. Check that there are no missing dependencies: ``` - $ yt ls + $ yotta 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: + If there are missing dependencies, yotta will list them in the terminal. Please install these before proceeding. + +5. Build mbedtls and the examples. This may take a long time if this is your first compilation: ``` - $ yt build + $ yotta build ``` 6. Copy `build/frdm-k64f-gcc/test/mbedtls-test-example-authcrypt.bin` to your mbed board and wait until the LED next to the USB port stops blinking. diff --git a/yotta/data/example-benchmark/README.md b/yotta/data/example-benchmark/README.md index dfdc965db..25d4ef549 100644 --- a/yotta/data/example-benchmark/README.md +++ b/yotta/data/example-benchmark/README.md @@ -1,10 +1,10 @@ -# mbed TLS benchmark +# mbed TLS Benchmark Example This application benchmarks the various cryptographic primitives offered by mbed TLS. ## Pre-requisites -To build and run this example the requirements below are necessary: +To build and run this example the following requirements are necessary: * A computer with the following software installed: * [CMake](http://www.cmake.org/download/). @@ -12,13 +12,13 @@ To build and run this example the requirements below are necessary: * [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 supported by mbed OS (in that case you'll have to substitute frdm-k64f-gcc with the appropriate target below). +* An [FRDM-K64F](http://developer.mbed.org/platforms/FRDM-K64F/) development board, or another board supported by mbed OS (in which case you'll have to substitute frdm-k64f-gcc with the appropriate target in the instructions below). * 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 computer with the micro-USB cable, being careful to use the micro-usb port labeled "OpenSDA". +1. Connect the FRDM-K64F to the computer with the micro-USB cable, being careful to use the "OpenSDA" connector on the target board. 2. Navigate to the mbedtls directory supplied with your release and open a terminal. @@ -31,15 +31,15 @@ To build and run this example the requirements below are necessary: 4. Check that there are no missing dependencies: ``` - $ yt ls + $ yotta ls ``` - If there are, yotta will list them in the terminal. Please install them before proceeding. + If there are missing dependencies, yotta will list them in the terminal. Please install these before proceeding. -5. Build mbedtls and the examples. This will take a long time if it is the first time: +5. Build mbedtls and the examples. This may take a long time if this is your first compilation: ``` - $ yt build + $ yotta build ``` 6. Copy `build/frdm-k64f-gcc/test/mbedtls-test-example-benchmark.bin` to your mbed board and wait until the LED next to the USB port stops blinking. diff --git a/yotta/data/example-hashing/README.md b/yotta/data/example-hashing/README.md index ed941cfcc..74f12a0f6 100644 --- a/yotta/data/example-hashing/README.md +++ b/yotta/data/example-hashing/README.md @@ -1,10 +1,10 @@ -# Hashing tutorial +# SHA-256 Hash Example This application performs hashing of a buffer with SHA-256 using various APIs. It serves as a tutorial for the basic hashing APIs of mbed TLS. ## Pre-requisites -To build and run this example the requirements below are necessary: +To build and run this example the following requirements are necessary: * A computer with the following software installed: * [CMake](http://www.cmake.org/download/). @@ -12,13 +12,13 @@ To build and run this example the requirements below are necessary: * [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 supported by mbed OS (in that case you'll have to substitute frdm-k64f-gcc with the appropriate target below). +* An [FRDM-K64F](http://developer.mbed.org/platforms/FRDM-K64F/) development board, or another board supported by mbed OS (in which case you'll have to substitute frdm-k64f-gcc with the appropriate target in the instructions below). * 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 computer with the micro-USB cable, being careful to use the micro-usb port labeled "OpenSDA". +1. Connect the FRDM-K64F to the computer with the micro-USB cable, being careful to use the "OpenSDA" connector on the target board. 2. Navigate to the mbedtls directory supplied with your release and open a terminal. @@ -31,15 +31,16 @@ To build and run this example the requirements below are necessary: 4. Check that there are no missing dependencies: ``` - $ yt ls + $ yotta 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: + If there are missing dependencies, yotta will list them in the terminal. Please install these before proceeding. + +5. Build mbedtls and the examples. This may take a long time if this is your first compilation: ``` - $ yt build + $ yotta build ``` 6. Copy `build/frdm-k64f-gcc/test/mbedtls-test-example-hashing.bin` to your mbed board and wait until the LED next to the USB port stops blinking. diff --git a/yotta/data/example-selftest/README.md b/yotta/data/example-selftest/README.md index 0ded4041c..1995e27a6 100644 --- a/yotta/data/example-selftest/README.md +++ b/yotta/data/example-selftest/README.md @@ -1,10 +1,10 @@ -# mbed TLS selftest programs +# mbed TLS Selftest Example -This application runs the various selftest function of individual mbed TLS components. It serves as a basic sanity check for mbed TLS on your platform. In the future, a wider portion of the mbed TLS test suite will be ported on mbed OS. +This application runs the various selftest function of individual mbed TLS components. It serves as a basic sanity check to verify operation of mbed TLS on your platform. In the future, a wider portion of the mbed TLS test suite will become part of this example application. ## Pre-requisites -To build and run this example the requirements below are necessary: +To build and run this example the following requirements are necessary: * A computer with the following software installed: * [CMake](http://www.cmake.org/download/). @@ -12,13 +12,13 @@ To build and run this example the requirements below are necessary: * [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 supported by mbed OS (in that case you'll have to substitute frdm-k64f-gcc with the appropriate target below). +* An [FRDM-K64F](http://developer.mbed.org/platforms/FRDM-K64F/) development board, or another board supported by mbed OS (in which case you'll have to substitute frdm-k64f-gcc with the appropriate target in the instructions below). * 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 computer with the micro-USB cable, being careful to use the micro-usb port labeled "OpenSDA". +1. Connect the FRDM-K64F to the computer with the micro-USB cable, being careful to use the "OpenSDA" connector on the target board. 2. Navigate to the mbedtls directory supplied with your release and open a terminal. @@ -31,15 +31,15 @@ To build and run this example the requirements below are necessary: 4. Check that there are no missing dependencies: ``` - $ yt ls + $ yotta ls ``` - If there are, yotta will list them in the terminal. Please install them before proceeding. + If there are missing dependencies, yotta will list them in the terminal. Please install these before proceeding. -5. Build mbedtls and the examples. This will take a long time if it is the first time: +5. Build mbedtls and the examples. This may take a long time if this is your first compilation: ``` - $ yt build + $ yotta build ``` 6. Copy `build/frdm-k64f-gcc/test/mbedtls-test-example-selftest.bin` to your mbed board and wait until the LED next to the USB port stops blinking. diff --git a/yotta/data/example-tls-client/README.md b/yotta/data/example-tls-client/README.md index beddd7b59..7bca1adfd 100644 --- a/yotta/data/example-tls-client/README.md +++ b/yotta/data/example-tls-client/README.md @@ -1,12 +1,12 @@ -# HTTPS file downloader (TLS client example) +# HTTPS File Download Example/ TLS Client -This application downloads a file from an HTTPS server (mbed.org) and looks for a specific string in that file. +This application downloads a file from an HTTPS server (developer.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: +To build and run this example the following requirements are necessary: * A computer with the following software installed: * [CMake](http://www.cmake.org/download/). @@ -14,9 +14,9 @@ To build and run this example the requirements below are necessary: * [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. +* 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 which case you'll have to substitute frdm-k64f-gcc with the appropriate target in the instructions 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). @@ -24,7 +24,7 @@ To build and run this example the requirements below are necessary: 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". +2. Connect the FRDM-K64F to the computer with the micro-USB cable, being careful to use the "OpenSDA" connector on the target board. 3. Navigate to the mbedtls directory supplied with your release and open a terminal. @@ -37,15 +37,15 @@ To build and run this example the requirements below are necessary: 5. Check that there are no missing dependencies: ``` - $ yt ls + $ yotta ls ``` - If there are, yotta will list them in the terminal. Please install them before proceeding. + If there are missing dependencies, yotta will list them in the terminal. Please install these before proceeding. 5. Build mbedtls and the examples. This will take a long time if it is the first time: ``` - $ yt build + $ yotta 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. @@ -54,7 +54,7 @@ To build and run this example the requirements below are necessary: 9. Press the reset button on the board. -10. The output in the terminal window should look like: +10. The output in the terminal window should look similar to this: ``` {timeout;120}} @@ -122,6 +122,7 @@ To print out more debug information about the TLS connection, edit the file `sou * Level 4 (the maximum) includes full binary dumps of the packets. + If the TLS connection is failing with an error similar to: ``` @@ -129,4 +130,4 @@ If the TLS connection is failing with an error similar to: 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! +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 `developer.mbed.org` switches to a new CA when updating its certificate). Another reason for this error may be a proxy providing a different certificate. Proxys 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 attacker, therefore use at your own risk, or for debugging only! diff --git a/yotta/data/example-tls-client/main.cpp b/yotta/data/example-tls-client/main.cpp index 56be087c9..aeb913aaf 100644 --- a/yotta/data/example-tls-client/main.cpp +++ b/yotta/data/example-tls-client/main.cpp @@ -78,10 +78,13 @@ const char *HTTPS_HELLO_STR = "Hello world!"; const char *DRBG_PERS = "mbed TLS helloword client"; /* List of trusted root CA certificates - * currently just Verisign since it's the root used by developer.mbed.org - * If you want to trust more that one root, just concatenate them. + * currently only GlobalSign, the CA for developer.mbed.org + * + * To add more than one root, just concatenate them. */ const char SSL_CA_PEM[] = +/* GlobalSign Root R1 SHA1/RSA/2048 + * Serial no. 04 00 00 00 00 01 15 4b 5a c3 94 */ "-----BEGIN CERTIFICATE-----\n" "MIIDdTCCAl2gAwIBAgILBAAAAAABFUtaw5QwDQYJKoZIhvcNAQEFBQAwVzELMAkG\n" "A1UEBhMCQkUxGTAXBgNVBAoTEEdsb2JhbFNpZ24gbnYtc2ExEDAOBgNVBAsTB1Jv\n"