mbedtls ported to mbed-classic
Fork of mbedtls by
README.md@4:bef26f687287, 2016-04-07 (annotated)
- Committer:
- Brian Daniels
- Date:
- Thu Apr 07 11:11:18 2016 +0100
- Revision:
- 4:bef26f687287
- Parent:
- 1:24750b9ad5ef
Adding ported selftest test case
Who changed what in which revision?
User | Revision | Line number | New 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 |