From 0abac0079dcd2970334be82e4bd7924d4013bae9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20B=C3=B8e?= Date: Mon, 28 Aug 2023 13:29:34 +0200 Subject: [PATCH] nrf_security: Document how to provide a custom mbedtls header config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document how to provide a custom mbedtls config header. Signed-off-by: Sebastian Bøe --- .../nrf_security/doc/mbed_tls_header.rst | 31 ++++++++++++------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/doc/nrf/libraries/nrf_security/doc/mbed_tls_header.rst b/doc/nrf/libraries/nrf_security/doc/mbed_tls_header.rst index 9950f9c51df..afd7250c096 100644 --- a/doc/nrf/libraries/nrf_security/doc/mbed_tls_header.rst +++ b/doc/nrf/libraries/nrf_security/doc/mbed_tls_header.rst @@ -1,21 +1,25 @@ .. _nrf_security_tls_header: -User-provided Mbed TLS config header -#################################### +User-provided Mbed TLS configuration header +########################################### -The nRF Security subsystem provides a Kconfig interface to control compilation and linking of Mbed TLS and the :ref:`nrf_cc3xx_mbedcrypto_readme` or :ref:`nrf_oberon_readme` libraries. +The nRF Security subsystem provides a Kconfig- and CMake-based build system to configure the Mbed TLS, :ref:`nrf_cc3xx_mbedcrypto_readme`, and :ref:`nrf_oberon_readme` libraries. +The recommended method for generating the Mbed TLS header is through this build system, as it also enforces dependencies between the libraries. +However, for use cases that cannot be configured through the build system, you must provide custom Mbed TLS configuration headers. -The Kconfig interface and build system ensures that the configuration of nrf_security is valid and working. -It also ensures that dependencies between different cryptographic APIs are met. +Complete the following steps: -It is therefore highly recommended to let the build system generate the Mbed TLS configuration headers. +1. Generate the Mbed TLS configuration header. +#. Create a copy of the :file:`nrf-config.h` Mbed TLS header file in the build directory and give it a custom name. +#. Move this custom Mbed TLS header file to your source directory. +#. In the project configuration, make the following changes: -However, for special use cases that cannot be achieved using the Kconfig configuration tool, it is possible to provide custom Mbed TLS configuration headers. - -Make sure that the system is working: - -1. Use Kconfig and the build system to create Mbed TLS configuration headers as a starting point. -#. Edit this file to include settings that are not available in Kconfig. + * `CONFIG_GENERATE_MBEDTLS_CFG_FILE=n`. + * `CONFIG_MBEDTLS_CFG_FILE="custom-name-nrf-config.h"`. + * `CONFIG_MBEDTLS_USER_CONFIG_FILE="empty_file.h"`. +#. Create an empty file named :file:`empty_file.h`. +#. Edit :file:`custom-name-nrf-config.h` with your custom configuration. +#. If the header files are not already in the include path, add them by editing the application build scripts. .. note:: When providing custom Mbed TLS configuration headers with CryptoCell in use, it is important that the following criteria are still met: @@ -23,3 +27,6 @@ Make sure that the system is working: * Entropy length of 144, that is, ``#define MBEDTLS_ENTROPY_MAX_GATHER 144``. * SHA-256 is used for entropy, that is, ``#define MBEDTLS_ENTROPY_FORCE_SHA256`` is set. * Entropy max sources is set to ``1``, that is ``#define MBEDTLS_ENTROPY_MAX_SOURCES 1``. + +.. note:: + Providing custom Mbed TLS configuration headers is not supported when TF-M is enabled.