doc: cracen: add doxygen docs to cracenpsa headers

Added doxygen API documentation to headers under cracenpsa/include.
NCSDK-33026.

Signed-off-by: Grzegorz Ferenc <[email protected]>

Author: greg-fer

doc/nrf/nrf.doxyfile.in

@@ -963,6 +963,7 @@ INPUT                  = @DOCSET_SOURCE_BASE@/applications \
                          @DOCSET_SOURCE_BASE@/subsys/nrf_security/include/psa/crypto_driver_contexts_key_derivation.h \
                          @DOCSET_SOURCE_BASE@/subsys/nrf_security/include/psa/crypto_driver_contexts_primitives.h \
                          @DOCSET_SOURCE_BASE@/subsys/nrf_security/include/nrf_security_api_structure.h \
+                         @DOCSET_SOURCE_BASE@/subsys/nrf_security/src/drivers/cracen/cracenpsa/include \
                          @DOCSET_SOURCE_BASE@/subsys/trusted_storage/include/psa \
 
 # This tag can be used to specify the character encoding of the source files

doc/nrf/security/crypto/drivers.rst

@@ -446,3 +446,10 @@ API documentation
 | Header files: :file:`subsys/nrf_security/include/psa/crypto_driver_contexts_*.h`
 
 .. doxygengroup:: nrf_security_api_structures
+
+CRACEN driver API
+=================
+
+| Header files: :file:`subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa.h` and related headers
+
+.. doxygengroup:: cracen_psa_driver

subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa.h

@@ -4,6 +4,13 @@
  * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
  */
 
+/**
+ * @file
+ * @addtogroup cracen_psa_driver
+ * @{
+ * @brief Built-in key policy definitions for CRACEN PSA driver.
+ */
+
 #ifndef CRACEN_PSA_BUILTIN_KEY_POLICY_H
 #define CRACEN_PSA_BUILTIN_KEY_POLICY_H
 
@@ -12,24 +19,37 @@
 
 #if defined(__NRF_TFM__)
 
+/** @brief Built-in IKG key policy structure. */
 typedef struct {
-	mbedtls_key_owner_id_t owner;
-	psa_drv_slot_number_t key_slot;
+	mbedtls_key_owner_id_t owner;      /**< Key owner ID. */
+	psa_drv_slot_number_t key_slot;    /**< Key slot number. */
 } cracen_builtin_ikg_key_policy_t;
 
+/** @brief KMU entry slot type. */
 typedef enum {
-	KMU_ENTRY_SLOT_SINGLE,
-	KMU_ENTRY_SLOT_RANGE,
+	KMU_ENTRY_SLOT_SINGLE,  /**< Single slot entry. */
+	KMU_ENTRY_SLOT_RANGE,   /**< Range of slots entry. */
 } cracen_kmu_entry_type_t;
 
-/* When defining a range of KMU slots both the start and end slot numbers are inclusive. */
+/** @brief Built-in KMU key policy structure.
+ *
+ * When defining a range of KMU slots, both the start and end slot numbers
+ * are inclusive.
+ */
 typedef struct {
-	mbedtls_key_owner_id_t owner;
-	psa_drv_slot_number_t key_slot_start;
-	psa_drv_slot_number_t key_slot_end;
-	cracen_kmu_entry_type_t kmu_entry_type;
+	mbedtls_key_owner_id_t owner;         /**< Key owner ID. */
+	psa_drv_slot_number_t key_slot_start; /**< Start slot number (inclusive). */
+	psa_drv_slot_number_t key_slot_end;   /**< End slot number (inclusive). */
+	cracen_kmu_entry_type_t kmu_entry_type; /**< Entry type. */
 } cracen_builtin_kmu_key_policy_t;
 
+/** @brief Check if a user is allowed to access a built-in key.
+ *
+ * @param[in] attributes Key attributes.
+ *
+ * @retval true  The user is allowed to access the key.
+ * @retval false The user is not allowed to access the key.
+ */
 bool cracen_builtin_key_user_allowed(const psa_key_attributes_t *attributes);
 
 #else
@@ -42,4 +62,6 @@ static inline bool cracen_builtin_key_user_allowed(const psa_key_attributes_t *a
 
 #endif /* __NRF_TFM__ */
 
+/** @} */
+
 #endif /* CRACEN_PSA_BUILTIN_KEY_POLICY_H */

subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_builtin_key_policy.h

@@ -4,36 +4,116 @@
  * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
  */
 
+/**
+ * @file
+ * @addtogroup cracen_psa_driver
+ * @{
+ * @brief ECDSA operations for CRACEN PSA driver.
+ */
+
 #ifndef CRACEN_PSA_ECDSA_H
 #define CRACEN_PSA_ECDSA_H
 
 #include <psa/crypto.h>
 #include <stdint.h>
 
+/** @brief Verify an ECDSA message signature.
+ *
+ * @param[in] pubkey        Public key.
+ * @param[in] hashalg       Hash algorithm.
+ * @param[in] message       Message that was signed.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[in] curve         Elliptic curve parameters.
+ * @param[in] signature     Signature to verify.
+ *
+ * @retval 0  The signature is valid.
+ * @retval <0 The signature is invalid or an error occurred.
+ */
 int cracen_ecdsa_verify_message(const uint8_t *pubkey, const struct sxhashalg *hashalg,
 				const uint8_t *message, size_t message_length,
 				const struct sx_pk_ecurve *curve, const uint8_t *signature);
 
+/** @brief Verify an ECDSA digest signature.
+ *
+ * @param[in] pubkey   Public key.
+ * @param[in] digest   Digest that was signed.
+ * @param[in] digestsz Length of the digest in bytes.
+ * @param[in] curve    Elliptic curve parameters.
+ * @param[in] signature Signature to verify.
+ *
+ * @retval 0  The signature is valid.
+ * @retval <0 The signature is invalid or an error occurred.
+ */
 int cracen_ecdsa_verify_digest(const uint8_t *pubkey, const uint8_t *digest, size_t digestsz,
 			       const struct sx_pk_ecurve *curve, const uint8_t *signature);
 
+/** @brief Sign a message using ECDSA.
+ *
+ * @param[in] privkey       Private key structure.
+ * @param[in] hashalg       Hash algorithm.
+ * @param[in] curve         Elliptic curve parameters.
+ * @param[in] message       Message to sign.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[out] signature    Buffer to store the signature.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ecdsa_sign_message(const struct cracen_ecc_priv_key *privkey,
 			      const struct sxhashalg *hashalg, const struct sx_pk_ecurve *curve,
 			      const uint8_t *message, size_t message_length, uint8_t *signature);
 
+/** @brief Sign a digest using ECDSA.
+ *
+ * @param[in] privkey       Private key structure.
+ * @param[in] hashalg       Hash algorithm.
+ * @param[in] curve         Elliptic curve parameters.
+ * @param[in] digest        Digest to sign.
+ * @param[in] digest_length Length of the digest in bytes.
+ * @param[out] signature    Buffer to store the signature.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ecdsa_sign_digest(const struct cracen_ecc_priv_key *privkey,
 			     const struct sxhashalg *hashalg, const struct sx_pk_ecurve *curve,
 			     const uint8_t *digest, size_t digest_length, uint8_t *signature);
 
+/** @brief Sign a message using deterministic ECDSA.
+ *
+ * @param[in] privkey       Private key structure.
+ * @param[in] hashalg       Hash algorithm.
+ * @param[in] curve         Elliptic curve parameters.
+ * @param[in] message       Message to sign.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[out] signature    Buffer to store the signature.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ecdsa_sign_message_deterministic(const struct cracen_ecc_priv_key *privkey,
 					    const struct sxhashalg *hashalg,
 					    const struct sx_pk_ecurve *curve,
 					    const uint8_t *message, size_t message_length,
 					    uint8_t *signature);
 
+/** @brief Sign a digest using deterministic ECDSA.
+ *
+ * @param[in] privkey   Private key structure.
+ * @param[in] hashalg   Hash algorithm.
+ * @param[in] curve     Elliptic curve parameters.
+ * @param[in] digest    Digest to sign.
+ * @param[in] digestsz  Length of the digest in bytes.
+ * @param[out] signature Buffer to store the signature.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ecdsa_sign_digest_deterministic(const struct cracen_ecc_priv_key *privkey,
 					   const struct sxhashalg *hashalg,
 					   const struct sx_pk_ecurve *curve, const uint8_t *digest,
 					   size_t digestsz, uint8_t *signature);
 
+/** @} */
+
 #endif /* CRACEN_PSA_ECDSA_H */

subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ecdsa.h

@@ -4,39 +4,148 @@
  * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
  */
 
+/**
+ * @file
+ * @addtogroup cracen_psa_driver
+ * @{
+ * @brief EdDSA operations for CRACEN PSA driver.
+ */
+
 #ifndef CRACEN_PSA_EDDSA_H
 #define CRACEN_PSA_EDDSA_H
 
 #include <stddef.h>
 #include <stdbool.h>
 #include <stdint.h>
 
+/** @brief Sign a message using Ed25519.
+ *
+ * @param[in] priv_key      Private key.
+ * @param[out] signature    Buffer to store the signature.
+ * @param[in] message       Message to sign.
+ * @param[in] message_length Length of the message in bytes.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ed25519_sign(const uint8_t *priv_key, uint8_t *signature, const uint8_t *message,
 			size_t message_length);
 
+/** @brief Verify an Ed25519 signature.
+ *
+ * @param[in] pub_key       Public key.
+ * @param[in] message       Message that was signed.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[in] signature     Signature to verify.
+ *
+ * @retval 0  The signature is valid.
+ * @retval <0 The signature is invalid or an error occurred.
+ */
 int cracen_ed25519_verify(const uint8_t *pub_key, const uint8_t *message, size_t message_length,
 			  const uint8_t *signature);
 
+/** @brief Sign a message using Ed25519ph (pre-hashed).
+ *
+ * @param[in] priv_key      Private key.
+ * @param[out] signature    Buffer to store the signature.
+ * @param[in] message       Message or hash to sign.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[in] is_message    True if @p message is a message, false if it's a hash.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ed25519ph_sign(const uint8_t *priv_key, uint8_t *signature, const uint8_t *message,
 			  size_t message_length, bool is_message);
 
+/** @brief Verify an Ed25519ph signature.
+ *
+ * @param[in] pub_key       Public key.
+ * @param[in] message       Message or hash that was signed.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[in] signature     Signature to verify.
+ * @param[in] is_message    True if @p message is a message, false if it's a hash.
+ *
+ * @retval 0  The signature is valid.
+ * @retval <0 The signature is invalid or an error occurred.
+ */
 int cracen_ed25519ph_verify(const uint8_t *pub_key, const uint8_t *message, size_t message_length,
 			    const uint8_t *signature, bool is_message);
 
+/** @brief Create an Ed25519 public key from a private key.
+ *
+ * @param[in] priv_key Private key.
+ * @param[out] pub_key  Buffer to store the public key.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ed25519_create_pubkey(const uint8_t *priv_key, uint8_t *pub_key);
 
+/** @brief Sign a message using Ed448.
+ *
+ * @param[in] priv_key      Private key.
+ * @param[out] signature    Buffer to store the signature.
+ * @param[in] message       Message to sign.
+ * @param[in] message_length Length of the message in bytes.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ed448_sign(const uint8_t *priv_key, uint8_t *signature, const uint8_t *message,
 			size_t message_length);
 
+/** @brief Verify an Ed448 signature.
+ *
+ * @param[in] pub_key       Public key.
+ * @param[in] message       Message that was signed.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[in] signature     Signature to verify.
+ *
+ * @retval 0  The signature is valid.
+ * @retval <0 The signature is invalid or an error occurred.
+ */
 int cracen_ed448_verify(const uint8_t *pub_key, const uint8_t *message, size_t message_length,
 			  const uint8_t *signature);
 
+/** @brief Sign a message using Ed448ph (pre-hashed).
+ *
+ * @param[in] priv_key      Private key.
+ * @param[out] signature    Buffer to store the signature.
+ * @param[in] message       Message or hash to sign.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[in] is_message    True if @p message is a message, false if it's a hash.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ed448ph_sign(const uint8_t *priv_key, uint8_t *signature, const uint8_t *message,
 			  size_t message_length, bool is_message);
 
+/** @brief Verify an Ed448ph signature.
+ *
+ * @param[in] pub_key       Public key.
+ * @param[in] message       Message or hash that was signed.
+ * @param[in] message_length Length of the message in bytes.
+ * @param[in] signature     Signature to verify.
+ * @param[in] is_message    True if @p message is a message, false if it's a hash.
+ *
+ * @retval 0  The signature is valid.
+ * @retval <0 The signature is invalid or an error occurred.
+ */
 int cracen_ed448ph_verify(const uint8_t *pub_key, const uint8_t *message, size_t message_length,
 			    const uint8_t *signature, bool is_message);
 
+/** @brief Create an Ed448 public key from a private key.
+ *
+ * @param[in] priv_key Private key.
+ * @param[out] pub_key  Buffer to store the public key.
+ *
+ * @retval 0  The operation completed successfully.
+ * @retval <0 An error occurred.
+ */
 int cracen_ed448_create_pubkey(const uint8_t *priv_key, uint8_t *pub_key);
 
+/** @} */
+
 #endif /* CRACEN_PSA_EDDSA_H */