doc: Bluetooth: Mesh: documentation for security toolbox and key importer

Commit adds:
* Mesh security toolbox documentation
* Key importer usage documentation

Signed-off-by: Aleksandr Khromykh <aleksandr.khromykh@nordicsemi.no>

Author: alxelax

doc/nrf/protocols/bt/bt_mesh/configuring.rst

@@ -246,3 +246,44 @@ Using the :ref:`bluetooth_mesh_sensor_server` sample as an example, configured a
   * Ambient light level gain
 
 Adding up all entries, it is worth setting the cache size to minimum 71.
+
+Security toolbox
+----------------
+
+Zephyr's Mesh security toolbox implementation does not include encryption and authentication functionality, such as CMAC, AES-CCM, and HMAC-SHA-256.
+The third-party crypto solutions are used instead.
+
+* The following options are available:
+
+  * :kconfig:option:`CONFIG_BT_MESH_USES_MBEDTLS_PSA` - Enables use of the Mbed TLS PSA API based security toolbox (default option).
+  * :kconfig:option:`CONFIG_BT_MESH_USES_TFM_PSA` - Enables use of the TF-M PSA API based security toolbox (default option for platforms that support TF-M).
+  * :kconfig:option:`CONFIG_BT_MESH_USES_TINYCRYPT` - Enables use of Tinycrypt-based security toolbox.
+    Zephyr's Mesh operates with open value of keys, including storing them in the persistent memory.
+    The Tinycrypt-based solution has worse security materials protection compared to others and not recommended for future designs.
+
+The Bluetooth Mesh security toolbox based on the PSA API does not operate with open key values.
+After Bluetooth Mesh gets open key value, it immediately imports the keys into the crypto library and receives the unique key identifier.
+The key identifiers are used in the security toolbox and stored in the persistent memory.
+The crypto library is responsible for storing of the open key values in the Internal Trusted Storage (ITS).
+Bluetooth Mesh data structures based on Tinycrypt and based on the PSA API as well as images of these structures stored in the persistent memory are not compatible due to different key representations.
+When a provisioned device updates its image using the Tinycrypt-based toolbox on image with the PSA API based toolbox, it needs to be unprovisioned first and reprovisioned after the update.
+If the image is changed over Mesh DFU, it is recommended to use :c:enumerator:`BT_MESH_DFU_EFFECT_UNPROV`.
+
+However, a provisioned device can update its image using the Tinycrypt-based toolbox on image with the PSA API based toolbox without being unprovisioned.
+The :kconfig:option:`CONFIG_BT_MESH_KEY_IMPORTER` Kconfig option enables the key importer functionality.
+The key importer is an application initialization functionality that is called with kernel initialization priority before starting main.
+This functionality reads out the persistently stored Bluetooth Mesh data and if it finds keys stored by the Tinycrypt-based security toolbox, it imports them over the PSA API into the crypto library and stores the key identifiers in PSA API toolbox based format.
+When the application starts Bluetooth Mesh initialization, the persistent area already has the stored data in the correct format.
+
+Using the key importer might make the device vulnerable for attacks.
+If the device works with the key importer functionality enabled and the attacker writes arbitrary data in the persistent memory, fake keys might be stored and imported to PSA crypto library after the next device reset.
+
+Complete the following steps to use the key importer functionality safely:
+
+1. Update the images with the Tinycrypt-based toolbox and the PSA API based toolbox with the key importer feature enabled.
+#. Reset the device to perform the key import after the devices in the network have successfully updated their images.
+#. Update the images with the PSA API based security toolbox with the key importer feature disabled.
+
+Even if you have completed these steps, the Tinycrypt-based open key values can be extracted from the settings subsystem backend if there is access to it.
+The keys might still be compromised.
+Start the key refresh procedure according to the specification for all existing keys.

doc/nrf/releases_and_maturity/migration/migration_guide_3.0.rst

@@ -219,3 +219,19 @@ Download client
         .. code-block:: C
 
            err = downloader_deinit(&dl);
+
+Protocols
+=========
+
+This section provides detailed lists of changes by :ref:`protocol <protocols>`.
+
+Bluetooth Mesh
+--------------
+
+.. toggle::
+
+   * Support of Tinycrypt-based security toolbox (:kconfig:option:`CONFIG_BT_MESH_USES_TINYCRYPT`) started the deprecation procedure and is not recommended for future designs.
+   * The default security toolbox is based on the Mbed TLS PSA API (:kconfig:option:`CONFIG_BT_MESH_USES_MBEDTLS_PSA`).
+   * The default security toolbox is based on the TF-M PSA API (:kconfig:option:`CONFIG_BT_MESH_USES_TFM_PSA`) for platforms that support TF-M.
+
+The :ref:`ug_bt_mesh_configuring` page provides more information about the updating of the images based on different security toolboxes.

doc/nrf/releases_and_maturity/releases/release-notes-3.0.0-preview1.rst

@@ -133,7 +133,9 @@ Bluetooth® LE
 Bluetooth Mesh
 --------------
 
-|no_changes_yet_note|
+* Added:
+
+  * The key importer functionality (:kconfig:option:`CONFIG_BT_MESH_KEY_IMPORTER`).
 
 DECT NR+
 --------
@@ -899,6 +901,7 @@ Documentation
   * The :ref:`create_application` page with the :ref:`creating_add_on_index` section.
   * The :ref:`ug_nrf91` documentation to use `nRF Util`_ instead of nrfjprog.
   * The :ref:`dm-revisions` section of the :ref:`dm_code_base` page with information about the preview release tag, which replaces the development tag.
+  * The :ref:`ug_bt_mesh_configuring` page with the security toolbox subclause and the key importer functionality.
 
 * Removed the standalone page for getting started with Nordic Thingy:53.
   The contents of this page have been moved to the :ref:`thingy53_precompiled` page and to the `Programmer app <Programming Nordic Thingy:53_>`_ documentation.