Eric Tsai / mbedtls

Modified mbed TLS headers for AES functionality only to reduce build size

Dependents:   BLE_Gateway_Linker_fix BLE_Gateway

Fork of mbedtls by sandbox

README.md@5:f09f5ed830ca, 2017-07-10 (annotated)

Committer:
electronichamsters
Date:
Mon Jul 10 04:00:25 2017 +0000
Revision:
5:f09f5ed830ca
Parent:
1:24750b9ad5ef 
working gateway

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 1:24750b9ad5ef 1 # mbed TLS
Christopher Haster 1:24750b9ad5ef 2
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 4
Christopher Haster 1:24750b9ad5ef 5 **Note:** The current release is beta, and implements no secure source of random numbers, weakening its security.
Christopher Haster 1:24750b9ad5ef 6
Christopher Haster 1:24750b9ad5ef 7 Currently the only supported yotta targets are:
Christopher Haster 1:24750b9ad5ef 8 - `frdm-k64f-gcc`
Christopher Haster 1:24750b9ad5ef 9 - `frdm-k64f-armcc`
Christopher Haster 1:24750b9ad5ef 10 - `x86-linux-native`
Christopher Haster 1:24750b9ad5ef 11 - `x86-osx-native`
Christopher Haster 1:24750b9ad5ef 12
Christopher Haster 1:24750b9ad5ef 13 ## Sample programs
Christopher Haster 1:24750b9ad5ef 14
Christopher Haster 1:24750b9ad5ef 15 This release includes the following examples:
Christopher Haster 1:24750b9ad5ef 16
Christopher Haster 1:24750b9ad5ef 17 1. [**Self test:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-selftest) Tests different basic functions in the mbed TLS library.
Christopher Haster 1:24750b9ad5ef 18
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 20
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 22
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 24
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 26
Christopher Haster 1:24750b9ad5ef 27 ## Performing TLS and DTLS connections
Christopher Haster 1:24750b9ad5ef 28
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 30
Christopher Haster 1:24750b9ad5ef 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).
Christopher Haster 1:24750b9ad5ef 32
Christopher Haster 1:24750b9ad5ef 33 ## Configuring mbed TLS features
Christopher Haster 1:24750b9ad5ef 34
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 36
Christopher Haster 1:24750b9ad5ef 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).
Christopher Haster 1:24750b9ad5ef 38
Christopher Haster 1:24750b9ad5ef 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`.
Christopher Haster 1:24750b9ad5ef 40
Christopher Haster 1:24750b9ad5ef 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:
Christopher Haster 1:24750b9ad5ef 42
Christopher Haster 1:24750b9ad5ef 43 #define MBEDTLS_ECJPAKE_C
Christopher Haster 1:24750b9ad5ef 44 #define MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED
Christopher Haster 1:24750b9ad5ef 45
Christopher Haster 1:24750b9ad5ef 46 #undef MBEDTLS_CIPHER_MODE_CBC
Christopher Haster 1:24750b9ad5ef 47
Christopher Haster 1:24750b9ad5ef 48 And then create a file named `config.json` at the root of your application with the following contents:
Christopher Haster 1:24750b9ad5ef 49
Christopher Haster 1:24750b9ad5ef 50 {
Christopher Haster 1:24750b9ad5ef 51 "mbedtls": {
Christopher Haster 1:24750b9ad5ef 52 "user-config-file": "\"myapp/mbedtls-config-changes.h\""
Christopher Haster 1:24750b9ad5ef 53 }
Christopher Haster 1:24750b9ad5ef 54 }
Christopher Haster 1:24750b9ad5ef 55
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 57
Christopher Haster 1:24750b9ad5ef 58 ## Getting mbed TLS from GitHub
Christopher Haster 1:24750b9ad5ef 59
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 61
Christopher Haster 1:24750b9ad5ef 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:
Christopher Haster 1:24750b9ad5ef 63
Christopher Haster 1:24750b9ad5ef 64 yotta/create-module.sh
Christopher Haster 1:24750b9ad5ef 65 cd yotta/module
Christopher Haster 1:24750b9ad5ef 66
Christopher Haster 1:24750b9ad5ef 67 You can then run any yotta command you would normally run, such as `yotta build` or `yotta link`.
Christopher Haster 1:24750b9ad5ef 68
Christopher Haster 1:24750b9ad5ef 69 ## Differences between the standalone and mbed OS editions
Christopher Haster 1:24750b9ad5ef 70
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 72
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 74
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 76
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 78
Christopher Haster 1:24750b9ad5ef 79 ## Other resources
Christopher Haster 1:24750b9ad5ef 80
Christopher Haster 1:24750b9ad5ef 81 The [mbed TLS website](https://tls.mbed.org) contains many other useful
Christopher Haster 1:24750b9ad5ef 82 resources for the developer, such as [developer
Christopher Haster 1:24750b9ad5ef 83 documentation](https://tls.mbed.org/dev-corner), [knowledgebase
Christopher Haster 1:24750b9ad5ef 84 articles](https://tls.mbed.org/kb), and a [support forum](https://tls.mbed.org/discussions).
Christopher Haster 1:24750b9ad5ef 85
Christopher Haster 1:24750b9ad5ef 86 ## Contributing
Christopher Haster 1:24750b9ad5ef 87
Christopher Haster 1:24750b9ad5ef 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:
Christopher Haster 1:24750b9ad5ef 89
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 91
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 93
Christopher Haster 1:24750b9ad5ef 94 To contribute, please:
Christopher Haster 1:24750b9ad5ef 95
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 97
Christopher Haster 1:24750b9ad5ef 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.
Christopher Haster 1:24750b9ad5ef 99
Christopher Haster 1:24750b9ad5ef 100 * Write a test that shows that the bug was fixed or that the feature works as expected.
Christopher Haster 1:24750b9ad5ef 101
Christopher Haster 1:24750b9ad5ef 102 * Send a pull request and bug us until it gets merged and published. We will include your name in the ChangeLog.
Christopher Haster 1:24750b9ad5ef 103