Skip to content

Appendix_D_Mbed_TLS.md

Latest commit

 

History

History
111 lines (84 loc) · 4.34 KB

Appendix_D_Mbed_TLS.md

File metadata and controls

111 lines (84 loc) · 4.34 KB
Raw

Appendix D: Mbed TLS

Below, two scenarios are discussed relating to Mbed TLS:

  1. Migrate an application that uses Mbed TLS cryptography functions through the PSA Certified Crypto API from the TF-PSA-Crypto implementation (successor project that split off the crypto implementation from Mbed TLS) to Oberon PSA Crypto.

  2. Migrating an application that uses Mbed TLS as a TLS stack, so that it continues using the protocol implementation of Mbed TLS, but without the default crypto implementation TF-PSA-Crypto, using Oberon PSA Crypto instead.

Migrate an Application to Oberon PSA Crypto

To migrate an application that

a) uses the crypto part of the Mbed TLS 3.x software stack via the PSA Certified Crypto API, but does not use its TLS protocol part, or b) uses TF-PSA-Crypto:

  1. Make sure that your application only uses the PSA Certified Crypto API for all crypto calls.

  2. Make sure that your application only uses the modern crypto algorithms that Oberon PSA Crypto supports, e.g., not MD5 etc. See Appendix A: Supported Crypto Features for more information.

  3. Select a target configuration example from the targets/acme folder, e.g., demo.

  4. Create an include/psa/crypto_config.h file based on the crypto_config.h example in the target configuration's dispatch/psa folder, adapt it based on your existing crypto_config.h and if you are migrating from Mbed TLS 3.x, also on your mbedtls_config.h. In TF-PSA-Crypto and Oberon PSA Crypto since 2.0, configuration aspects from both files are combined into crypto_config.h.

  5. Make sure that your new crypto_config.h file defines the "wanted" crypto features as described above and add the use directives for a DRGB driver and provide an entropy driver. Oberon PSA Crypto provides the DRBG directives PSA_USE_CTR_DRBG_DRIVER and PSA_USE_HMAC_DRBG_DRIVER for production, and the entropy driver directive PSA_USE_DEMO_ENTROPY_DRIVER for testing.

  6. Make sure to remove the demo hardware, the demo opaque, and the demo entropy drivers for production use.

  7. Copy the driver configuration files, i.e., psa/crypto_driver_contexts_composites.h, psa/crypto_driver_contexts_key_derivation.h, psa/crypto_driver_contexts_primitives.h, psa/crypto_driver_config.h from the target configuration's dispatch folder to your include folder of Oberon PSA Crypto or make sure they can be found in the include path of your build.

  8. Copy the psa_crypto_driver_wrappers.c from the target configuration's dispatch folder to your dispatch folder and add the code file to your build.

  9. Optionally, add your own hardware drivers and adapt the driver configuration files and the dispatch logic implementation accordingly.

  10. Oberon PSA Crypto provides the TF-PSA-Crypto mock implementations for MBEDTLS_PSA_CRYPTO_STORAGE_C and MBEDTLS_PSA_ITS_FILE_C by default. They are handy for testing, and should be replaced by hardened implementations of the PSA Storage APIs for production use.

Use the Mbed TLS Protocol Stack Without its Crypto Implementation

If the TLS protocol part of the Mbed TLS software stack is used with Oberon PSA Crypto, there are settings in include/mbedtls/mbedtls_config.h of the MbedTLS project that may have to be configured as well. See README-SSL for more information.

Relevant Defines

The configuration in psa/crypto_config.h contains genuine PSA Crypto configuration options with a PSA_ prefix and inherited options from former MBed TLS with an MBEDTLS_ prefix, that can be configured.

Relevant for Oberon PSA Crypto:

  • MBEDTLS_THREADING_C
  • MBEDTLS_PSA_CRYPTO_C
  • MBEDTLS_PSA_CRYPTO_CLIENT
  • MBEDTLS_PSA_CRYPTO_STORAGE_C
  • MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
  • MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS
  • MBEDTLS_PSA_ITS_FILE_C
  • MBEDTLS_PSA_KEY_STORE_DYNAMIC
  • MBEDTLS_PSA_KEY_SLOT_COUNT
  • MBEDTLS_PSA_STATIC_KEY_SLOTS
  • MBEDTLS_PSA_STATIC_KEY_SLOT_BUFFER_SIZE

Should always be defined:

  • MBEDTLS_USE_PSA_CRYPTO
  • MBEDTLS_PSA_CRYPTO_CONFIG

Should never be defined:

  • MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS
  • MBEDTLS_PSA_CRYPTO_SPM

This file by Oberon microsystems is licensed under the Creative Commons Attribution-ShareAlike 4.0 License.