Kev Mann / mbed-dev-OS5_10_4

RTC auf true

features/mbedtls/README.md@0:38ceb79fef03, 2018-11-28 (annotated)

Committer:
kevman
Date:
Wed Nov 28 15:10:15 2018 +0000
Revision:
0:38ceb79fef03
RTC modified

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kevman 0:38ceb79fef03 1 ## README for Mbed TLS
kevman 0:38ceb79fef03 2
kevman 0:38ceb79fef03 3 ### Mbed TLS for Mbed OS
kevman 0:38ceb79fef03 4
kevman 0:38ceb79fef03 5 This edition of Mbed TLS has been adapted for Mbed OS and imported from its standalone release, which you can find on [GitHub](https://github.com/ARMmbed/mbedtls). This edition of Mbed TLS does not include the test code or scripts used in the development of the library. You can find these in the standalone release.
kevman 0:38ceb79fef03 6
kevman 0:38ceb79fef03 7 ### Getting started
kevman 0:38ceb79fef03 8
kevman 0:38ceb79fef03 9 Several example programs are available that demonstrate Mbed TLS with Mbed OS. These can help you become familiar with the library:
kevman 0:38ceb79fef03 10
kevman 0:38ceb79fef03 11 * [**TLS Client:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/tls-client) TLS Client demonstrates the use of Mbed TLS to establish a TLS connection to a remote server.
kevman 0:38ceb79fef03 12
kevman 0:38ceb79fef03 13 * [**Benchmark:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/benchmark) Benchmark measures the time taken to perform basic cryptographic functions used in the library.
kevman 0:38ceb79fef03 14
kevman 0:38ceb79fef03 15 * [**Hashing:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/hashing) Hashing demonstrates the various APIs for computing hashes of data (also known as message digests) with SHA-256.
kevman 0:38ceb79fef03 16
kevman 0:38ceb79fef03 17 * [**Authenticated encryption:**](https://github.com/ARMmbed/mbed-os-example-tls/tree/master/authcrypt) Authcrypt demonstrates usage of the cipher API for encrypting and authenticating data with AES-CCM.
kevman 0:38ceb79fef03 18
kevman 0:38ceb79fef03 19 These examples are fully integrated into Mbed OS. Each of them comes with complete usage instructions as a `README.md` file.
kevman 0:38ceb79fef03 20
kevman 0:38ceb79fef03 21 ### Configuring Mbed TLS features
kevman 0:38ceb79fef03 22
kevman 0:38ceb79fef03 23 With Mbed TLS, you can disable any unneeded features during compilation for a particular project. The default configuration enables widely used features of the TLS protocol, which meets the needs of most projects. It also disables all older and less common features to minimize the code footprint.
kevman 0:38ceb79fef03 24
kevman 0:38ceb79fef03 25 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).
kevman 0:38ceb79fef03 26
kevman 0:38ceb79fef03 27 If you need to adjust these flags, you can provide your own supplementary configuration adjustment file with suitable `#define` and `#undef` statements. These are 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, but you then need to tell Mbed TLS the file's name. To do that, you can use the [Mbed OS configuration system](https://os.mbed.com/docs/latest/reference/configuration.html).
kevman 0:38ceb79fef03 28
kevman 0:38ceb79fef03 29 For example, if you wanted to enable the options `MBEDTLS_PEM_WRITE_C` and `MBEDTLS_CMAC_C` and provide your own additional configuration file for Mbed TLS named `my_config.h`, you could define these in a top level `mbed_app.json` configuration file in the root directory of your project.
kevman 0:38ceb79fef03 30
kevman 0:38ceb79fef03 31 The Mbed TLS configuration file would be specified in the `.json` file as:
kevman 0:38ceb79fef03 32
kevman 0:38ceb79fef03 33 ```
kevman 0:38ceb79fef03 34 {
kevman 0:38ceb79fef03 35 "macros" : [
kevman 0:38ceb79fef03 36
kevman 0:38ceb79fef03 37 "MBEDTLS_USER_CONFIG_FILE" : "my_config.h",
kevman 0:38ceb79fef03 38
kevman 0:38ceb79fef03 39 "MBEDTLS_PEM_WRITE_C",
kevman 0:38ceb79fef03 40 "MBEDTLS_CMAC_C"
kevman 0:38ceb79fef03 41 ]
kevman 0:38ceb79fef03 42 [remainder of file]
kevman 0:38ceb79fef03 43 }
kevman 0:38ceb79fef03 44 ```
kevman 0:38ceb79fef03 45
kevman 0:38ceb79fef03 46 You can then use the additional configuration file `my_config.h` as a normal configuration header file to include or exclude configurations. For example, it could include the following lines to include ECJPAKE, and to disable the CBC block mode:
kevman 0:38ceb79fef03 47
kevman 0:38ceb79fef03 48 ```
kevman 0:38ceb79fef03 49 #define MBEDTLS_ECJPAKE_C
kevman 0:38ceb79fef03 50 #define MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED
kevman 0:38ceb79fef03 51
kevman 0:38ceb79fef03 52 #undef MBEDTLS_CIPHER_MODE_CBC
kevman 0:38ceb79fef03 53 ```
kevman 0:38ceb79fef03 54
kevman 0:38ceb79fef03 55 You can use this to change any configuration normally in the `config.h` file.
kevman 0:38ceb79fef03 56
kevman 0:38ceb79fef03 57 ### Getting Mbed TLS from GitHub
kevman 0:38ceb79fef03 58
kevman 0:38ceb79fef03 59 We maintain and develop Mbed TLS in the open, independently of Mbed OS, and you can find its source on GitHub here: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). To import a different version of Mbed TLS into an instance of Mbed OS, there is a `Makefile` script to update the local Git repository, extract a specific version and modify the configuration files to Mbed OS defaults.
kevman 0:38ceb79fef03 60
kevman 0:38ceb79fef03 61 To use the `Makefile`, you can either set `MBED_TLS_RELEASE` environment variable to the Git tag or commit ID of the Mbed TLS release or version you want to use, or modify the `Makefile` itself. If `MBED_TLS_RELEASE` is not set, the HEAD of the main development branch will be extracted.
kevman 0:38ceb79fef03 62
kevman 0:38ceb79fef03 63 Run the following commands in the `importer` directory in the Mbed TLS directory:
kevman 0:38ceb79fef03 64
kevman 0:38ceb79fef03 65 ```
kevman 0:38ceb79fef03 66 make update
kevman 0:38ceb79fef03 67 make
kevman 0:38ceb79fef03 68 ```
kevman 0:38ceb79fef03 69
kevman 0:38ceb79fef03 70 The `make update` command pulls the specified version of Mbed TLS into the local `importer/TARGET_IGNORE` directory, and `make` transforms it into the `src` directory, modifying its configuration file as necessary.
kevman 0:38ceb79fef03 71
kevman 0:38ceb79fef03 72 Once these steps are complete, you can build Mbed OS normally with the new version of Mbed TLS.
kevman 0:38ceb79fef03 73
kevman 0:38ceb79fef03 74 ### Differences between the standalone and Mbed OS editions
kevman 0:38ceb79fef03 75
kevman 0:38ceb79fef03 76 Although the two editions share the same code base, there are differences, mainly in configuration and integration. Remember these differences if you consult our [knowledge base](https://tls.mbed.org/kb), as the knowledge base articles refer to the standalone edition.
kevman 0:38ceb79fef03 77
kevman 0:38ceb79fef03 78 * The Mbed OS edition has a smaller set of features enabled by default in `config.h`, to reduce footprint. Although the default configuration of the standalone edition puts more emphasis on maintaining interoperability with old peers, the Mbed OS edition only enables the most modern ciphers and the latest version of (D)TLS.
kevman 0:38ceb79fef03 79
kevman 0:38ceb79fef03 80 * The following components of Mbed TLS are disabled in the Mbed OS edition: `net_sockets.c` and `timing.c`. This is because Mbed OS includes its own equivalents.
kevman 0:38ceb79fef03 81
kevman 0:38ceb79fef03 82 ### Help and support
kevman 0:38ceb79fef03 83
kevman 0:38ceb79fef03 84 For further documentation and help, you can visit the [Mbed TLS website](https://tls.mbed.org/), which contains full documentation of the library, including function-by-function descriptions, knowledge base articles and blogs. Additionally, you can join our [support forum](https://forums.mbed.com/c/mbed-tls) for questions to the community or to help others.
kevman 0:38ceb79fef03 85
kevman 0:38ceb79fef03 86 ### Contributing to the project
kevman 0:38ceb79fef03 87
kevman 0:38ceb79fef03 88 We are happy to accept bug reports and contributions from the community. There are some requirements to integrate contributions:
kevman 0:38ceb79fef03 89
kevman 0:38ceb79fef03 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.
kevman 0:38ceb79fef03 91 * 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 if you submit a contribution or pull request that we deem this necessary for.
kevman 0:38ceb79fef03 92
kevman 0:38ceb79fef03 93 Please submit contributions to the [standalone Mbed TLS project](https://github.com/ARMmbed/mbedtls), not to the version of Mbed TLS embedded within Mbed OS.