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 uses third-party crypto libraries APIs (such as CMAC, AES-CCM, and HMAC-SHA-256) for implementing encryption and authentication functionality.
+
+* 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 `Trusted Firmware 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 key values, including storing them in the persistent memory.
+    The Tinycrypt-based solution has worse security materials protection compared to others due to keeping keys in memory in open form. Therefore, usage of Tinycrypt is not recommended for future designs.
+
+The Bluetooth Mesh security toolbox based on the `PSA Certified Crypto API`_ does not operate with open key values.
+After Bluetooth Mesh receives an open key value, it immediately imports the key 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 (`PSA Certified Secure Storage API 1.0`_).
+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 firmware binary from the Tinycrypt-based toolbox to firmware binary that uses the PSA API based toolbox, a provisioned device must be unprovisioned first and reprovisioned after the update.
+If not then a device cannot restore data from the persistent memory after firmware 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 firmware image from the Tinycrypt-based toolbox to firmware image that uses the PSA API based toolbox without requiring to be unprovisioned by using key importer functionality.
+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 a format based on the PSA API toolbox.
+Once the new firmware image starts Bluetooth Mesh initialization, the persistent area already has the stored data in the correct format due to use of key importer functionality.
+
+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.
+#. Reboot 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.
+   * For platforms that do not support the TF-M: The default security toolbox is based on the Mbed TLS PSA API (:kconfig:option:`CONFIG_BT_MESH_USES_MBEDTLS_PSA`).
+   * For platforms that support the TF-M: The default security toolbox is based on the TF-M PSA API (:kconfig:option:`CONFIG_BT_MESH_USES_TFM_PSA`).
+
+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-changelog.rst

@@ -141,7 +141,9 @@ Bluetooth® LE
 Bluetooth Mesh
 --------------
 
-|no_changes_yet_note|
+* Added:
+
+  * The key importer functionality (:kconfig:option:`CONFIG_BT_MESH_KEY_IMPORTER`).
 
 DECT NR+
 --------
@@ -1013,6 +1015,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 section and the key importer functionality.
 
 * Removed: