From bc554f66ef3e932c8eb9ea694e0dd896c0fafd61 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 21 Nov 2018 12:34:47 +0100 Subject: [PATCH] Document Mbed Crypto and the PSA API Briefly explain that this is experimental, and document how to try it out. --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index d7a0e9d6b..58e5273e2 100644 --- a/README.md +++ b/README.md @@ -158,6 +158,43 @@ Configurations We provide some non-standard configurations focused on specific use cases in the `configs/` directory. You can read more about those in `configs/README.txt` +Using Mbed Crypto as a submodule +-------------------------------- + +As an experimental feature, you can use Mbed Crypto as the source of the cryptography implementation, with Mbed TLS providing the X.509 and TLS parts of the library. Mbed Crypto is currently provided for evaluation only and should not be used in production. At this point, you should only use this option if you want to try out the experimental PSA Crypto API. + +To enable the use of Mbed Crypto as a submodule: + +1. Check out the `crypto` submodule and update it. + + git submodule init crypto + git submodule update crypto + +2. (Optional) TO enable the PSA Crypto API, set the build configuration option `MBEDTLS_PSA_CRYPTO_C`. You can either edit `include/mbedtls/config.h` directly or use the configuration script: + + scripts/config.pl set MBEDTLS_PSA_CRYPTO_C + +3. Activate the build option `USE_CRYPTO_SUBMODULE`. With GNU make, set `USE_CRYPTO_SUBMODULE=1` on each make invocation: + + make USE_CRYPTO_SUBMODULE=1 + make USE_CRYPTO_SUBMODULE=1 test + tests/ssl-opt.sh -f Default + + Note that you need to pass `USE_CRYPTO_SUBMODULE=1` even to `make clean`. For example, if you change `config.h`, run this before rebuilding: + + make USE_CRYPTO_SUBMODULE=1 clean + + With CMake, create a build directory (recommended) and pass `-DUSE_CRYPTO_SUBMODULE=1` to `cmake`: + + mkdir build + cd build + cmake -DUSE_CRYPTO_SUBMODULE=1 .. + make + make test + tests/ssl-opt.sh -f Default + +Note that this does not enable the PSA-specific tests and utility programs. To use these programs, use Mbed Crypto as a standalone project. + Porting Mbed TLS ----------------