Skip to content

Appendix_D_Mbed_TLS.md

Latest commit

 

History

History
88 lines (66 loc) · 3.39 KB

Appendix_D_Mbed_TLS.md

File metadata and controls

88 lines (66 loc) · 3.39 KB

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 Mbed TLS crypto implementation 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 crypto implementation that comes with Mbed TLS, using Oberon PSA Crypto instead.

Migrate an Application to Oberon PSA Crypto

If an application that uses the crypto part of the Mbed TLS software stack via the PSA Certified Crypto API, but does not use its TLS protocol part, should be migrated to Oberon 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. See Appendix A: Supported Crypto Features for more information.

  3. Copy your existing mbedtls/mbedtls_config.h configuration file to the corresponding location in Oberon PSA Crypto. Oberon PSA Crypto provides the Mbed TLS implementations for MBEDTLS_PSA_CRYPTO_STORAGE_C and MBEDTLS_PSA_ITS_FILE_C by default, but can use other provided implementations of these PSA Storage APIs.

  4. Copy your existing psa/crypto_config.h file to include/psa/ in Oberon PSA Crypto.

  5. Make sure that the include/psa/crypto_config.h file defines the "wanted" crypto features as described above.

  6. In the include/psa/crypto_config.h file, add the use directives for a DRGB driver and 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.

  7. Copy the header files include/psa/crypto_driver_contexts_composites.h, include/psa/crypto_driver_contexts_key_derivation.h, include/psa/crypto_driver_contexts_primitives.h, include/psa/crypto_driver_config.h and the driver wrapper implementation library/psa_crypto_driver_wrappers.c from the folder oberon/platforms. Demo files for the configuration of Oberon PSA Crypto drivers are located in subfolders demo/include/psa and demo/library.

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 that may have to be configured as well. See README-SSL for more information.

Relevant Defines

The following defines in mbedtls_config.h are relevant for Oberon PSA Crypto:

  • MBEDTLS_THREADING_C
  • MBEDTLS_PSA_CRYPTO_C
  • MBEDTLS_PSA_CRYPTO_CLIENT
  • MBEDTLS_PSA_CRYPTO_STORAGE_C
  • MBEDTLS_PSA_ITS_FILE_C
  • MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
  • MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS

Only relevant for testing:

  • MBEDTLS_STATIC_TESTABLE
  • MBEDTLS_TEST_HOOKS
  • MBEDTLS_TEST_HOOK_TEST_ASSERT
  • MBEDTLS_TEST_PSA_SKIP_IF_SMALL_RSA_KEY (introduced by Oberon microsystems)

Should always be defined:

  • MBEDTLS_USE_PSA_CRYPTO
  • MBEDTLS_PSA_CRYPTO_CONFIG

Should never be defined:

  • MBEDTLS_PSA_CRYPTO_SE_C
  • MBEDTLS_PSA_INJECT_ENTROPY
  • MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS
  • MBEDTLS_PSA_CRYPTO_SPM