b0: bl_crypto: Add RST docs for bl_crypto

Also fix doxygen text and tagging inside bl_crypto.h

Signed-off-by: Øyvind Rønningstad <[email protected]>

Author: oyvindronningstad

include/bl_crypto.h

@@ -7,9 +7,18 @@
 #ifndef BOOTLOADER_CRYPTO_H__
 #define BOOTLOADER_CRYPTO_H__
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 #include <zephyr/types.h>
 #include <fw_info.h>
 
+
+/** @defgroup bl_crypto Bootloader crypto functions
+ * @{
+ */
+
 /* Placeholder defines. Values should be updated, if no existing errors can be
  * used instead. */
 #define EHASHINV 101
@@ -196,13 +205,19 @@ typedef int (*bl_secp256r1_validate_t)(
 			  const u8_t *public_key);
 
 
+/**
+ * @brief Structure describing the BL_ROT_VERIFY EXT_API.
+ */
 struct bl_rot_verify_ext_api {
 	struct fw_info_ext_api header;
 	struct {
 		bl_root_of_trust_verify_t bl_root_of_trust_verify;
 	} ext_api;
 };
 
+/**
+ * @brief Structure describing the BL_SHA256 EXT_API.
+ */
 struct bl_sha256_ext_api {
 	struct fw_info_ext_api header;
 	struct {
@@ -214,13 +229,20 @@ struct bl_sha256_ext_api {
 	} ext_api;
 };
 
+/**
+ * @brief Structure describing the BL_SECP256R1 EXT_API.
+ */
 struct bl_secp256r1_ext_api {
 	struct fw_info_ext_api header;
 	struct {
 		bl_secp256r1_validate_t bl_secp256r1_validate;
 	} ext_api;
 };
 
+  /** @} */
 
+#ifdef __cplusplus
+}
 #endif
 
+#endif

include/bl_crypto.rst

@@ -0,0 +1,52 @@
+.. _doc_bl_crypto:
+
+Bootloader crypto
+#################
+
+The bootloader crypto library is the cryptography library that is used by the :ref:`bootloader`.
+
+The API is public because applications that are booted by the immutable bootloader can call functions from this library via the bootloader's code, through external APIs.
+See :ref:`doc_fw_info_ext_api` for more information.
+
+The library provides the following functionality:
+
+* SHA256 hashing
+* SECP256R1 signature validation
+* Root-of-trust firmware validation, which is the function the bootloader uses to validate a firmware's signature and digest, using the SHA256 and SECP256R1 algorithms
+
+These functions are available as separate external APIs.
+The API can be used the same way regardless of which backend is used.
+
+Backends
+********
+
+When using the library, you can choose between the following backends:
+
+* Hardware backend :ref:`nrf_cc310_bl_readme` (can only be used if Arm CryptoCell CC310 is available)
+* Software backend :ref:`nrf_oberon_readme`
+* Another image's instance of the bootloader crypto library, called via external APIs.
+  The other image chooses its own backend.
+
+To configure which backend is used for hashing, set one of the following configuration options:
+
+* :option:`CONFIG_SB_CRYPTO_OBERON_SHA256`
+* :option:`CONFIG_SB_CRYPTO_CC310_SHA256`
+* :option:`CONFIG_SB_CRYPTO_CLIENT_SHA256`
+
+To configure which backend is used for firmware verification, set one of the following configuration options:
+
+* :option:`CONFIG_SB_CRYPTO_CC310_ECDSA_SECP256R1`
+* :option:`CONFIG_SB_CRYPTO_OBERON_ECDSA_SECP256R1`
+* :option:`CONFIG_SB_CRYPTO_CLIENT_ECDSA_SECP256R1`
+
+
+
+API documentation
+*****************
+
+| Header file: :file:`include/bl_crypto.h`
+| Source files: :file:`subsys/bootloader/bl_crypto/` and :file:`subsys/bootloader/bl_crypto_client/`
+
+.. doxygengroup:: bl_crypto
+   :project: nrf
+   :members: