Timothy Beight / Mbed 2 deprecated 6_songs-from-the-cloud

This is a fork due to permission issues

Dependencies:   mbed Socket lwip-eth lwip-sys lwip

Fork of 6_songs-from-the-cloud by MakingMusicWorkshop

mbed-client/mbedtls/README.md@0:f7c60d3e7b8a, 2016-05-18 (annotated)

Committer:
maclobdell
Date:
Wed May 18 19:06:32 2016 +0000
Revision:
0:f7c60d3e7b8a
clean version

Who changed what in which revision?

UserRevisionLine numberNew contents of line
maclobdell 0:f7c60d3e7b8a 1 # mbed TLS
maclobdell 0:f7c60d3e7b8a 2
maclobdell 0:f7c60d3e7b8a 3 mbed TLS 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.
maclobdell 0:f7c60d3e7b8a 4
maclobdell 0:f7c60d3e7b8a 5 **Note:** The current release is beta, and implements no secure source of random numbers, weakening its security.
maclobdell 0:f7c60d3e7b8a 6
maclobdell 0:f7c60d3e7b8a 7 Currently the only supported yotta targets are:
maclobdell 0:f7c60d3e7b8a 8 - `frdm-k64f-gcc`
maclobdell 0:f7c60d3e7b8a 9 - `frdm-k64f-armcc`
maclobdell 0:f7c60d3e7b8a 10 - `x86-linux-native`
maclobdell 0:f7c60d3e7b8a 11 - `x86-osx-native`
maclobdell 0:f7c60d3e7b8a 12
maclobdell 0:f7c60d3e7b8a 13 ## Sample programs
maclobdell 0:f7c60d3e7b8a 14
maclobdell 0:f7c60d3e7b8a 15 This release includes the following examples:
maclobdell 0:f7c60d3e7b8a 16
maclobdell 0:f7c60d3e7b8a 17 1. [**Self test:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-selftest) Tests different basic functions in the mbed TLS library.
maclobdell 0:f7c60d3e7b8a 18
maclobdell 0:f7c60d3e7b8a 19 2. [**Benchmark:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-benchmark) Measures the time taken to perform basic cryptographic functions used in the library.
maclobdell 0:f7c60d3e7b8a 20
maclobdell 0:f7c60d3e7b8a 21 3. [**Hashing:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-hashing) Demonstrates the various APIs for computing hashes of data (also known as message digests) with SHA-256.
maclobdell 0:f7c60d3e7b8a 22
maclobdell 0:f7c60d3e7b8a 23 4. [**Authenticated encryption:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-authcrypt) Demonstrates usage of the Cipher API for encrypting and authenticating data with AES-CCM.
maclobdell 0:f7c60d3e7b8a 24
maclobdell 0:f7c60d3e7b8a 25 These examples are integrated as yotta tests, so that they are built automatically when you build mbed TLS. Each of them comes with complete usage instructions as a Readme file in the repository.
maclobdell 0:f7c60d3e7b8a 26
maclobdell 0:f7c60d3e7b8a 27 ## Performing TLS and DTLS connections
maclobdell 0:f7c60d3e7b8a 28
maclobdell 0:f7c60d3e7b8a 29 A high-level API for performing TLS and DTLS connections with mbed TLS in mbed OS is provided in a separate yotta module: [mbed-tls-sockets](https://github.com/ARMmbed/mbed-tls-sockets). We recommend this API for TLS and DTLS connections. It is very similar to the API provided by the [sockets](https://github.com/ARMmbed/sockets) module for unencrypted TCP and UDP connections.
maclobdell 0:f7c60d3e7b8a 30
maclobdell 0:f7c60d3e7b8a 31 The `mbed-tls-sockets` module includes a complete [example TLS client](https://github.com/ARMmbed/mbed-tls-sockets/blob/master/test/tls-client/main.cpp) with [usage instructions](https://github.com/ARMmbed/mbed-tls-sockets/blob/master/test/tls-client/README.md).
maclobdell 0:f7c60d3e7b8a 32
maclobdell 0:f7c60d3e7b8a 33 ## Configuring mbed TLS features
maclobdell 0:f7c60d3e7b8a 34
maclobdell 0:f7c60d3e7b8a 35 mbed TLS makes it easy to disable any feature during compilation, if that feature 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 minimize the code footprint.
maclobdell 0:f7c60d3e7b8a 36
maclobdell 0:f7c60d3e7b8a 37 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).
maclobdell 0:f7c60d3e7b8a 38
maclobdell 0:f7c60d3e7b8a 39 If you need to adjust those flags, you can provide your own configuration-adjustment file with suitable `#define` and `#undef` statements. These will be included between the default definitions and the sanity checks. Your configuration file should be in your application's include directory, and can be named freely; you just need to let mbed TLS know the file's name. To do that, use yotta's [configuration system](http://docs.yottabuild.org/reference/config.html). The file's name should be in your `config.json` file, under mbedtls, as the key `user-config-file`.
maclobdell 0:f7c60d3e7b8a 40
maclobdell 0:f7c60d3e7b8a 41 For example, in an application called `myapp`, if you want to enable the EC J-PAKE key exchange and disable the CBC cipher mode, you can create a file named `mbedtls-config-changes.h` in the `myapp` directory containing the following lines:
maclobdell 0:f7c60d3e7b8a 42
maclobdell 0:f7c60d3e7b8a 43 #define MBEDTLS_ECJPAKE_C
maclobdell 0:f7c60d3e7b8a 44 #define MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED
maclobdell 0:f7c60d3e7b8a 45
maclobdell 0:f7c60d3e7b8a 46 #undef MBEDTLS_CIPHER_MODE_CBC
maclobdell 0:f7c60d3e7b8a 47
maclobdell 0:f7c60d3e7b8a 48 And then create a file named `config.json` at the root of your application with the following contents:
maclobdell 0:f7c60d3e7b8a 49
maclobdell 0:f7c60d3e7b8a 50 {
maclobdell 0:f7c60d3e7b8a 51 "mbedtls": {
maclobdell 0:f7c60d3e7b8a 52 "user-config-file": "\"myapp/mbedtls-config-changes.h\""
maclobdell 0:f7c60d3e7b8a 53 }
maclobdell 0:f7c60d3e7b8a 54 }
maclobdell 0:f7c60d3e7b8a 55
maclobdell 0:f7c60d3e7b8a 56 Please note: you need to provide the exact name that will be used in the `#include` directive, including the `<>` or quotes around the name.
maclobdell 0:f7c60d3e7b8a 57
maclobdell 0:f7c60d3e7b8a 58 ## Getting mbed TLS from GitHub
maclobdell 0:f7c60d3e7b8a 59
maclobdell 0:f7c60d3e7b8a 60 Like most components of mbed OS, mbed TLS is developed in the open and its source can be found on GitHub: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). Unlike most other mbed OS components, however, you cannot just clone the repository and run `yotta build` from its root. This is because mbed TLS also exists as an independent component, so its repository includes things that are not relevant for mbed OS, as well as other build systems.
maclobdell 0:f7c60d3e7b8a 61
maclobdell 0:f7c60d3e7b8a 62 The way to use mbed TLS from a clone of the GitHub repository is to run the following commands from the root of a checkout:
maclobdell 0:f7c60d3e7b8a 63
maclobdell 0:f7c60d3e7b8a 64 yotta/create-module.sh
maclobdell 0:f7c60d3e7b8a 65 cd yotta/module
maclobdell 0:f7c60d3e7b8a 66
maclobdell 0:f7c60d3e7b8a 67 You can then run any yotta command you would normally run, such as `yotta build` or `yotta link`.
maclobdell 0:f7c60d3e7b8a 68
maclobdell 0:f7c60d3e7b8a 69 ## Differences between the standalone and mbed OS editions
maclobdell 0:f7c60d3e7b8a 70
maclobdell 0:f7c60d3e7b8a 71 While the two editions share the same code base, there are still a number of differences, mainly in configuration and integration. You should keep in mind those differences when reading some articles in our [knowledge base](https://tls.mbed.org/kb), as currently all the articles are about the standalone edition.
maclobdell 0:f7c60d3e7b8a 72
maclobdell 0:f7c60d3e7b8a 73 * The mbed OS edition has a smaller set of features enabled by default in `config.h`, in order to reduce footprint. While the default configuration of the standalone edition puts more emphasize on maintaining interoperability with old peers, the mbed OS edition only enables the most modern ciphers and the latest version of (D)TLS.
maclobdell 0:f7c60d3e7b8a 74
maclobdell 0:f7c60d3e7b8a 75 * The following components of mbed TLS are disabled in the mbed OS edition: `net.c` and `timing.c`. This is because mbed OS includes their equivalents.
maclobdell 0:f7c60d3e7b8a 76
maclobdell 0:f7c60d3e7b8a 77 * The mbed OS edition comes with a fully integrated API for (D)TLS connections in a companion module: [mbed-tls-sockets](https://github.com/ARMmbed/mbed-tls-sockets). See "Performing TLS and DTLS connections" above.
maclobdell 0:f7c60d3e7b8a 78
maclobdell 0:f7c60d3e7b8a 79 ## Other resources
maclobdell 0:f7c60d3e7b8a 80
maclobdell 0:f7c60d3e7b8a 81 The [mbed TLS website](https://tls.mbed.org) contains many other useful
maclobdell 0:f7c60d3e7b8a 82 resources for the developer, such as [developer
maclobdell 0:f7c60d3e7b8a 83 documentation](https://tls.mbed.org/dev-corner), [knowledgebase
maclobdell 0:f7c60d3e7b8a 84 articles](https://tls.mbed.org/kb), and a [support forum](https://tls.mbed.org/discussions).
maclobdell 0:f7c60d3e7b8a 85
maclobdell 0:f7c60d3e7b8a 86 ## Contributing
maclobdell 0:f7c60d3e7b8a 87
maclobdell 0:f7c60d3e7b8a 88 We gratefully accept bug reports and contributions from the community. There are some requirements we need to fulfill in order to be able to integrate contributions:
maclobdell 0:f7c60d3e7b8a 89
maclobdell 0:f7c60d3e7b8a 90 * Simple bug fixes to existing code do not contain copyright themselves and we can integrate without issue. The same is true of trivial contributions.
maclobdell 0:f7c60d3e7b8a 91
maclobdell 0:f7c60d3e7b8a 92 * 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 send to you in case you submit a contribution or pull request that we deem this necessary for.
maclobdell 0:f7c60d3e7b8a 93
maclobdell 0:f7c60d3e7b8a 94 To contribute, please:
maclobdell 0:f7c60d3e7b8a 95
maclobdell 0:f7c60d3e7b8a 96 * [Check for open issues](https://github.com/ARMmbed/mbedtls/issues) or [start a discussion](https://tls.mbed.org/discussions) around a feature idea or a bug.
maclobdell 0:f7c60d3e7b8a 97
maclobdell 0:f7c60d3e7b8a 98 * Fork the [mbed TLS repository on GitHub](https://github.com/ARMmbed/mbedtls) to start making your changes. As a general rule, you should use the "development" branch as a basis.
maclobdell 0:f7c60d3e7b8a 99
maclobdell 0:f7c60d3e7b8a 100 * Write a test that shows that the bug was fixed or that the feature works as expected.
maclobdell 0:f7c60d3e7b8a 101
maclobdell 0:f7c60d3e7b8a 102 * Send a pull request and bug us until it gets merged and published. We will include your name in the ChangeLog.
maclobdell 0:f7c60d3e7b8a 103