Document Mbed Crypto and the PSA API
Briefly explain that this is experimental, and document how to try it out.
@@ -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
----------------
