diff --git a/doc/nrf/nrf.doxyfile.in b/doc/nrf/nrf.doxyfile.in index d80dae2486c1..b0f55b024bf4 100644 --- a/doc/nrf/nrf.doxyfile.in +++ b/doc/nrf/nrf.doxyfile.in @@ -963,6 +963,8 @@ 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/nrf_security/src/drivers/cracen/common/include/cracen/statuscodes.h \ @DOCSET_SOURCE_BASE@/subsys/trusted_storage/include/psa \ # This tag can be used to specify the character encoding of the source files diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 156fa5cda04f..efca05d8aaca 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -120,6 +120,8 @@ Security The algorithm implementation is conformant to the NIST SP 800-108 Rev. 1 recommendation. * Support for the secp384r1 key storage in the :ref:`Key Management Unit (KMU) `. +* Updated the :ref:`API documentation section for the cryptographic drivers ` with links to the added API documentation for the CRACEN driver. + Protocols ========= @@ -437,7 +439,9 @@ Gazell libraries Security libraries ------------------ -|no_changes_yet_note| +* :ref:`nrf_security` library: + + * Updated the header files at :file:`subsys/nrf_security/src/drivers/cracen/cracenpsa/include/` with Doxygen documentation. Modem libraries --------------- diff --git a/doc/nrf/security/crypto/drivers.rst b/doc/nrf/security/crypto/drivers.rst index 65cc637d71bb..0340f7ef6602 100644 --- a/doc/nrf/security/crypto/drivers.rst +++ b/doc/nrf/security/crypto/drivers.rst @@ -440,9 +440,25 @@ For configuration details, see the following pages: * :ref:`psa_crypto_support` * :ref:`nrf_security_legacy_backend_config` (nrf_oberon used as legacy backend) +.. _crypto_drivers_api_documentation: + 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/` + +.. doxygengroup:: cracen_psa_driver_apis + +SX status codes +=============== + +| Header files: :file:`subsys/nrf_security/src/drivers/cracen/common/include/cracen/statuscodes.h` + +.. doxygengroup:: status_codes diff --git a/subsys/nrf_security/src/drivers/cracen/common/include/cracen/statuscodes.h b/subsys/nrf_security/src/drivers/cracen/common/include/cracen/statuscodes.h index 336654d52195..9e752a368b06 100644 --- a/subsys/nrf_security/src/drivers/cracen/common/include/cracen/statuscodes.h +++ b/subsys/nrf_security/src/drivers/cracen/common/include/cracen/statuscodes.h @@ -8,7 +8,8 @@ #define CRACEN_STATUSCODES_HEADER_FILE /** - * @addtogroup + * @defgroup status_codes SX Status Codes + * @brief SX status code definitions. * * @{ */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa.h index e68d849bfd0f..0d59c49277d8 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa.h @@ -4,6 +4,23 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_driver_api + * @{ + * @brief PSA Crypto driver API for CRACEN hardware accelerator. + * + * @note This is the public driver API. Applications should use the PSA Crypto API + * (psa_* functions) instead of calling these driver functions directly. + * This header documents the driver implementation that is called by the + * PSA Crypto layer. See Arm's PSA Crypto API for the public interface. + * + * This module provides the PSA Crypto driver API implementation for the + * CRACEN hardware accelerator. It implements cryptographic operations + * including signing, verification, hashing, encryption, decryption, key + * management, and more. + */ + #ifndef CRACEN_PSA_H #define CRACEN_PSA_H @@ -18,35 +35,123 @@ #include "cracen_psa_key_ids.h" #include "sxsymcrypt/keyref.h" -/** - * See "PSA Cryptography API" for documentation. +/** @brief Sign a message. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Signing algorithm. + * @param[in] input Message to sign. + * @param[in] input_length Length of the message in bytes. + * @param[out] signature Buffer to store the signature. + * @param[in] signature_size Size of the signature buffer in bytes. + * @param[out] signature_length Length of the generated signature in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. */ - psa_status_t cracen_sign_message(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length); +/** @brief Verify a message signature. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Verification algorithm. + * @param[in] input Message that was signed. + * @param[in] input_length Length of the message in bytes. + * @param[in] signature Signature to verify. + * @param[in] signature_length Length of the signature in bytes. + * + * @retval PSA_SUCCESS The signature is valid. + * @retval PSA_ERROR_INVALID_SIGNATURE The signature is invalid. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_verify_message(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length); +/** @brief Sign a hash or digest. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Signing algorithm. + * @param[in] hash Hash or digest to sign. + * @param[in] hash_length Length of the hash in bytes. + * @param[out] signature Buffer to store the signature. + * @param[in] signature_size Size of the signature buffer in bytes. + * @param[out] signature_length Length of the generated signature in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_sign_hash(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length); +/** @brief Verify a hash signature. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Verification algorithm. + * @param[in] hash Hash or digest that was signed. + * @param[in] hash_length Length of the hash in bytes. + * @param[in] signature Signature to verify. + * @param[in] signature_length Length of the signature in bytes. + * + * @retval PSA_SUCCESS The signature is valid. + * @retval PSA_ERROR_INVALID_SIGNATURE The signature is invalid. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_verify_hash(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length); +/** @brief Compute a hash. + * + * @param[in] alg Hash algorithm. + * @param[in] input Input data to hash. + * @param[in] input_length Length of the input data in bytes. + * @param[out] hash Buffer to store the hash. + * @param[in] hash_size Size of the hash buffer in bytes. + * @param[out] hash_length Length of the generated hash in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The hash buffer is too small. + */ psa_status_t cracen_hash_compute(psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length); +/** @brief Set up a hash operation. + * + * @param[in,out] operation Hash operation context. + * @param[in] alg Hash algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_hash_setup(cracen_hash_operation_t *operation, psa_algorithm_t alg); +/** @brief Clone a hash operation. + * + * @param[in] source_operation Source hash operation context. + * @param[out] target_operation Target hash operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ static inline psa_status_t cracen_hash_clone(const cracen_hash_operation_t *source_operation, cracen_hash_operation_t *target_operation) { @@ -58,12 +163,38 @@ static inline psa_status_t cracen_hash_clone(const cracen_hash_operation_t *sour return PSA_SUCCESS; } +/** @brief Update a hash operation with input data. + * + * @param[in,out] operation Hash operation context. + * @param[in] input Input data to add to the hash. + * @param[in] input_length Length of the input data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_hash_update(cracen_hash_operation_t *operation, const uint8_t *input, const size_t input_length); +/** @brief Finish a hash operation. + * + * @param[in,out] operation Hash operation context. + * @param[out] hash Buffer to store the hash. + * @param[in] hash_size Size of the hash buffer in bytes. + * @param[out] hash_length Length of the generated hash in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The hash buffer is too small. + */ psa_status_t cracen_hash_finish(cracen_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length); +/** @brief Abort a hash operation. + * + * @param[in,out] operation Hash operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ static inline psa_status_t cracen_hash_abort(cracen_hash_operation_t *operation) { __ASSERT_NO_MSG(operation != NULL); @@ -73,6 +204,27 @@ static inline psa_status_t cracen_hash_abort(cracen_hash_operation_t *operation) return PSA_SUCCESS; } +/** @brief Encrypt and authenticate a message using AEAD. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg AEAD algorithm. + * @param[in] nonce Nonce or IV. + * @param[in] nonce_length Length of the nonce in bytes. + * @param[in] additional_data Additional authenticated data. + * @param[in] additional_data_length Length of additional data in bytes. + * @param[in] plaintext Plaintext to encrypt. + * @param[in] plaintext_length Length of the plaintext in bytes. + * @param[out] ciphertext Buffer to store the ciphertext and tag. + * @param[in] ciphertext_size Size of the ciphertext buffer in bytes. + * @param[out] ciphertext_length Length of the generated ciphertext in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The ciphertext buffer is too small. + */ psa_status_t cracen_aead_encrypt(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, @@ -80,6 +232,28 @@ psa_status_t cracen_aead_encrypt(const psa_key_attributes_t *attributes, const u size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length); +/** @brief Decrypt and verify a message using AEAD. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg AEAD algorithm. + * @param[in] nonce Nonce or IV. + * @param[in] nonce_length Length of the nonce in bytes. + * @param[in] additional_data Additional authenticated data. + * @param[in] additional_data_length Length of additional data in bytes. + * @param[in] ciphertext Ciphertext and tag to decrypt. + * @param[in] ciphertext_length Length of the ciphertext in bytes. + * @param[out] plaintext Buffer to store the plaintext. + * @param[in] plaintext_size Size of the plaintext buffer in bytes. + * @param[out] plaintext_length Length of the decrypted plaintext in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_INVALID_SIGNATURE The authentication tag is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The plaintext buffer is too small. + */ psa_status_t cracen_aead_decrypt(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, @@ -87,284 +261,1148 @@ psa_status_t cracen_aead_decrypt(const psa_key_attributes_t *attributes, const u size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length); +/** @brief Encrypt a message using a symmetric cipher. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Cipher algorithm. + * @param[in] iv Initialization vector. + * @param[in] iv_length Length of the IV in bytes. + * @param[in] input Plaintext to encrypt. + * @param[in] input_length Length of the plaintext in bytes. + * @param[out] output Buffer to store the ciphertext. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated ciphertext in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_cipher_encrypt(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *iv, size_t iv_length, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Decrypt a message using a symmetric cipher. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Cipher algorithm. + * @param[in] input Ciphertext to decrypt. + * @param[in] input_length Length of the ciphertext in bytes. + * @param[out] output Buffer to store the plaintext. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the decrypted plaintext in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_cipher_decrypt(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Set up a cipher encryption operation. + * + * @param[in,out] operation Cipher operation context. + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Cipher algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_cipher_encrypt_setup(cracen_cipher_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg); +/** @brief Set up a cipher decryption operation. + * + * @param[in,out] operation Cipher operation context. + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Cipher algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_cipher_decrypt_setup(cracen_cipher_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg); +/** @brief Set the initialization vector for a cipher operation. + * + * @param[in,out] operation Cipher operation context. + * @param[in] iv Initialization vector. + * @param[in] iv_length Length of the IV in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_cipher_set_iv(cracen_cipher_operation_t *operation, const uint8_t *iv, size_t iv_length); +/** @brief Process input data in a cipher operation. + * + * @param[in,out] operation Cipher operation context. + * @param[in] input Input data to process. + * @param[in] input_length Length of the input data in bytes. + * @param[out] output Buffer to store the output. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated output in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_cipher_update(cracen_cipher_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Finish a cipher operation. + * + * @param[in,out] operation Cipher operation context. + * @param[out] output Buffer to store the final output. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated output in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_cipher_finish(cracen_cipher_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Abort a cipher operation. + * + * @param[in,out] operation Cipher operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_cipher_abort(cracen_cipher_operation_t *operation); +/** @brief Set up an AEAD encryption operation. + * + * @param[in,out] operation AEAD operation context. + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg AEAD algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_aead_encrypt_setup(cracen_aead_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg); +/** @brief Set up an AEAD decryption operation. + * + * @param[in,out] operation AEAD operation context. + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg AEAD algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_aead_decrypt_setup(cracen_aead_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg); +/** @brief Set the nonce for an AEAD operation. + * + * @param[in,out] operation AEAD operation context. + * @param[in] nonce Nonce or IV. + * @param[in] nonce_length Length of the nonce in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_aead_set_nonce(cracen_aead_operation_t *operation, const uint8_t *nonce, size_t nonce_length); +/** @brief Set the lengths for an AEAD operation. + * + * @param[in,out] operation AEAD operation context. + * @param[in] ad_length Length of additional authenticated data in bytes. + * @param[in] plaintext_length Length of plaintext in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_aead_set_lengths(cracen_aead_operation_t *operation, size_t ad_length, size_t plaintext_length); +/** @brief Add additional authenticated data to an AEAD operation. + * + * @param[in,out] operation AEAD operation context. + * @param[in] input Additional authenticated data. + * @param[in] input_length Length of the additional data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_aead_update_ad(cracen_aead_operation_t *operation, const uint8_t *input, size_t input_length); +/** @brief Process input data in an AEAD operation. + * + * @param[in,out] operation AEAD operation context. + * @param[in] input Input data to process. + * @param[in] input_length Length of the input data in bytes. + * @param[out] output Buffer to store the output. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated output in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_aead_update(cracen_aead_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Finish an AEAD encryption operation. + * + * @param[in,out] operation AEAD operation context. + * @param[out] ciphertext Buffer to store the final ciphertext. + * @param[in] ciphertext_size Size of the ciphertext buffer in bytes. + * @param[out] ciphertext_length Length of the generated ciphertext in bytes. + * @param[out] tag Buffer to store the authentication tag. + * @param[in] tag_size Size of the tag buffer in bytes. + * @param[out] tag_length Length of the generated tag in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL A buffer is too small. + */ psa_status_t cracen_aead_finish(cracen_aead_operation_t *operation, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length, uint8_t *tag, size_t tag_size, size_t *tag_length); +/** @brief Finish an AEAD decryption operation and verify the tag. + * + * @param[in,out] operation AEAD operation context. + * @param[out] plaintext Buffer to store the final plaintext. + * @param[in] plaintext_size Size of the plaintext buffer in bytes. + * @param[out] plaintext_length Length of the generated plaintext in bytes. + * @param[in] tag Authentication tag to verify. + * @param[in] tag_length Length of the tag in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully and the tag is valid. + * @retval PSA_ERROR_INVALID_SIGNATURE The authentication tag is invalid. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The plaintext buffer is too small. + */ psa_status_t cracen_aead_verify(cracen_aead_operation_t *operation, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length, const uint8_t *tag, size_t tag_length); +/** @brief Abort an AEAD operation. + * + * @param[in,out] operation AEAD operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_aead_abort(cracen_aead_operation_t *operation); +/** @brief Compute a MAC in a single operation. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg MAC algorithm. + * @param[in] input Input data to authenticate. + * @param[in] input_length Length of the input data in bytes. + * @param[out] mac Buffer to store the MAC. + * @param[in] mac_size Size of the MAC buffer in bytes. + * @param[out] mac_length Length of the generated MAC in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The MAC buffer is too small. + */ psa_status_t cracen_mac_compute(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *mac, size_t mac_size, size_t *mac_length); +/** @brief Set up a MAC signing operation. + * + * @param[in,out] operation MAC operation context. + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg MAC algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_mac_sign_setup(cracen_mac_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg); +/** @brief Set up a MAC verification operation. + * + * @param[in,out] operation MAC operation context. + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg MAC algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_mac_verify_setup(cracen_mac_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg); +/** @brief Add input data to a MAC operation. + * + * @param[in,out] operation MAC operation context. + * @param[in] input Input data to add. + * @param[in] input_length Length of the input data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_mac_update(cracen_mac_operation_t *operation, const uint8_t *input, size_t input_length); +/** @brief Finish a MAC signing operation. + * + * @param[in,out] operation MAC operation context. + * @param[out] mac Buffer to store the MAC. + * @param[in] mac_size Size of the MAC buffer in bytes. + * @param[out] mac_length Length of the generated MAC in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The MAC buffer is too small. + */ psa_status_t cracen_mac_sign_finish(cracen_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_length); +/** @brief Finish a MAC verification operation. + * + * @param[in,out] operation MAC operation context. + * @param[in] mac MAC to verify. + * @param[in] mac_length Length of the MAC in bytes. + * + * @retval PSA_SUCCESS The MAC is valid. + * @retval PSA_ERROR_INVALID_SIGNATURE The MAC is invalid. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_mac_verify_finish(cracen_mac_operation_t *operation, const uint8_t *mac, size_t mac_length); +/** @brief Abort a MAC operation. + * + * @param[in,out] operation MAC operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_mac_abort(cracen_mac_operation_t *operation); +/** @brief Perform a key agreement operation. + * + * @param[in] attributes Key attributes for the private key. + * @param[in] priv_key Private key material. + * @param[in] priv_key_size Size of the private key in bytes. + * @param[in] publ_key Public key material. + * @param[in] publ_key_size Size of the public key in bytes. + * @param[out] output Buffer to store the shared secret. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated shared secret in bytes. + * @param[in] alg Key agreement algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_key_agreement(const psa_key_attributes_t *attributes, const uint8_t *priv_key, size_t priv_key_size, const uint8_t *publ_key, size_t publ_key_size, uint8_t *output, size_t output_size, size_t *output_length, psa_algorithm_t alg); +/** @brief Set up a key derivation operation. + * + * @param[in,out] operation Key derivation operation context. + * @param[in] alg Key derivation algorithm. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_key_derivation_setup(cracen_key_derivation_operation_t *operation, psa_algorithm_t alg); +/** @brief Set the capacity for a key derivation operation. + * + * @param[in,out] operation Key derivation operation context. + * @param[in] capacity Maximum capacity in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_key_derivation_set_capacity(cracen_key_derivation_operation_t *operation, size_t capacity); +/** @brief Provide a key as input to a key derivation operation. + * + * @param[in,out] operation Key derivation operation context. + * @param[in] step Derivation step. + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_key_derivation_input_key(cracen_key_derivation_operation_t *operation, psa_key_derivation_step_t step, const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size); +/** @brief Provide bytes as input to a key derivation operation. + * + * @param[in,out] operation Key derivation operation context. + * @param[in] step Derivation step. + * @param[in] data Input data. + * @param[in] data_length Length of the input data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_key_derivation_input_bytes(cracen_key_derivation_operation_t *operation, psa_key_derivation_step_t step, const uint8_t *data, size_t data_length); +/** @brief Provide an integer as input to a key derivation operation. + * + * @param[in,out] operation Key derivation operation context. + * @param[in] step Derivation step. + * @param[in] value Integer value. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_key_derivation_input_integer(cracen_key_derivation_operation_t *operation, psa_key_derivation_step_t step, uint64_t value); +/** @brief Read output from a key derivation operation. + * + * @param[in,out] operation Key derivation operation context. + * @param[out] output Buffer to store the output. + * @param[in] output_length Length of the output to read in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_key_derivation_output_bytes(cracen_key_derivation_operation_t *operation, uint8_t *output, size_t output_length); +/** @brief Abort a key derivation operation. + * + * @param[in,out] operation Key derivation operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_key_derivation_abort(cracen_key_derivation_operation_t *operation); +/** @brief Export a public key. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[out] data Buffer to store the public key. + * @param[in] data_size Size of the data buffer in bytes. + * @param[out] data_length Length of the exported public key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The data buffer is too small. + */ psa_status_t cracen_export_public_key(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, uint8_t *data, size_t data_size, size_t *data_length); +/** @brief Import a key. + * + * @param[in] attributes Key attributes. + * @param[in] data Key data to import. + * @param[in] data_length Length of the key data in bytes. + * @param[out] key_buffer Buffer to store the imported key. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[out] key_buffer_length Length of the imported key in bytes. + * @param[out] key_bits Size of the key in bits. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_ARGUMENT The key data is invalid. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The key buffer is too small. + */ psa_status_t cracen_import_key(const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length, size_t *key_bits); +/** @brief Generate a key. + * + * @param[in] attributes Key attributes. + * @param[out] key_buffer Buffer to store the generated key. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[out] key_buffer_length Length of the generated key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The key type or size is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The key buffer is too small. + */ psa_status_t cracen_generate_key(const psa_key_attributes_t *attributes, uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length); +/** @brief Encrypt a message using an asymmetric key. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Encryption algorithm. + * @param[in] input Plaintext to encrypt. + * @param[in] input_length Length of the plaintext in bytes. + * @param[in] salt Optional salt. + * @param[in] salt_length Length of the salt in bytes. + * @param[out] output Buffer to store the ciphertext. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated ciphertext in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_asymmetric_encrypt(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Decrypt a message using an asymmetric key. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[in] alg Decryption algorithm. + * @param[in] input Ciphertext to decrypt. + * @param[in] input_length Length of the ciphertext in bytes. + * @param[in] salt Optional salt. + * @param[in] salt_length Length of the salt in bytes. + * @param[out] output Buffer to store the plaintext. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the decrypted plaintext in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_asymmetric_decrypt(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Get a built-in key. + * + * @param[in] slot_number Key slot number. + * @param[out] attributes Key attributes. + * @param[out] key_buffer Buffer to store the key. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[out] key_buffer_length Length of the key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_DOES_NOT_EXIST The key does not exist. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The key buffer is too small. + */ psa_status_t cracen_get_builtin_key(psa_drv_slot_number_t slot_number, psa_key_attributes_t *attributes, uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length); +/** @brief Export a key. + * + * @param[in] attributes Key attributes. + * @param[in] key_buffer Key material buffer. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[out] data Buffer to store the exported key. + * @param[in] data_size Size of the data buffer in bytes. + * @param[out] data_length Length of the exported key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The data buffer is too small. + */ psa_status_t cracen_export_key(const psa_key_attributes_t *attributes, const uint8_t *key_buffer, size_t key_buffer_size, uint8_t *data, size_t data_size, size_t *data_length); +/** @brief Copy a key. + * + * @param[in,out] attributes Key attributes for the target key. + * @param[in] source_key Source key material. + * @param[in] source_key_length Length of the source key in bytes. + * @param[out] target_key_buffer Buffer to store the copied key. + * @param[in] target_key_buffer_size Size of the target key buffer in bytes. + * @param[out] target_key_buffer_length Length of the copied key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The target key buffer is too small. + */ psa_status_t cracen_copy_key(psa_key_attributes_t *attributes, const uint8_t *source_key, size_t source_key_length, uint8_t *target_key_buffer, size_t target_key_buffer_size, size_t *target_key_buffer_length); +/** @brief Destroy a key. + * + * @param[in] attributes Key attributes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + */ psa_status_t cracen_destroy_key(const psa_key_attributes_t *attributes); +/** @brief Get the size of an opaque key. + * + * @param[in] attributes Key attributes. + * @param[out] key_size Size of the key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + */ psa_status_t cracen_get_opaque_size(const psa_key_attributes_t *attributes, size_t *key_size); +/** @brief Set up a JPAKE operation. + * + * @param[in,out] operation JPAKE operation context. + * @param[in] attributes Key attributes. + * @param[in] password Password. + * @param[in] password_length Length of the password in bytes. + * @param[in] cipher_suite PAKE cipher suite. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_jpake_setup(cracen_jpake_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *password, size_t password_length, const psa_pake_cipher_suite_t *cipher_suite); +/** @brief Set the password key for a JPAKE operation. + * + * @param[in,out] operation JPAKE operation context. + * @param[in] attributes Key attributes. + * @param[in] password Password. + * @param[in] password_length Length of the password in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_jpake_set_password_key(cracen_jpake_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *password, size_t password_length); +/** @brief Set the user identifier for a JPAKE operation. + * + * @param[in,out] operation JPAKE operation context. + * @param[in] user_id User identifier. + * @param[in] user_id_len Length of the user identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_jpake_set_user(cracen_jpake_operation_t *operation, const uint8_t *user_id, size_t user_id_len); +/** @brief Set the peer identifier for a JPAKE operation. + * + * @param[in,out] operation JPAKE operation context. + * @param[in] peer_id Peer identifier. + * @param[in] peer_id_len Length of the peer identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_jpake_set_peer(cracen_jpake_operation_t *operation, const uint8_t *peer_id, size_t peer_id_len); +/** @brief Set the role for a JPAKE operation. + * + * @param[in,out] operation JPAKE operation context. + * @param[in] role PAKE role. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_jpake_set_role(cracen_jpake_operation_t *operation, psa_pake_role_t role); +/** @brief Get output from a JPAKE operation step. + * + * @param[in,out] operation JPAKE operation context. + * @param[in] step PAKE step. + * @param[out] output Buffer to store the output. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated output in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_jpake_output(cracen_jpake_operation_t *operation, psa_pake_step_t step, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Provide input to a JPAKE operation step. + * + * @param[in,out] operation JPAKE operation context. + * @param[in] step PAKE step. + * @param[in] input Input data. + * @param[in] input_length Length of the input data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_jpake_input(cracen_jpake_operation_t *operation, psa_pake_step_t step, const uint8_t *input, size_t input_length); +/** @brief Get the shared key from a completed JPAKE operation. + * + * @param[in,out] operation JPAKE operation context. + * @param[in] attributes Key attributes for the shared key. + * @param[out] output Buffer to store the shared key. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated shared key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_jpake_get_shared_key(cracen_jpake_operation_t *operation, const psa_key_attributes_t *attributes, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Abort a JPAKE operation. + * + * @param[in,out] operation JPAKE operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_jpake_abort(cracen_jpake_operation_t *operation); +/** @brief Initialize a random number generator context. + * + * @param[in,out] context PRNG context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_init_random(cracen_prng_context_t *context); + +/** @brief Get random bytes from a PRNG context. + * + * @param[in,out] context PRNG context. + * @param[out] output Buffer to store the random bytes. + * @param[in] output_size Number of random bytes to generate. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_get_random(cracen_prng_context_t *context, uint8_t *output, size_t output_size); + +/** @brief Free a random number generator context. + * + * @param[in,out] context PRNG context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_free_random(cracen_prng_context_t *context); +/** @brief Set up an SRP operation. + * + * @param[in,out] operation SRP operation context. + * @param[in] attributes Key attributes. + * @param[in] password Password. + * @param[in] password_length Length of the password in bytes. + * @param[in] cipher_suite PAKE cipher suite. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_srp_setup(cracen_srp_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *password, size_t password_length, const psa_pake_cipher_suite_t *cipher_suite); +/** @brief Set the user identifier for an SRP operation. + * + * @param[in,out] operation SRP operation context. + * @param[in] user_id User identifier. + * @param[in] user_id_len Length of the user identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_srp_set_user(cracen_srp_operation_t *operation, const uint8_t *user_id, size_t user_id_len); + +/** @brief Set the role for an SRP operation. + * + * @param[in,out] operation SRP operation context. + * @param[in] role PAKE role. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_srp_set_role(cracen_srp_operation_t *operation, psa_pake_role_t role); + +/** @brief Set the password key for an SRP operation. + * + * @param[in,out] operation SRP operation context. + * @param[in] attributes Key attributes. + * @param[in] password Password. + * @param[in] password_length Length of the password in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_srp_set_password_key(cracen_srp_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *password, size_t password_length); + +/** @brief Get output from an SRP operation step. + * + * @param[in,out] operation SRP operation context. + * @param[in] step PAKE step. + * @param[out] output Buffer to store the output. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated output in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_srp_output(cracen_srp_operation_t *operation, psa_pake_step_t step, uint8_t *output, size_t output_size, size_t *output_length); + +/** @brief Provide input to an SRP operation step. + * + * @param[in,out] operation SRP operation context. + * @param[in] step PAKE step. + * @param[in] input Input data. + * @param[in] input_length Length of the input data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_srp_input(cracen_srp_operation_t *operation, psa_pake_step_t step, const uint8_t *input, size_t input_length); + +/** @brief Get the shared key from a completed SRP operation. + * + * @param[in,out] operation SRP operation context. + * @param[in] attributes Key attributes for the shared key. + * @param[out] output Buffer to store the shared key. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated shared key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_srp_get_shared_key(cracen_srp_operation_t *operation, const psa_key_attributes_t *attributes, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Abort an SRP operation. + * + * @param[in,out] operation SRP operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_srp_abort(cracen_srp_operation_t *operation); +/** @brief Set up a PAKE operation. + * + * @param[in,out] operation PAKE operation context. + * @param[in] attributes Key attributes. + * @param[in] password Password. + * @param[in] password_length Length of the password in bytes. + * @param[in] cipher_suite PAKE cipher suite. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_pake_setup(cracen_pake_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *password, size_t password_length, const psa_pake_cipher_suite_t *cipher_suite); +/** @brief Set the user identifier for a PAKE operation. + * + * @param[in,out] operation PAKE operation context. + * @param[in] user_id User identifier. + * @param[in] user_id_len Length of the user identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_pake_set_user(cracen_pake_operation_t *operation, const uint8_t *user_id, size_t user_id_len); +/** @brief Set the peer identifier for a PAKE operation. + * + * @param[in,out] operation PAKE operation context. + * @param[in] peer_id Peer identifier. + * @param[in] peer_id_len Length of the peer identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_pake_set_peer(cracen_pake_operation_t *operation, const uint8_t *peer_id, size_t peer_id_len); +/** @brief Set the context for a PAKE operation. + * + * @param[in,out] operation PAKE operation context. + * @param[in] context Context data. + * @param[in] context_length Length of the context data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_pake_set_context(cracen_pake_operation_t *operation, const uint8_t *context, size_t context_length); +/** @brief Set the role for a PAKE operation. + * + * @param[in,out] operation PAKE operation context. + * @param[in] role PAKE role. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_pake_set_role(cracen_pake_operation_t *operation, psa_pake_role_t role); +/** @brief Get output from a PAKE operation step. + * + * @param[in,out] operation PAKE operation context. + * @param[in] step PAKE step. + * @param[out] output Buffer to store the output. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated output in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_pake_output(cracen_pake_operation_t *operation, psa_pake_step_t step, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Provide input to a PAKE operation step. + * + * @param[in,out] operation PAKE operation context. + * @param[in] step PAKE step. + * @param[in] input Input data. + * @param[in] input_length Length of the input data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_pake_input(cracen_pake_operation_t *operation, psa_pake_step_t step, const uint8_t *input, size_t input_length); +/** @brief Get the shared key from a completed PAKE operation. + * + * @param[in,out] operation PAKE operation context. + * @param[in] attributes Key attributes for the shared key. + * @param[out] key_buffer Buffer to store the shared key. + * @param[in] key_buffer_size Size of the key buffer in bytes. + * @param[out] key_buffer_length Length of the generated shared key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The key buffer is too small. + */ psa_status_t cracen_pake_get_shared_key(cracen_pake_operation_t *operation, const psa_key_attributes_t *attributes, uint8_t *key_buffer, size_t key_buffer_size, size_t *key_buffer_length); +/** @brief Abort a PAKE operation. + * + * @param[in,out] operation PAKE operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_pake_abort(cracen_pake_operation_t *operation); +/** @brief Set up a SPAKE2+ operation. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] attributes Key attributes. + * @param[in] password Password. + * @param[in] password_length Length of the password in bytes. + * @param[in] cipher_suite PAKE cipher suite. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_spake2p_setup(cracen_spake2p_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *password, size_t password_length, const psa_pake_cipher_suite_t *cipher_suite); +/** @brief Set the password key for a SPAKE2+ operation. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] attributes Key attributes. + * @param[in] password Password. + * @param[in] password_length Length of the password in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_spake2p_set_password_key(cracen_spake2p_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *password, size_t password_length); +/** @brief Set the user identifier for a SPAKE2+ operation. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] user_id User identifier. + * @param[in] user_id_len Length of the user identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_spake2p_set_user(cracen_spake2p_operation_t *operation, const uint8_t *user_id, size_t user_id_len); +/** @brief Set the peer identifier for a SPAKE2+ operation. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] peer_id Peer identifier. + * @param[in] peer_id_len Length of the peer identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_spake2p_set_peer(cracen_spake2p_operation_t *operation, const uint8_t *peer_id, size_t peer_id_len); +/** @brief Set the context for a SPAKE2+ operation. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] context Context data. + * @param[in] context_length Length of the context data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_spake2p_set_context(cracen_spake2p_operation_t *operation, const uint8_t *context, size_t context_length); +/** @brief Set the role for a SPAKE2+ operation. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] role PAKE role. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_spake2p_set_role(cracen_spake2p_operation_t *operation, psa_pake_role_t role); +/** @brief Get output from a SPAKE2+ operation step. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] step PAKE step. + * @param[out] output Buffer to store the output. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated output in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_spake2p_output(cracen_spake2p_operation_t *operation, psa_pake_step_t step, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Provide input to a SPAKE2+ operation step. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] step PAKE step. + * @param[in] input Input data. + * @param[in] input_length Length of the input data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_spake2p_input(cracen_spake2p_operation_t *operation, psa_pake_step_t step, const uint8_t *input, size_t input_length); +/** @brief Get the shared key from a completed SPAKE2+ operation. + * + * @param[in,out] operation SPAKE2+ operation context. + * @param[in] attributes Key attributes for the shared key. + * @param[out] output Buffer to store the shared key. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated shared key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_spake2p_get_shared_key(cracen_spake2p_operation_t *operation, const psa_key_attributes_t *attributes, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Abort a SPAKE2+ operation. + * + * @param[in,out] operation SPAKE2+ operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_spake2p_abort(cracen_spake2p_operation_t *operation); +/** @brief Derive a key from input material. + * + * @param[in] attributes Key attributes for the derived key. + * @param[in] input Input material. + * @param[in] input_length Length of the input material in bytes. + * @param[out] key Buffer to store the derived key. + * @param[in] key_size Size of the key buffer in bytes. + * @param[out] key_length Length of the derived key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The key derivation is not supported. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The key buffer is too small. + */ psa_status_t cracen_derive_key(const psa_key_attributes_t *attributes, const uint8_t *input, size_t input_length, uint8_t *key, size_t key_size, size_t *key_length); +/** @brief Get random bytes from the True Random Number Generator. + * + * @param[out] output Buffer to store the random bytes. + * @param[in] output_size Number of random bytes to generate. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_get_trng(uint8_t *output, size_t output_size); +/** @brief Get the key slot for a given key ID. + * + * @param[in] key_id Key ID. + * @param[out] lifetime Key lifetime. + * @param[out] slot_number Key slot number. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_DOES_NOT_EXIST The key does not exist. + */ psa_status_t cracen_get_key_slot(mbedtls_svc_key_id_t key_id, psa_key_lifetime_t *lifetime, psa_drv_slot_number_t *slot_number); +/** @} */ + #endif /* CRACEN_PSA_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_api_structure.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_api_structure.h new file mode 100644 index 000000000000..29bdfa829ac1 --- /dev/null +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_api_structure.h @@ -0,0 +1,115 @@ +/* + * Copyright (c) 2025 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause + */ + +/** + * @defgroup cracen_psa_driver_apis CRACEN PSA Driver APIs + * @brief Complete API structure for CRACEN PSA driver + * + * This file defines the hierarchical organization of all CRACEN PSA driver APIs. + * The APIs are organized into logical groups based on their purpose and visibility. + * + * @{ + */ + +/** + * @defgroup cracen_psa_driver_api CRACEN PSA Driver API + * @brief Public driver API for CRACEN PSA driver + * + * @note This is the public driver API. Applications should use the PSA Crypto API + * (psa_* functions) instead of calling these driver functions directly. + * + */ + +/** + * @defgroup cracen_psa_driver_internal CRACEN PSA Driver Internal API + * @brief Internal implementation APIs for CRACEN PSA driver + * + * @note These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + * @{ + */ + +/** + * @defgroup cracen_psa_ecdsa ECDSA Operations + * @brief ECDSA signature and verification operations (internal use only) + */ + +/** + * @defgroup cracen_psa_rsa_keygen RSA Key Generation + * @brief RSA key generation operations (internal use only) + */ + +/** + * @defgroup cracen_psa_rsa_encryption RSA Encryption + * @brief RSA encryption and decryption operations (internal use only) + */ + +/** + * @defgroup cracen_psa_rsa_signatures RSA Signatures + * @brief RSA signature operations (internal use only) + * + * This group includes both PKCS#1 v1.5 and PSS signature schemes. + */ + +/** + * @defgroup cracen_psa_eddsa EDDSA Operations + * @brief EDDSA signature and verification operations (internal use only) + */ + +/** + * @defgroup cracen_psa_mac_kdf MAC and KDF Operations + * @brief MAC and Key Derivation Function operations (internal use only) + */ + +/** + * @defgroup cracen_psa_montgomery Montgomery Operations + * @brief Montgomery arithmetic operations (internal use only) + */ + +/** + * @defgroup cracen_psa_ikg Identity Key Generation + * @brief Identity Key Generation (IKG) operations (internal use only) + */ + +/** + * @defgroup cracen_psa_wpa3_sae WPA3 SAE Operations + * @brief WPA3 Simultaneous Authentication of Equals (SAE) operations (internal use only) + */ + +/** @} */ /* cracen_psa_driver_internal */ + +/** + * @defgroup cracen_psa_primitives CRACEN PSA Primitives + * @brief Primitive operations and data structures + * + * @note These primitives are shared between the public driver API and internal + * implementation. + */ + +/** + * @defgroup cracen_psa_key_ids CRACEN Key IDs + * @brief Key ID definitions and constants + * + * @note These key IDs are shared between the public driver API and internal + * implementation. + */ + +/** + * @defgroup cracen_psa_builtin_key_policy CRACEN Built-in Key Policy + * @brief Built-in key policy definitions + * + * @note These definitions are shared between the public driver API and internal + * implementation. + */ + +/** + * @defgroup cracen_psa_kmu CRACEN Key Management Unit (KMU) + * @brief Key Management Unit (KMU) support for CRACEN PSA driver + */ + +/** @} */ /* cracen_psa_driver_apis */ + diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_builtin_key_policy.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_builtin_key_policy.h index 8dbb368bcd03..c5566a432460 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_builtin_key_policy.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_builtin_key_policy.h @@ -4,6 +4,19 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_builtin_key_policy + * @{ + * @brief Built-in key policy definitions for CRACEN PSA driver. + * + * @note These definitions are shared between the public driver API and internal + * implementation. + * + * This module provides definitions and functions for managing built-in key + * policies, shared between the public driver API and internal implementation. + */ + #ifndef CRACEN_PSA_BUILTIN_KEY_POLICY_H #define CRACEN_PSA_BUILTIN_KEY_POLICY_H @@ -12,24 +25,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 +68,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 */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ecdsa.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ecdsa.h index d7e02f28e9d6..dcf70dc60602 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ecdsa.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ecdsa.h @@ -4,36 +4,168 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_ecdsa + * @{ + * @brief ECDSA operations for CRACEN PSA driver (internal use only). + * + * @note These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + * + * @details + * These ECDSA implementation functions expect the following key and signature formats: + * - Public key: Uncompressed format as Qx || Qy + * (2 × curve_op_size bytes, no 0x04 prefix). + * - Private key: Scalar d in big-endian format (curve_op_size bytes), + * wrapped in struct @ref cracen_ecc_priv_key. + * - Signature: Concatenated r || s values in big-endian format + * (2 × curve_op_size bytes total). + * - The curve operation size can be obtained via sx_pk_curve_opsize(). + * - If the provided digest is larger than the curve order size, it is + * truncated, as per FIPS 186-4 DSS requirements. Digests exceeding + * 64 bytes (SHA-512) are rejected. + * + * These ECDSA implementation functions perform minimal input validation for performance, with the following limitations: + * - NULL pointers are not checked and cause undefined behavior. + * - Private key range (1 ≤ d < n) is not validated. + * - Curve (sx_pk_ecurve) and hash algorithm (sxhashalg) pointers are not validated. + * - Output buffer sizes are not validated so undersized buffers cause overflow. + */ + #ifndef CRACEN_PSA_ECDSA_H #define CRACEN_PSA_ECDSA_H #include #include +/** @brief Verify an ECDSA message signature. + * + * @param[in] pubkey Public key. + * @param[in] hashalg Hash algorithm to use for message digesting, given as a sxhashalg struct. + * @param[in] message Message that was signed. + * @param[in] message_length Length of the message in bytes. Can be zero. + * @param[in] curve Elliptic curve parameters. + * @param[in] signature Signature to verify. + * + * @retval 0 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_POINT_NOT_ON_CURVE The public key point is not on the curve. + * @retval ::SX_ERR_OUT_OF_RANGE Signature values r or s are out of valid range. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 signature over a pre-computed digest. + * + * @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 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_POINT_NOT_ON_CURVE The public key point is not on the curve. + * @retval ::SX_ERR_OUT_OF_RANGE Signature values r or s are out of valid range. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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. Can be zero. + * @param[out] signature Buffer to store the signature. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_TOO_MANY_ATTEMPTS Nonce generation failed after maximum + * retry attempts (255). This is extremely rare and may indicate + * issues with the random number generator. + * @retval ::SX_ERR_INSUFFICIENT_ENTROPY Insufficient entropy for random number generation. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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. + * Maximum 64 bytes due to the SHA-512 limit. + * @param[out] signature Buffer to store the signature. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_TOO_BIG The digest length exceeds the maximum supported size (64 bytes). + * @retval ::SX_ERR_TOO_MANY_ATTEMPTS Nonce generation failed after maximum + * retry attempts (255). This is extremely rare and may indicate + * issues with the random number generator. + * @retval ::SX_ERR_INSUFFICIENT_ENTROPY Insufficient entropy for random number generation. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 (RFC 6979). + * + * @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. Can be zero. + * @param[out] signature Buffer to store the signature. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_TOO_MANY_ATTEMPTS Deterministic nonce generation failed after maximum + * retry attempts (255). This should not occur with valid inputs + * and may indicate corrupted key material. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 (RFC 6979). + * + * @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 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_TOO_MANY_ATTEMPTS Deterministic nonce generation failed after maximum + * retry attempts (255). This should not occur with valid inputs + * and may indicate corrupted key material. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_eddsa.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_eddsa.h index 11fab040ebb5..5e91c6363b3d 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_eddsa.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_eddsa.h @@ -4,6 +4,17 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_eddsa + * @{ + * @brief EdDSA operations for CRACEN PSA driver (internal use only). + * + * @note These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + */ + #ifndef CRACEN_PSA_EDDSA_H #define CRACEN_PSA_EDDSA_H @@ -11,32 +22,148 @@ #include #include +/** @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 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 is a hash. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 is a hash. + * + * @retval 0 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 is a hash. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 is a hash. + * + * @retval 0 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ 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 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_ed448_create_pubkey(const uint8_t *priv_key, uint8_t *pub_key); +/** @} */ + #endif /* CRACEN_PSA_EDDSA_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ikg.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ikg.h index 9fdd13592f4e..b488493d03e5 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ikg.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_ikg.h @@ -4,6 +4,20 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_ikg + * @{ + * @brief Identity Key Generation (IKG) support for CRACEN PSA driver (internal use only). + * + * @note These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + * + * This module provides APIs for generating and using identity keys through + * the CRACEN hardware's Identity Key Generation feature. + */ + #ifndef CRACEN_PSA_IKG_H #define CRACEN_PSA_IKG_H @@ -11,14 +25,56 @@ #include #include +/** @brief Sign a message using an identity key. + * + * @param[in] identity_key_index Index of the identity key to use. + * @param[in] hashalg Hash algorithm to use for signing. + * @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 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_IK_NOT_READY The IK module is not ready. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_ikg_sign_message(int identity_key_index, 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 an identity key. + * + * @param[in] identity_key_index Index of the identity key to use. + * @param[in] hashalg Hash algorithm to use for signing. + * @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 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_IK_NOT_READY The IK module is not ready. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_ikg_sign_digest(int identity_key_index, const struct sxhashalg *hashalg, const struct sx_pk_ecurve *curve, const uint8_t *digest, size_t digest_length, uint8_t *signature); +/** @brief Create a public key from an identity key. + * + * @param[in] identity_key_index Index of the identity key to use. + * @param[out] pub_key Buffer to store the public key. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_IK_NOT_READY The IK module is not ready. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_ikg_create_pub_key(int identity_key_index, uint8_t *pub_key); +/** @} */ + #endif /* CRACEN_PSA_IKG_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_key_ids.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_key_ids.h index f348df839402..6f9f3c04ac1c 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_key_ids.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_key_ids.h @@ -4,27 +4,52 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_key_ids + * @{ + * @brief Key ID definitions for CRACEN PSA driver. + * + * @note These key IDs are shared between the public driver API and internal + * implementation. + * + * This module provides key ID definitions and constants, shared between the + * public driver API and internal implementation. + */ + #ifndef CRACEN_PSA_KEY_IDS_H #define CRACEN_PSA_KEY_IDS_H +/** @brief Built-in identity key ID. */ #define CRACEN_BUILTIN_IDENTITY_KEY_ID ((uint32_t)0x7fffc001) + +/** @brief Built-in MKEK (Master Key Encryption Key) ID. */ #define CRACEN_BUILTIN_MKEK_ID ((uint32_t)0x7fffc002) + +/** @brief Built-in MEXT (Master External Key) ID. */ #define CRACEN_BUILTIN_MEXT_ID ((uint32_t)0x7fffc003) +/** @brief Protected RAM AES key 0 ID. */ #define CRACEN_PROTECTED_RAM_AES_KEY0_ID ((uint32_t)0x7fffc004) +/** @brief Key location identifier for CRACEN. */ #define PSA_KEY_LOCATION_CRACEN ((psa_key_location_t)(0x800000 | ('N' << 8))) -/* +/** @brief Key persistence state: revokable. + * * Defines a persistence state where deleted keys are permanently revoked. - * In this state, once a key is deleted, its corresponding slot cannot be provisioned again. + * In this state, once a key is deleted, its corresponding slot cannot be + * provisioned again. */ #define CRACEN_KEY_PERSISTENCE_REVOKABLE 0x02 -/* - * Defines a persistence state where the key can't be erased - * In this state the key will only be erased if ERASEALL is available and run +/** @brief Key persistence state: read-only. + * + * Defines a persistence state where the key can't be erased. + * In this state the key will only be erased if ERASEALL is available and run. */ - #define CRACEN_KEY_PERSISTENCE_READ_ONLY 0x03 +#define CRACEN_KEY_PERSISTENCE_READ_ONLY 0x03 + +/** @} */ #endif diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_kmu.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_kmu.h index 0205ecdd2008..a0a8729175b9 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_kmu.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_kmu.h @@ -4,73 +4,131 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_kmu + * @{ + * @brief Key Management Unit (KMU) support for CRACEN PSA driver. + * + * This module provides APIs and macros for managing keys stored in the KMU + * hardware peripheral, including key slot management, key usage schemes, and + * key blocking operations. + * + * @note Applications should use the PSA Crypto API (psa_* functions) instead + * of calling these driver functions directly. This header documents the + * KMU driver implementation that is called by the PSA Crypto layer. + */ + #ifndef CRACEN_PSA_KMU_H #define CRACEN_PSA_KMU_H #include #ifdef CONFIG_BUILD_WITH_TFM -/** A slot number identifying a key in a driver. +/** @brief A slot number identifying a key in a driver. * * Values of this type are used to identify built-in keys. */ typedef uint64_t psa_drv_slot_number_t; #endif +/** @brief Key location identifier for CRACEN KMU. + * + * This macro defines the PSA key location value for keys stored in the CRACEN + * KMU hardware peripheral. + */ #define PSA_KEY_LOCATION_CRACEN_KMU (PSA_KEY_LOCATION_VENDOR_FLAG | ('N' << 8) | 'K') -/* Key id 0x7fffXYZZ */ -/* X: Key usage scheme */ -/* Y: Reserved (0) */ -/* Z: KMU Slot index */ - -/* Construct a PSA Key handle for key stored in KMU */ +/** @brief Construct a PSA key handle for a key stored in KMU. + * + * The key ID format is 0x7fffXYZZ where: + * - X: Key usage scheme (4 bits) + * - Y: Reserved (0) + * - Z: KMU slot index (8 bits) + * + * @param[in] scheme Key usage scheme from @ref cracen_kmu_metadata_key_usage_scheme. + * @param[in] slot_id KMU slot index (0-255). + * + * @return PSA key handle value. + */ #define PSA_KEY_HANDLE_FROM_CRACEN_KMU_SLOT(scheme, slot_id) \ (0x7fff0000 | ((scheme) << 12) | ((slot_id)&0xff)) -/* Retrieve key usage scheme from PSA key id. */ +/** @brief Retrieve key usage scheme from PSA key ID. + * + * @param[in] key_id PSA key ID. + * + * @return Key usage scheme value (0-15). + */ #define CRACEN_PSA_GET_KEY_USAGE_SCHEME(key_id) (((key_id) >> 12) & 0xf) -/* Retrieve KMU slot number for PSA key id. */ +/** @brief Retrieve KMU slot number from PSA key ID. + * + * @param[in] key_id PSA key ID. + * + * @return KMU slot number (0-255). + */ #define CRACEN_PSA_GET_KMU_SLOT(key_id) ((key_id)&0xff) +/** @brief Key usage schemes for KMU metadata. + * + * Defines how keys stored in KMU are handled and used by the CRACEN driver. + */ enum cracen_kmu_metadata_key_usage_scheme { - /** - * These keys can only be pushed to CRACEN's protected RAM. - * The keys are not encrypted. Only AES supported. + /** Keys can only be pushed to CRACEN's protected RAM. + * + * The keys are not encrypted. Only AES is supported. */ CRACEN_KMU_KEY_USAGE_SCHEME_PROTECTED, - /** - * CRACEN's IKG seed uses 3 key slots. Pushed to the seed register. + + /** CRACEN's IKG seed uses 3 key slots. + * + * Pushed to the seed register. */ CRACEN_KMU_KEY_USAGE_SCHEME_SEED, - /** - * These keys are stored in encrypted form. They will be decrypted - * to @ref kmu_push_area for usage. + + /** Keys are stored in encrypted form. + * + * They will be decrypted to the KMU push area for usage. */ CRACEN_KMU_KEY_USAGE_SCHEME_ENCRYPTED, - /** - * These keys are not encrypted. Pushed to @ref kmu_push_area. + + /** Keys are not encrypted. + * + * Pushed to the KMU push area. */ CRACEN_KMU_KEY_USAGE_SCHEME_RAW }; -/** Retrieves the slot number for a given key handle. +/** @brief Retrieve the slot number for a given key handle. * - * @param[in] key_id Key handler. - * @param[out] lifetime Lifetime for key. + * @param[in] key_id Key handle identifier. + * @param[out] lifetime Lifetime for the key. * @param[out] slot_number The key's slot number. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_DOES_NOT_EXIST The key does not exist. */ psa_status_t cracen_kmu_get_key_slot(mbedtls_svc_key_id_t key_id, psa_key_lifetime_t *lifetime, psa_drv_slot_number_t *slot_number); -/** Blocks a key in the KMU. +/** @brief Block a key in the KMU. + * + * This function blocks a key stored in KMU, preventing its use in cryptographic + * operations. * * @param[in] key_attr Attributes of the key to block. * - * @note The underlying operation performed is a `BLOCK` on devices - * that support it, and a `PUSHBLOCK` on those that don't. + * @note The underlying operation performed is a `BLOCK` on devices that support + * it, and a `PUSHBLOCK` on those that don't. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_INVALID_HANDLE The key handle is invalid. + * @retval PSA_ERROR_DOES_NOT_EXIST The key does not exist. */ psa_status_t cracen_kmu_block(const psa_key_attributes_t *key_attr); +/** @} */ + #endif /* CRACEN_PSA_KMU_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_mac_kdf.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_mac_kdf.h index 36f7b6c5cf83..7ef59a84d227 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_mac_kdf.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_mac_kdf.h @@ -4,14 +4,29 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_mac_kdf + * @{ + * @brief MAC and KDF definitions for CRACEN PSA driver (internal use only). + * + * @note These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + */ + #ifndef CRACEN_PSA_MAC_KDF_H #define CRACEN_PSA_MAC_KDF_H -/* The defines will eventually become part of the PSA core once the - * spec is finalized and the core is updated +/** @brief SP800-108 Counter MAC initial capacity. + * + * The defines will eventually become part of the PSA core once the spec is + * finalized and the core is updated. + * + * Value: 2^29 - 1 */ - -/* 2^29 -1 */ #define PSA_ALG_SP800_108_COUNTER_MAC_INIT_CAPACITY (0x1fffffff) +/** @} */ + #endif /* CRACEN_PSA_MAC_KDF_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_montgomery.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_montgomery.h index 293576eebfdf..e14de6087fb5 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_montgomery.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_montgomery.h @@ -4,13 +4,44 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_montgomery + * @{ + * @brief Montgomery curve operations for CRACEN PSA driver (internal use only). + * + * @note These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + */ + #ifndef CRACEN_PSA_MONTGOMERY_H #define CRACEN_PSA_MONTGOMERY_H #include +/** @brief Generate an X448 public key from a private key. + * + * @param[in] priv_key Private key. + * @param[out] pub_key Buffer to store the public key. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_x448_genpubkey(const uint8_t *priv_key, uint8_t *pub_key); +/** @brief Generate an X25519 public key from a private key. + * + * @param[in] priv_key Private key. + * @param[out] pub_key Buffer to store the public key. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_x25519_genpubkey(const uint8_t *priv_key, uint8_t *pub_key); +/** @} */ + #endif /* CRACEN_PSA_MONTGOMERY_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_primitives.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_primitives.h index 2dcc951aca50..b69d63344934 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_primitives.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_primitives.h @@ -4,6 +4,21 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_primitives + * @{ + * @brief Primitive operations and data structures for CRACEN PSA driver. + * + * @note These primitives are shared between the public driver API and internal + * implementation. + * + * This module provides primitive data structures and constants, shared between + * the public driver API and internal implementation. + * + * Unless otherwise specified, all size and length defines are in bytes. + */ + #ifndef CRACEN_PSA_PRIMITIVES_H #define CRACEN_PSA_PRIMITIVES_H @@ -22,80 +37,133 @@ #define SX_BLKCIPHER_AES_BLK_SZ (16U) #if defined(PSA_NEED_CRACEN_STREAM_CIPHER_CHACHA20) -/* ChaCha20 has a 512 bit block size */ +/** Maximum block cipher block size. + * + * ChaCha20 has a 512-bit block size. + */ #define SX_BLKCIPHER_MAX_BLK_SZ (64U) #else #define SX_BLKCIPHER_MAX_BLK_SZ SX_BLKCIPHER_AES_BLK_SZ #endif #define CRACEN_MAX_AES_KEY_SIZE (32u) - #define CRACEN_MAX_AEAD_BLOCK_SIZE (64u) -/* - * Cracen AEAD uses two backends, BA411 for GCM/CCM and BA417 for - * ChaChaPoly. And they both have 32 bytes as the max key size. + +/** Maximum AEAD key size. + * + * CRACEN AEAD uses two backends, BA411 for GCM/CCM and BA417 for + * ChaChaPoly. Both have 32 bytes as the max key size. */ #define CRACEN_MAX_AEAD_KEY_SIZE (32u) -/* +/** Maximum ChaCha20 key size. + * * The low level driver only supports a key size of exactly 32 bytes for - * CHACHA20 (and for CHACHAPOLY for that sake). + * CHACHA20 (and for CHACHAPOLY). */ #define CRACEN_MAX_CHACHA20_KEY_SIZE (32u) -/* +/** Maximum cipher key size. + * * There are two key types supported for ciphers, CHACHA20 and AES, * and they both have a max key size of 32. */ #define CRACEN_MAX_CIPHER_KEY_SIZE (32u) -/* Max length of PBKDF2 salt. There is no set max length. - * For this implementation max length is set 128 bytes. +/** Maximum length of PBKDF2 salt. + * + * There is no set max length. For this implementation max length is set + * to 128 bytes. */ #define CRACEN_PBKDF_MAX_SALT_SIZE 128 -/* Max length for HKDF info input. The input is optional and has no set max - * length. For this implementation max length is set 128 bytes. +/** Maximum length for HKDF info input. + * + * The input is optional and has no set max length. For this implementation + * max length is set to 128 bytes. */ #define CRACEN_HKDF_MAX_INFO_SIZE 128 #define CRACEN_MAC_MAX_LABEL_SIZE 127 - #define CRACEN_MAC_MAX_CONTEXT_SIZE 64 - #define CRACEN_JPAKE_USER_ID_MAX_SIZE 16 - #define CRACEN_P256_KEY_SIZE 32 #define CRACEN_P256_POINT_SIZE 64 - #define CRACEN_TLS12_PRF_MAX_LABEL_SIZE 128 #define CRACEN_TLS12_PRF_MAX_SEED_SIZE 128 -#define CRACEN_PRNG_KEY_SIZE (32u) /* Key size to get 256 bits of security */ -#define CRACEN_PRNG_ENTROPY_SIZE (48u) /* Seed equals key-len + 16 */ -#define CRACEN_PRNG_NONCE_SIZE (0u) /* Not supported for CTR_DRBG */ -#define CRACEN_PRNG_PERSONALIZATION_MAX_SIZE (48u) /* Max Equal to SEED size */ -#define CRACEN_PRNG_WORKMEM_SIZE (176u) /* KeyLen + AES block len + XORBUF_SZ (128) */ -#define CRACEN_PRNG_MAX_REQUEST_SIZE (1u << 16) /* Max request. See NIST specification */ +/** PRNG key size. + * + * Key size to get 256 bits of security. + */ +#define CRACEN_PRNG_KEY_SIZE (32u) + +/** PRNG entropy size. + * + * Seed equals key length plus 16 bytes. + */ +#define CRACEN_PRNG_ENTROPY_SIZE (48u) + +/** PRNG nonce size. + * + * Not supported for CTR_DRBG. + */ +#define CRACEN_PRNG_NONCE_SIZE (0u) + +/** Maximum PRNG personalization size. + * + * Maximum equals the seed size. + */ +#define CRACEN_PRNG_PERSONALIZATION_MAX_SIZE (48u) + +/** PRNG working memory size. + * + * Key length plus AES block length plus XORBUF_SZ (128). + */ +#define CRACEN_PRNG_WORKMEM_SIZE (176u) + +/** Maximum PRNG request size. + * + * Maximum request size. See NIST specification. + */ +#define CRACEN_PRNG_MAX_REQUEST_SIZE (1u << 16) #define CRACEN_SPAKE2P_HASH_LEN PSA_HASH_LENGTH(PSA_ALG_SHA_256) #define CRACEN_WPA3_SAE_MAX_SSID_LEN (32u) #define CRACEN_WPA3_SAE_MAX_PWD_LEN (256u) #define CRACEN_WPA3_SAE_MAX_PWID_LEN (256u) -#define CRACEN_WPA3_SAE_PMK_LEN (32u) /* According to IEEE802.11-2024, 12.7.1.3 */ + +/** WPA3 SAE PMK (Pairwise Master Key) length. + * + * According to IEEE802.11-2024, 12.7.1.3. + */ +#define CRACEN_WPA3_SAE_PMK_LEN (32u) + #define CRACEN_WPA3_SAE_PMKID_SIZE (16u) #define CRACEN_WPA3_SAE_STA_ID_LEN (6u) -/** IANA group to identify the elliptic curve. - * See IEEE802.11-2024, Table 12-2 + +/** WPA3 SAE IANA group size. + * + * IANA group to identify the elliptic curve. + * See IEEE802.11-2024, Table 12-2. */ #define CRACEN_WPA3_SAE_IANA_GROUP_SIZE (2u) + +/** WPA3 SAE commit message size. + * + * Size includes IANA group size, P-256 key size, and P-256 point size. + */ #define CRACEN_WPA3_SAE_COMMIT_SIZE (CRACEN_WPA3_SAE_IANA_GROUP_SIZE + \ CRACEN_P256_KEY_SIZE + \ CRACEN_P256_POINT_SIZE) -/* Send-confirm counter size */ #define CRACEN_WPA3_SAE_SEND_CONFIRM_SIZE (2u) + +/** WPA3 SAE confirm message size. + * + * Size includes send-confirm counter size plus hash length. + */ #define CRACEN_WPA3_SAE_CONFIRM_SIZE (CRACEN_WPA3_SAE_SEND_CONFIRM_SIZE + \ PSA_HASH_LENGTH(PSA_ALG_SHA_256)) @@ -104,6 +172,7 @@ enum cipher_operation { CRACEN_ENCRYPT }; +/** Key derivation state machine states. */ enum cracen_kd_state { CRACEN_KD_STATE_INVALID = 0, @@ -146,8 +215,11 @@ enum cracen_kd_state { CRACEN_KD_STATE_WPA3_SAE_H2E_OUTPUT, }; -/* States to keep track of when the AEAD sxsymcrypt context has been initialized with xxx_create and - * when the hardware is reserved with a xxx_resume call. +/** CRACEN context state. + * + * States to keep track of when the AEAD sxsymcrypt context has been + * initialized with xxx_create and when the hardware is reserved with a + * xxx_resume call. */ enum cracen_context_state { CRACEN_NOT_INITIALIZED = 0x0, @@ -155,27 +227,27 @@ enum cracen_context_state { CRACEN_HW_RESERVED = 0x2 }; +/** Hash operation context. */ struct cracen_hash_operation_s { const struct sxhashalg *sx_hash_algo; - /* Internal sxcrypto context */ + /* Internal sxcrypto context. */ struct sxhash sx_ctx; - /* The driver can perform a processing round after getting a multiple of - * the blocksize. - * Therefore we have to know how much much data is left to fill up to - * the next block + /* The driver can perform a processing round after getting a multiple of the blocksize. + * Therefore we have to know how much data is left to fill up to the next block. */ size_t bytes_left_for_next_block; - /* Buffer for input data to fill up the next block */ + /* Buffer for input data to fill up the next block. */ uint8_t input_buffer[SX_HASH_MAX_ENABLED_BLOCK_SIZE]; - /* Flag to know if the Hashing has already started */ + /* Flag to know if the hashing has already started. */ bool is_first_block; }; typedef struct cracen_hash_operation_s cracen_hash_operation_t; +/** Cipher operation context. */ struct cracen_cipher_operation { psa_algorithm_t alg; struct sxblkcipher cipher; @@ -190,20 +262,22 @@ struct cracen_cipher_operation { }; typedef struct cracen_cipher_operation cracen_cipher_operation_t; +/** Software CCM context for workarounds. */ struct cracen_sw_ccm_context_s { - uint8_t cbc_mac[SX_BLKCIPHER_AES_BLK_SZ]; /* CBC-MAC state */ - uint8_t ctr_block[SX_BLKCIPHER_AES_BLK_SZ]; /* Counter block for CTR mode */ - uint8_t keystream[SX_BLKCIPHER_AES_BLK_SZ]; /* Generated keystream */ - uint8_t partial_block[SX_BLKCIPHER_AES_BLK_SZ]; /* Buffer for partial blocks */ - size_t keystream_offset; /* Position in keystream buffer */ - size_t total_ad_fed; /* Total AD bytes processed */ - size_t data_partial_len; /* Partial data block length */ - bool cbc_mac_initialized; /* CBC-MAC initialization flag */ - bool ctr_initialized; /* CTR initialization flag */ - bool has_partial_ad_block; /* Partial AD block flag */ + uint8_t cbc_mac[SX_BLKCIPHER_AES_BLK_SZ]; /* CBC-MAC state. */ + uint8_t ctr_block[SX_BLKCIPHER_AES_BLK_SZ]; /* Counter block for CTR mode. */ + uint8_t keystream[SX_BLKCIPHER_AES_BLK_SZ]; /* Generated keystream. */ + uint8_t partial_block[SX_BLKCIPHER_AES_BLK_SZ]; /* Buffer for partial blocks. */ + size_t keystream_offset; /* Position in keystream buffer. */ + size_t total_ad_fed; /* Total AD bytes processed. */ + size_t data_partial_len; /* Partial data block length. */ + bool cbc_mac_initialized; /* CBC-MAC initialization flag. */ + bool ctr_initialized; /* CTR initialization flag. */ + bool has_partial_ad_block; /* Partial AD block flag. */ }; typedef struct cracen_sw_ccm_context_s cracen_sw_ccm_context_t; +/** AEAD operation context. */ struct cracen_aead_operation { psa_algorithm_t alg; struct sxkeyref keyref; @@ -225,26 +299,26 @@ struct cracen_aead_operation { }; typedef struct cracen_aead_operation cracen_aead_operation_t; +/** CMAC context for multipart workarounds. */ struct cracen_cmac_context_s { - uint8_t mac_state[SX_BLKCIPHER_AES_BLK_SZ]; /* The current MAC state */ + uint8_t mac_state[SX_BLKCIPHER_AES_BLK_SZ]; /* Current MAC state. */ uint8_t partial_block[SX_BLKCIPHER_AES_BLK_SZ]; size_t partial_len; - size_t processed_len; /* Total length of data processed so far (in bytes) */ + size_t processed_len; /* Total length of data processed so far, in bytes. */ }; typedef struct cracen_cmac_context_s cracen_cmac_context_t; +/** MAC operation context. */ struct cracen_mac_operation_s { psa_algorithm_t alg; size_t mac_size; - /* The driver can perform a processing round after getting a multiple of - * the blocksize. - * Therefore we have to know how much much data is left to fill up to - * the next block + /* The driver can perform a processing round after getting a multiple of the blocksize. + * Therefore we have to know how much data is left to fill up to the next block. */ size_t bytes_left_for_next_block; - /* Buffer for input data to fill up the next block */ + /* Buffer for input data to fill up the next block. */ uint8_t input_buffer[SX_MAX(SX_HASH_MAX_ENABLED_BLOCK_SIZE, SX_BLKCIPHER_PRIV_SZ)]; bool is_first_block; @@ -272,6 +346,7 @@ struct cracen_mac_operation_s { }; typedef struct cracen_mac_operation_s cracen_mac_operation_t; +/** Key derivation operation context. */ struct cracen_key_derivation_operation { psa_algorithm_t alg; enum cracen_kd_state state; @@ -316,8 +391,8 @@ struct cracen_key_derivation_operation { uint8_t K_0[SX_BLKCIPHER_AES_BLK_SZ]; #endif /* PSA_NEED_CRACEN_SP800_108_COUNTER_CMAC */ uint32_t counter; - /* The +1 here is meant to store an algorithm specific byte needed after the - * label + /* The +1 here is meant to store an algorithm-specific byte needed after + * the label. */ uint8_t label[CRACEN_MAC_MAX_LABEL_SIZE + 1]; size_t label_length; @@ -333,8 +408,8 @@ struct cracen_key_derivation_operation { #endif /* PSA_NEED_CRACEN_TLS12_ECJPAKE_TO_PMS */ #if defined(PSA_NEED_CRACEN_TLS12_PRF) || defined(PSA_NEED_CRACEN_TLS12_PSK_TO_MS) struct { - /* May contain secret, length of secret as uint16be, other secret - * and other secret length as uint16be. + /* May contain secret, length of secret as uint16be, other secret and + * other secret length as uint16be. */ uint8_t secret[PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE * 2 + 4]; size_t secret_length; @@ -350,25 +425,26 @@ struct cracen_key_derivation_operation { }; typedef struct cracen_key_derivation_operation cracen_key_derivation_operation_t; +/** JPAKE operation context. */ struct cracen_jpake_operation { - psa_algorithm_t alg; /* Hashing algorithm. */ - uint8_t secret[CRACEN_P256_KEY_SIZE]; /* A secret value derived from the password. */ + psa_algorithm_t alg; /* Hashing algorithm. */ + uint8_t secret[CRACEN_P256_KEY_SIZE]; /* Secret value derived from the password. */ uint8_t user_id[CRACEN_JPAKE_USER_ID_MAX_SIZE]; uint8_t peer_id[CRACEN_JPAKE_USER_ID_MAX_SIZE]; size_t user_id_length; size_t peer_id_length; uint8_t rd_idx; uint8_t wr_idx; - uint8_t x[3][CRACEN_P256_KEY_SIZE]; /* private keys */ - uint8_t X[3][CRACEN_P256_POINT_SIZE]; /* public keys */ - uint8_t P[3][CRACEN_P256_POINT_SIZE]; /* peer keys */ + uint8_t x[3][CRACEN_P256_KEY_SIZE]; /* Private keys. */ + uint8_t X[3][CRACEN_P256_POINT_SIZE]; /* Public keys. */ + uint8_t P[3][CRACEN_P256_POINT_SIZE]; /* Peer keys. */ uint8_t V[CRACEN_P256_POINT_SIZE]; uint8_t r[CRACEN_P256_KEY_SIZE]; const struct sx_pk_ecurve *curve; }; typedef struct cracen_jpake_operation cracen_jpake_operation_t; -/** @brief Structure type for PRNG context */ +/** PRNG context. */ struct cracen_prng_context { uint8_t key[CRACEN_PRNG_KEY_SIZE]; uint8_t V[SX_BLKCIPHER_AES_BLK_SZ]; @@ -379,38 +455,47 @@ typedef struct cracen_prng_context cracen_prng_context_t; #define CRACEN_SRP_HASH_ALG PSA_ALG_SHA_512 #define CRACEN_SRP_HASH_LENGTH PSA_HASH_LENGTH(CRACEN_SRP_HASH_ALG) +/** SRP RFC3526 key size in bits. */ #define CRACEN_SRP_RFC3526_KEY_BITS_SIZE 3072 #define CRACEN_SRP_FIELD_SIZE PSA_BITS_TO_BYTES(CRACEN_SRP_RFC3526_KEY_BITS_SIZE) -/* The same number that Oberon PSA driver use to align the implementations */ + +/** Maximum SRP salt length. + * + * The same number that Oberon PSA driver uses to align the implementations. + */ #define CRACEN_SRP_MAX_SALT_LENGTH 64 +/** SRP operation context. */ struct cracen_srp_operation { - psa_pake_role_t role; /* Protocol role */ - uint8_t user_hash[CRACEN_SRP_HASH_LENGTH]; /* Hash of the username */ - uint8_t salt[CRACEN_SRP_MAX_SALT_LENGTH]; /* salt chosen by server */ - size_t salt_len; /* length of salt */ + psa_pake_role_t role; /* Protocol role. */ + uint8_t user_hash[CRACEN_SRP_HASH_LENGTH]; /* Hash of the username. */ + uint8_t salt[CRACEN_SRP_MAX_SALT_LENGTH]; /* Salt chosen by server. */ + size_t salt_len; /* Length of salt. */ union { - uint8_t x[CRACEN_SRP_HASH_LENGTH]; /* x = SHA512(salt | SHA512(user | ":" | pass)) - */ - uint8_t v[CRACEN_SRP_FIELD_SIZE]; /* v = g^x mod N */ + /* x = SHA512(salt | SHA512(user | ":" | pass)). */ + uint8_t x[CRACEN_SRP_HASH_LENGTH]; + uint8_t v[CRACEN_SRP_FIELD_SIZE]; /* v = g^x mod N. */ }; - uint8_t ab[32]; /* random a for client, b for server*/ - uint8_t A[CRACEN_SRP_FIELD_SIZE]; /* (v + g^b) mod N */ - uint8_t B[CRACEN_SRP_FIELD_SIZE]; /* g^a mod N */ + uint8_t ab[32]; /* Random a for client, b for server. */ + uint8_t A[CRACEN_SRP_FIELD_SIZE]; /* (v + g^b) mod N. */ + uint8_t B[CRACEN_SRP_FIELD_SIZE]; /* g^a mod N. */ - uint8_t M[CRACEN_SRP_HASH_LENGTH]; /* H(H(N) xor H(g) | H(U) | salt | A | B | K ) */ - uint8_t K[CRACEN_SRP_HASH_LENGTH]; /* shared key k= H_Interleaved(S) */ + uint8_t M[CRACEN_SRP_HASH_LENGTH]; /* H(H(N) xor H(g) | H(U) | salt | A | B | K). */ + uint8_t K[CRACEN_SRP_HASH_LENGTH]; /* Shared key k = H_Interleaved(S). */ }; typedef struct cracen_srp_operation cracen_srp_operation_t; +/** SPAKE2+ operation context. */ struct cracen_spake2p_operation { psa_algorithm_t alg; - cracen_hash_operation_t hash_op; /* Protocol transcript (TT) */ + cracen_hash_operation_t hash_op; /* Protocol transcript (TT). */ uint8_t w0[CRACEN_P256_KEY_SIZE]; uint8_t w1_or_L[CRACEN_P256_POINT_SIZE]; /* w1 is scalar, L is a point. */ uint8_t xy[CRACEN_P256_KEY_SIZE]; - uint8_t XY[CRACEN_P256_POINT_SIZE + 1]; /* Includes prefix for uncompressed points (0x04) */ - uint8_t YX[CRACEN_P256_POINT_SIZE + 1]; /* Includes prefix for uncompressed points (0x04) */ + /* Includes prefix for uncompressed points (0x04). */ + uint8_t XY[CRACEN_P256_POINT_SIZE + 1]; + /* Includes prefix for uncompressed points (0x04). */ + uint8_t YX[CRACEN_P256_POINT_SIZE + 1]; uint8_t shared[CRACEN_SPAKE2P_HASH_LEN]; uint8_t shared_len; uint8_t KconfPV[CRACEN_SPAKE2P_HASH_LEN]; @@ -426,6 +511,7 @@ struct cracen_spake2p_operation { }; typedef struct cracen_spake2p_operation cracen_spake2p_operation_t; +/** WPA3 SAE operation context. */ struct cracen_wpa3_sae_operation { cracen_mac_operation_t mac_op; psa_algorithm_t hash_alg; @@ -455,6 +541,7 @@ struct cracen_wpa3_sae_operation { }; typedef struct cracen_wpa3_sae_operation cracen_wpa3_sae_operation_t; +/** PAKE operation context. */ struct cracen_pake_operation { psa_algorithm_t alg; union { @@ -475,34 +562,40 @@ struct cracen_pake_operation { }; typedef struct cracen_pake_operation cracen_pake_operation_t; +/** ECC signature representation. */ struct cracen_signature { size_t sz; /** Total signature size, in bytes. */ uint8_t *r; /** Signature element "r". */ uint8_t *s; /** Signature element "s". */ }; +/** ECC signature representation with const pointers. */ struct cracen_const_signature { size_t sz; /** Total signature size, in bytes. */ const uint8_t *r; /** Signature element "r". */ const uint8_t *s; /** Signature element "s". */ }; +/** ECC private key representation. */ struct cracen_ecc_priv_key { const struct sx_pk_ecurve *curve; - const uint8_t *d; /** Private key value d */ + const uint8_t *d; /** Private key value d. */ }; +/** ECC public key representation. */ struct cracen_ecc_pub_key { const struct sx_pk_ecurve *curve; - uint8_t *qx; /** x coordinate of a point on the curve */ - uint8_t *qy; /** y coordinate of a point on the curve */ + uint8_t *qx; /** x coordinate of a point on the curve. */ + uint8_t *qy; /** y coordinate of a point on the curve. */ }; +/** ECC key pair representation. */ struct cracen_ecc_keypair { struct cracen_ecc_priv_key priv_key; struct cracen_ecc_pub_key pub_key; }; +/** RSA key representation. */ struct cracen_rsa_key { const struct sx_pk_cmd_def *cmd; unsigned int slotmask; @@ -520,6 +613,7 @@ struct cracen_crypt_text { size_t sz; }; +/** Coprime check parameters. */ struct cracen_coprimecheck { const uint8_t *a; size_t asz; @@ -527,6 +621,7 @@ struct cracen_coprimecheck { size_t bsz; }; +/** RSA prime check parameters. */ struct cracen_rsacheckpq { const uint8_t *pubexp; size_t pubexpsz; @@ -536,6 +631,7 @@ struct cracen_rsacheckpq { size_t mrrounds; }; +/** RSA prime generation parameters. */ struct cracen_rsagenpq { const uint8_t *pubexp; size_t pubexpsz; @@ -547,4 +643,6 @@ struct cracen_rsagenpq { size_t attempts; }; +/** @} */ + #endif /* CRACEN_PSA_PRIMITIVES_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_encryption.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_encryption.h index 10adb6cb02ad..f7e45667f258 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_encryption.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_encryption.h @@ -4,23 +4,96 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_rsa_encryption + * @{ + * @brief RSA encryption operations for CRACEN PSA driver (internal use only). + * + * @note These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + */ + #ifndef CRACEN_PSA_RSA_ENCRYPTION_H #define CRACEN_PSA_RSA_ENCRYPTION_H #include "cracen_psa_primitives.h" +/** @brief Encrypt data using RSA OAEP. + * + * @param[in] hashalg Hash algorithm. + * @param[in] rsa_key RSA key structure. + * @param[in] text Text to encrypt. + * @param[in] label Optional label. + * @param[out] output Buffer to store the ciphertext. + * @param[in,out] output_length On input, size of the output buffer in bytes. + * On output, length of the generated ciphertext. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_OUTPUT_BUFFER_TOO_SMALL The output buffer is too small. + * @retval ::SX_ERR_INVALID_CIPHERTEXT The input plaintext is too large for the key size. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_oaep_encrypt(const struct sxhashalg *hashalg, struct cracen_rsa_key *rsa_key, struct cracen_crypt_text *text, struct sx_const_buf *label, uint8_t *output, size_t *output_length); +/** @brief Decrypt data using RSA OAEP. + * + * @param[in] hashalg Hash algorithm. + * @param[in] rsa_key RSA key structure. + * @param[in] text Ciphertext to decrypt. + * @param[in] label Optional label. + * @param[out] output Buffer to store the plaintext. + * @param[in,out] output_length On input, size of the output buffer in bytes. + * On output, length of the decrypted plaintext. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_OUTPUT_BUFFER_TOO_SMALL The output buffer is too small. + * @retval ::SX_ERR_INVALID_CIPHERTEXT The ciphertext is invalid or decryption failed. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_oaep_decrypt(const struct sxhashalg *hashalg, struct cracen_rsa_key *rsa_key, struct cracen_crypt_text *text, struct sx_const_buf *label, uint8_t *output, size_t *output_length); +/** @brief Decrypt data using RSA PKCS#1 v1.5. + * + * @param[in] rsa_key RSA key structure. + * @param[in] text Ciphertext to decrypt. + * @param[out] output Buffer to store the plaintext. + * @param[in,out] output_length On input, size of the output buffer in bytes. + * On output, length of the decrypted plaintext. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_OUTPUT_BUFFER_TOO_SMALL The output buffer is too small. + * @retval ::SX_ERR_INVALID_CIPHERTEXT The ciphertext is invalid or decryption failed. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pkcs1v15_decrypt(struct cracen_rsa_key *rsa_key, struct cracen_crypt_text *text, uint8_t *output, size_t *output_length); +/** @brief Encrypt data using RSA PKCS#1 v1.5. + * + * @param[in] rsa_key RSA key structure. + * @param[in] text Plaintext to encrypt. + * @param[out] output Buffer to store the ciphertext. + * @param[in,out] output_length On input, size of the output buffer in bytes. + * On output, length of the generated ciphertext. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_OUTPUT_BUFFER_TOO_SMALL The output buffer is too small. + * @retval ::SX_ERR_INVALID_CIPHERTEXT The input plaintext is too large for the key size. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pkcs1v15_encrypt(struct cracen_rsa_key *rsa_key, struct cracen_crypt_text *text, uint8_t *output, size_t *output_length); +/** @} */ + #endif /* CRACEN_PSA_RSA_ENCRYPTION_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_keygen.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_keygen.h index f139778db7dd..5bd2ede26c80 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_keygen.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_keygen.h @@ -4,16 +4,41 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_rsa_keygen + * @{ + * @brief RSA key generation for CRACEN PSA driver (internal use only). + * + * @warning These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + */ + #ifndef CRACEN_PSA_RSA_KEYGEN_H #define CRACEN_PSA_RSA_KEYGEN_H #include #include -/* - * Generate an RSA private key, based on FIPS 186-4. +/** @brief Generate an RSA private key. + * + * Generates an RSA private key based on FIPS 186-4. + * + * @param[in] pubexp Public exponent. + * @param[in] pubexpsz Size of the public exponent in bytes. + * @param[in] keysz Key size in bits. + * @param[out] privkey Generated private key structure. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_INSUFFICIENT_ENTROPY Insufficient entropy for prime generation. + * @retval ::SX_ERR_TOO_MANY_ATTEMPTS Too many attempts to generate valid primes. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. */ int cracen_rsa_generate_privkey(uint8_t *pubexp, size_t pubexpsz, size_t keysz, struct cracen_rsa_key *privkey); +/** @} */ + #endif /* CRACEN_PSA_RSA_KEYGEN_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_signature_pkcs1v15.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_signature_pkcs1v15.h index 17bff4ae2e2e..02713e37844b 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_signature_pkcs1v15.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_signature_pkcs1v15.h @@ -4,29 +4,96 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_rsa_signatures + * @{ + * @brief RSA PKCS#1 v1.5 signature operations for CRACEN PSA driver (internal use only). + * + * @warning These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + */ + #ifndef CRACEN_PSA_RSA_SIGNATURE_PKCS1V15_H #define CRACEN_PSA_RSA_SIGNATURE_PKCS1V15_H #include +/** @brief Sign a message using RSA PKCS#1 v1.5. + * + * @param[in] rsa_key RSA key structure. + * @param[out] signature Signature structure to populate. + * @param[in] hashalg Hash algorithm. + * @param[in] message Message to sign. + * @param[in] message_length Length of the message in bytes. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pkcs1v15_sign_message(struct cracen_rsa_key *rsa_key, struct cracen_signature *signature, const struct sxhashalg *hashalg, const uint8_t *message, size_t message_length); +/** @brief Sign a digest using RSA PKCS#1 v1.5. + * + * @param[in] rsa_key RSA key structure. + * @param[out] signature Signature structure to populate. + * @param[in] hashalg Hash algorithm. + * @param[in] digest Digest to sign. + * @param[in] digest_length Length of the digest in bytes. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pkcs1v15_sign_digest(struct cracen_rsa_key *rsa_key, struct cracen_signature *signature, const struct sxhashalg *hashalg, const uint8_t *digest, size_t digest_length); +/** @brief Verify a message signature using RSA PKCS#1 v1.5. + * + * @param[in] rsa_key RSA key structure. + * @param[in] signature Signature to verify. + * @param[in] hashalg Hash algorithm. + * @param[in] message Message that was signed. + * @param[in] message_length Length of the message in bytes. + * + * @retval 0 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pkcs1v15_verify_message(struct cracen_rsa_key *rsa_key, struct cracen_const_signature *signature, const struct sxhashalg *hashalg, const uint8_t *message, size_t message_length); +/** @brief Verify a digest signature using RSA PKCS#1 v1.5. + * + * @param[in] rsa_key RSA key structure. + * @param[in] signature Signature to verify. + * @param[in] hashalg Hash algorithm. + * @param[in] digest Digest that was signed. + * @param[in] digest_length Length of the digest in bytes. + * + * @retval 0 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pkcs1v15_verify_digest(struct cracen_rsa_key *rsa_key, struct cracen_const_signature *signature, const struct sxhashalg *hashalg, const uint8_t *digest, size_t digest_length); +/** @} */ + #endif /* CRACEN_PSA_RSA_SIGNATURE_PKCS1V15_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_signature_pss.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_signature_pss.h index 0e38ded19d0b..51bf7c035e9f 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_signature_pss.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_rsa_signature_pss.h @@ -4,27 +4,100 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_rsa_signatures + * @{ + * @brief RSA PSS signature operations for CRACEN PSA driver (internal use only). + * + * @warning These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + */ + #ifndef CRACEN_PSA_RSA_SIGNATURE_PSS_H #define CRACEN_PSA_RSA_SIGNATURE_PSS_H #include +/** @brief Sign a message using RSA PSS. + * + * @param[in] rsa_key RSA key structure. + * @param[out] signature Signature structure to populate. + * @param[in] hashalg Hash algorithm. + * @param[in] message Message to sign. + * @param[in] message_length Length of the message in bytes. + * @param[in] saltsz Salt size in bytes. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_INSUFFICIENT_ENTROPY Insufficient entropy for salt generation. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pss_sign_message(struct cracen_rsa_key *rsa_key, struct cracen_signature *signature, const struct sxhashalg *hashalg, const uint8_t *message, size_t message_length, size_t saltsz); +/** @brief Sign a digest using RSA PSS. + * + * @param[in] rsa_key RSA key structure. + * @param[out] signature Signature structure to populate. + * @param[in] hashalg Hash algorithm. + * @param[in] input Digest to sign. + * @param[in] input_length Length of the digest in bytes. + * @param[in] saltsz Salt size in bytes. + * + * @retval 0 (::SX_OK) The operation completed successfully. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_INSUFFICIENT_ENTROPY Insufficient entropy for salt generation. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pss_sign_digest(struct cracen_rsa_key *rsa_key, struct cracen_signature *signature, const struct sxhashalg *hashalg, const uint8_t *input, size_t input_length, size_t saltsz); +/** @brief Verify a message signature using RSA PSS. + * + * @param[in] rsa_key RSA key structure. + * @param[in] signature Signature to verify. + * @param[in] hashalg Hash algorithm. + * @param[in] message Message that was signed. + * @param[in] message_length Length of the message in bytes. + * @param[in] saltsz Salt size in bytes. + * + * @retval 0 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pss_verify_message(struct cracen_rsa_key *rsa_key, struct cracen_const_signature *signature, const struct sxhashalg *hashalg, const uint8_t *message, size_t message_length, size_t saltsz); +/** @brief Verify a digest signature using RSA PSS. + * + * @param[in] rsa_key RSA key structure. + * @param[in] signature Signature to verify. + * @param[in] hashalg Hash algorithm. + * @param[in] digest Digest that was signed. + * @param[in] digest_length Length of the digest in bytes. + * @param[in] saltsz Salt size in bytes. + * + * @retval 0 (::SX_OK) The signature is valid. + * @retval ::SX_ERR_INVALID_SIGNATURE The signature verification failed. + * @retval ::SX_ERR_UNSUPPORTED_HASH_ALG The hash algorithm is not supported. + * @retval ::SX_ERR_PK_RETRY Resources not available, retry later. + * @retval Other SX status codes from @ref status_codes on internal errors. + */ int cracen_rsa_pss_verify_digest(struct cracen_rsa_key *rsa_key, struct cracen_const_signature *signature, const struct sxhashalg *hashalg, const uint8_t *digest, size_t digest_length, size_t saltsz); +/** @} */ + #endif /* CRACEN_PSA_RSA_SIGNATURE_PSS_H */ diff --git a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_wpa3_sae.h b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_wpa3_sae.h index 5cac8c28d370..ceb72ea488f1 100644 --- a/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_wpa3_sae.h +++ b/subsys/nrf_security/src/drivers/cracen/cracenpsa/include/cracen_psa_wpa3_sae.h @@ -4,34 +4,115 @@ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause */ +/** + * @file + * @addtogroup cracen_psa_wpa3_sae + * @{ + * @brief WPA3 SAE (Simultaneous Authentication of Equals) support for CRACEN PSA + * driver (internal use only). + * + * @note These APIs are for internal use only. Applications should use the + * PSA Crypto API (psa_* functions) instead of calling these functions + * directly. + */ + #ifndef CRACEN_PSA_WPA3_SAE_H #define CRACEN_PSA_WPA3_SAE_H #include #include "cracen_psa_primitives.h" +/** @brief Set up a WPA3 SAE operation. + * + * @param[in,out] operation SAE operation context. + * @param[in] attributes Key attributes. + * @param[in] password Password for SAE. + * @param[in] password_length Length of the password in bytes. + * @param[in] cipher_suite PAKE cipher suite. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_NOT_SUPPORTED The algorithm is not supported. + */ psa_status_t cracen_wpa3_sae_setup(cracen_wpa3_sae_operation_t *operation, const psa_key_attributes_t *attributes, const uint8_t *password, size_t password_length, const psa_pake_cipher_suite_t *cipher_suite); +/** @brief Set the user identifier for a WPA3 SAE operation. + * + * @param[in,out] operation SAE operation context. + * @param[in] user_id User identifier. + * @param[in] user_id_len Length of the user identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_wpa3_sae_set_user(cracen_wpa3_sae_operation_t *operation, const uint8_t *user_id, size_t user_id_len); +/** @brief Set the peer identifier for a WPA3 SAE operation. + * + * @param[in,out] operation SAE operation context. + * @param[in] peer_id Peer identifier. + * @param[in] peer_id_len Length of the peer identifier in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_wpa3_sae_set_peer(cracen_wpa3_sae_operation_t *operation, const uint8_t *peer_id, size_t peer_id_len); +/** @brief Get output from a WPA3 SAE operation step. + * + * @param[in,out] operation SAE operation context. + * @param[in] step PAKE step. + * @param[out] output Buffer to store the output. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated output in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_wpa3_sae_output(cracen_wpa3_sae_operation_t *operation, psa_pake_step_t step, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Provide input to a WPA3 SAE operation step. + * + * @param[in,out] operation SAE operation context. + * @param[in] step PAKE step. + * @param[in] input Input data. + * @param[in] input_length Length of the input data in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + */ psa_status_t cracen_wpa3_sae_input(cracen_wpa3_sae_operation_t *operation, psa_pake_step_t step, const uint8_t *input, size_t input_length); +/** @brief Get the shared key from a completed WPA3 SAE operation. + * + * @param[in,out] operation SAE operation context. + * @param[in] attributes Key attributes for the shared key. + * @param[out] output Buffer to store the shared key. + * @param[in] output_size Size of the output buffer in bytes. + * @param[out] output_length Length of the generated shared key in bytes. + * + * @retval PSA_SUCCESS The operation completed successfully. + * @retval PSA_ERROR_BAD_STATE The operation is not in a valid state. + * @retval PSA_ERROR_BUFFER_TOO_SMALL The output buffer is too small. + */ psa_status_t cracen_wpa3_sae_get_shared_key(cracen_wpa3_sae_operation_t *operation, const psa_key_attributes_t *attributes, uint8_t *output, size_t output_size, size_t *output_length); +/** @brief Abort a WPA3 SAE operation. + * + * @param[in,out] operation SAE operation context. + * + * @retval PSA_SUCCESS The operation completed successfully. + */ psa_status_t cracen_wpa3_sae_abort(cracen_wpa3_sae_operation_t *operation); +/** @} */ + #endif /* CRACEN_PSA_WPA3_SAE_H */