Austin Blackstone / Mbed 2 deprecated mbed-client-classic-example-lwip

mbed client on ethernet with LWIP

Dependencies:   mbed Socket lwip-eth lwip-sys lwip

Fork of mbed-client-classic-example-lwip by sandbox

mbedtls/README.md@11:cada08fc8a70, 2016-06-09 (annotated)

Committer:
mbedAustin
Date:
Thu Jun 09 17:08:36 2016 +0000
Revision:
11:cada08fc8a70
Commit for public Consumption

Who changed what in which revision?

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