nrf_security: Document how to provide a custom mbedtls header config

Document how to provide a custom mbedtls config header.

Signed-off-by: Sebastian Bøe <[email protected]>

doc/nrf/libraries/nrf_security/doc/mbed_tls_header.rst

@@ -1,25 +1,32 @@
 .. _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:
 
    * 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.