From 00646883f1cef7713e3e15c3228f5ea3d13f675f Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 10:04:44 +0100 Subject: [PATCH 01/10] visualc: Add crypto_driver.h to project A new header file for crypto drivers has been added, so we need to ensure that the Visual Studio project files reference the new header. --- visualc/VS2010/mbedTLS.vcxproj | 1 + 1 file changed, 1 insertion(+) diff --git a/visualc/VS2010/mbedTLS.vcxproj b/visualc/VS2010/mbedTLS.vcxproj index 4d8b92af1..301d3333f 100644 --- a/visualc/VS2010/mbedTLS.vcxproj +++ b/visualc/VS2010/mbedTLS.vcxproj @@ -225,6 +225,7 @@ + From d3d26aa6b2477e5d5b65da5a578458157fb22f7f Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 10:07:32 +0100 Subject: [PATCH 02/10] psa: driver: Fix trailing whitespace issues Remove all trailing whitespace from crypto_driver.h. Ensure there is a new line at the end of crypto_driver.h. --- include/psa/crypto_driver.h | 250 ++++++++++++++++++------------------ 1 file changed, 125 insertions(+), 125 deletions(-) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index d2008b7c3..9bf00d513 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -1,7 +1,7 @@ /** * \file psa/crypto_driver.h * \brief Platform Security Architecture cryptographic driver module - * + * * This file describes an API for driver developers to implement to enable * hardware to be called in a standardized way by a PSA Cryptographic API * implementation. The API described is not intended to be called by @@ -31,7 +31,7 @@ #include /** The following types are redefinitions from the psa/crypto.h file. - * It is intended that these will be moved to a new common header file to + * It is intended that these will be moved to a new common header file to * avoid duplication. They are included here for expediency in publication. */ typedef uint32_t psa_status_t; @@ -46,7 +46,7 @@ typedef uint32_t psa_key_usage_t; /** \defgroup opaque_mac Opaque Message Authentication Code * Generation and authentication of Message Authentication Codes (MACs) using - * opaque keys can be done either as a single function call (via the + * opaque keys can be done either as a single function call (via the * `pcd_mac_opaque_generate_t` or `psa_mac_opaque_verify_t` functions), or in * parts using the following sequence: * - `psa_mac_opaque_setup_t` @@ -54,23 +54,23 @@ typedef uint32_t psa_key_usage_t; * - `psa_mac_opaque_update_t` * - ... * - `psa_mac_opaque_finish_t` or `psa_mac_opaque_finish_verify_t` - * - * If a previously started Opaque MAC operation needs to be terminated, it + * + * If a previously started Opaque MAC operation needs to be terminated, it * should be done so by the `psa_mac_opaque_abort_t`. Failure to do so may * result in allocated resources not being freed or in other undefined * behavior. */ /**@{*/ -/** \brief A function that starts a MAC operation for a PSA Crypto Driver +/** \brief A function that starts a MAC operation for a PSA Crypto Driver * implementation using an opaque key - * - * \param[in,out] p_context A structure that will contain the + * + * \param[in,out] p_context A structure that will contain the * hardware-specific MAC context * \param[in] key_slot The slot of the key to be used for the * operation - * \param[in] algorithm The algorithm to be used to underly the MAC + * \param[in] algorithm The algorithm to be used to underly the MAC * operation - * + * * \retval PSA_SUCCESS * Success. */ @@ -80,7 +80,7 @@ typedef psa_status_t (*pcd_mac_opaque_setup_t)(void *p_context, /** \brief A function that continues a previously started MAC operation using * an opaque key - * + * * \param[in,out] p_context A hardware-specific structure for the * previously-established MAC operation to be * continued @@ -94,9 +94,9 @@ typedef psa_status_t (*pcd_mac_opaque_update_t)(void *p_context, /** \brief a function that completes a previously started MAC operation by * returning the resulting MAC using an opaque key - * - * \param[in,out] p_context A hardware-specific structure for the - * previously started MAC operation to be + * + * \param[in,out] p_context A hardware-specific structure for the + * previously started MAC operation to be * finished * \param[out] p_mac A buffer where the generated MAC will be * placed @@ -104,7 +104,7 @@ typedef psa_status_t (*pcd_mac_opaque_update_t)(void *p_context, * allocated for the `output` buffer * \param[out] p_mac_length After completion, will contain the number of * bytes placed in the `p_mac` buffer - * + * * \retval PSA_SUCCESS * Success. */ @@ -115,13 +115,13 @@ typedef psa_status_t (*pcd_mac_opaque_finish_t)(void *p_context, /** \brief A function that completes a previously started MAC operation by * comparing the resulting MAC against a known value using an opaque key - * + * * \param[in,out] p_context A hardware-specific structure for the previously * started MAC operation to be fiinished * \param[in] p_mac The MAC value against which the resulting MAC will * be compared against * \param[in] mac_length The size in bytes of the value stored in `p_mac` - * + * * \retval PSA_SUCCESS * The operation completed successfully and the MACs matched each * other @@ -142,7 +142,7 @@ typedef psa_status_t (*pcd_mac_opaque_abort_t)(void *p_context); /** \brief A function that performs a MAC operation in one command and returns * the calculated MAC using an opaque key - * + * * \param[in] p_input A buffer containing the message to be MACed * \param[in] input_length The size in bytes of `p_input` * \param[in] key_slot The slot of the key to be used @@ -153,7 +153,7 @@ typedef psa_status_t (*pcd_mac_opaque_abort_t)(void *p_context); * \param[in] mac_size The size in bytes of the `p_mac` buffer * \param[out] p_mac_length After completion, will contain the number of * bytes placed in the `output` buffer - * + * * \retval PSA_SUCCESS * Success. */ @@ -167,7 +167,7 @@ typedef psa_status_t (*pcd_mac_opaque_generate_t)(const uint8_t *p_input, /** \brief A function that performs an MAC operation in one command and * compare the resulting MAC against a known value using an opaque key - * + * * \param[in] p_input A buffer containing the message to be MACed * \param[in] input_length The size in bytes of `input` * \param[in] key_slot The slot of the key to be used @@ -176,7 +176,7 @@ typedef psa_status_t (*pcd_mac_opaque_generate_t)(const uint8_t *p_input, * \param[in] p_mac The MAC value against which the resulting MAC will * be compared against * \param[in] mac_length The size in bytes of `mac` - * + * * \retval PSA_SUCCESS * The operation completed successfully and the MACs matched each * other @@ -193,18 +193,18 @@ typedef psa_status_t (*pcd_mac_opaque_verify_t)(const uint8_t *p_input, /** \brief A struct containing all of the function pointers needed to * implement MAC operations using opaque keys. - * + * * PSA Crypto API implementations should populate the table as appropriate * upon startup. * * If one of the functions is not implemented (such as * `pcd_mac_opaque_generate_t`), it should be set to NULL. - * + * * Driver implementers should ensure that they implement all of the functions * that make sense for their hardware, and that they provide a full solution * (for example, if they support `p_setup`, they should also support * `p_update` and at least one of `p_finish` or `p_finish_verify`). - * + * */ struct pcd_mac_opaque_t { /**The size in bytes of the hardware-specific Opaque-MAC Context structure @@ -236,7 +236,7 @@ struct pcd_mac_opaque_t { /** \defgroup transparent_mac Transparent Message Authentication Code * Generation and authentication of Message Authentication Codes (MACs) using - * transparent keys can be done either as a single function call (via the + * transparent keys can be done either as a single function call (via the * `pcd_mac_transparent_generate_t` or `psa_mac_transparent_verify_t` * functions), or in parts using the following sequence: * - `psa_mac_transparent_setup_t` @@ -244,12 +244,12 @@ struct pcd_mac_opaque_t { * - `psa_mac_transparent_update_t` * - ... * - `psa_mac_transparent_finish_t` or `psa_mac_transparent_finish_verify_t` - * - * If a previously started Transparent MAC operation needs to be terminated, it + * + * If a previously started Transparent MAC operation needs to be terminated, it * should be done so by the `psa_mac_transparent_abort_t`. Failure to do so may * result in allocated resources not being freed or in other undefined * behavior. - * + * */ /**@{*/ @@ -262,7 +262,7 @@ typedef struct pcd_mac_transparent_context_s pcd_mac_transparent_context_t; /** \brief The function prototype for the setup operation of a * transparent-key MAC operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} @@ -270,13 +270,13 @@ typedef struct pcd_mac_transparent_context_s pcd_mac_transparent_context_t; * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying primitive, and `MAC_VARIANT` * is the specific variant of a MAC operation (such as HMAC or CMAC) - * - * \param[in,out] p_context A structure that will contain the + * + * \param[in,out] p_context A structure that will contain the * hardware-specific MAC context * \param[in] p_key A buffer containing the cleartext key material * to be used in the operation * \param[in] key_length The size in bytes of the key material - * + * * \retval PSA_SUCCESS * Success. */ @@ -294,7 +294,7 @@ typedef psa_status_t (*pcd_mac_transparent_setup_t)(pcd_mac_transparent_context_ * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` * is the specific variant of a MAC operation (such as HMAC or CMAC) - * + * * \param[in,out] p_context A hardware-specific structure for the * previously-established MAC operation to be * continued @@ -308,7 +308,7 @@ typedef psa_status_t (*pcd_mac_transparent_update_t)(pcd_mac_transparent_context /** \brief The function prototype for the finish operation of a * transparent-key MAC operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} @@ -316,14 +316,14 @@ typedef psa_status_t (*pcd_mac_transparent_update_t)(pcd_mac_transparent_context * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started MAC operation to be * finished * \param[out] p_mac A buffer where the generated MAC will be placed * \param[in] mac_length The size in bytes of the buffer that has been * allocated for the `p_mac` buffer - * + * * \retval PSA_SUCCESS * Success. */ @@ -333,7 +333,7 @@ typedef psa_status_t (*pcd_mac_transparent_finish_t)(pcd_mac_transparent_context /** \brief The function prototype for the finish and verify operation of a * transparent-key MAC operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} @@ -341,7 +341,7 @@ typedef psa_status_t (*pcd_mac_transparent_finish_t)(pcd_mac_transparent_context * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started MAC operation to be * verified and finished @@ -349,7 +349,7 @@ typedef psa_status_t (*pcd_mac_transparent_finish_t)(pcd_mac_transparent_context * for verification * \param[in] mac_length The size in bytes of the data in the `p_mac` * buffer - * + * * \retval PSA_SUCCESS * The operation completed successfully and the comparison matched */ @@ -359,7 +359,7 @@ typedef psa_status_t (*pcd_mac_transparent_finish_verify_t)(pcd_mac_transparent_ /** \brief The function prototype for the abort operation for a previously * started transparent-key MAC operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} @@ -367,25 +367,25 @@ typedef psa_status_t (*pcd_mac_transparent_finish_verify_t)(pcd_mac_transparent_ * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started MAC operation to be * aborted - * + * */ typedef psa_status_t (*pcd_mac_transparent_abort_t)(pcd_mac_transparent_context_t *p_context); /** \brief The function prototype for a one-shot operation of a transparent-key * MAC operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} * pcd_mac_transparent__ * ~~~~~~~~~~~~~ - * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is + * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) - * + * * \param[in] p_input A buffer containing the data to be MACed * \param[in] input_length The length in bytes of the `p_input` data * \param[in] p_key A buffer containing the key material to be used @@ -406,7 +406,7 @@ typedef psa_status_t (*pcd_mac_transparent_t)(const uint8_t *p_input, /** \brief The function prototype for a one-shot operation of a transparent-key * MAC Verify operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} @@ -414,7 +414,7 @@ typedef psa_status_t (*pcd_mac_transparent_t)(const uint8_t *p_input, * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) - * + * * \param[in] p_input A buffer containing the data to be MACed * \param[in] input_length The length in bytes of the `p_input` data * \param[in] p_key A buffer containing the key material to be used @@ -423,7 +423,7 @@ typedef psa_status_t (*pcd_mac_transparent_t)(const uint8_t *p_input, * \param[in] alg The algorithm to be performed * \param[in] p_mac The MAC data to be compared * \param[in] mac_length The length in bytes of the `p_mac` buffer - * + * * \retval PSA_SUCCESS * The operation completed successfully and the comparison matched */ @@ -437,7 +437,7 @@ typedef psa_status_t (*pcd_mac_transparent_verify_t)(const uint8_t *p_input, /**@}*/ /** \defgroup opaque_cipher Opaque Symmetric Ciphers - * + * * Encryption and Decryption using opaque keys in block modes other than ECB * must be done in multiple parts, using the following flow: * - `pcd_cipher_opaque_setup_t` @@ -446,11 +446,11 @@ typedef psa_status_t (*pcd_mac_transparent_verify_t)(const uint8_t *p_input, * - ... * - `pcd_cipher_opaque_finish_t` - * If a previously started Opaque Cipher operation needs to be terminated, it + * If a previously started Opaque Cipher operation needs to be terminated, it * should be done so by the `psa_cipher_opaque_abort_t`. Failure to do so may * result in allocated resources not being freed or in other undefined * behavior. - * + * * In situations where a PSA Cryptographic API implementation is using a block * mode not-supported by the underlying hardware or driver, it can construct * the block mode itself, while calling the `pcd_cipher_opaque_ecb_t` function @@ -469,7 +469,7 @@ typedef psa_status_t (*pcd_mac_transparent_verify_t)(const uint8_t *p_input, * operation * \param[in] direction Indicates whether the operation is an encrypt * or decrypt - * + * * \retval PSA_SUCCESS * \retval PSA_ERROR_NOT_SUPPORTED */ @@ -480,17 +480,17 @@ typedef psa_status_t (*pcd_cipher_opaque_setup_t)(void *p_context, /** \brief A function pointer that sets the initialization vector (if * necessary) for an opaque cipher operation - * + * * Rationale: The `psa_cipher_*` function in the PSA Cryptographic API has two * IV functions: one to set the IV, and one to generate it internally. The * generate function is not necessary for the driver API as the PSA Crypto * implementation can do the generation using its RNG features. - * + * * \param[in,out] p_context A structure that contains the previously set up * hardware-specific cipher context * \param[in] p_iv A buffer containing the initialization vector * \param[in] iv_length The size (in bytes) of the `p_iv` buffer - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_cipher_opaque_set_iv_t)(void *p_context, @@ -499,7 +499,7 @@ typedef psa_status_t (*pcd_cipher_opaque_set_iv_t)(void *p_context, /** \brief A function that continues a previously started opaque-key cipher * operation - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started cipher operation * \param[in] p_input A buffer containing the data to be @@ -512,7 +512,7 @@ typedef psa_status_t (*pcd_cipher_opaque_set_iv_t)(void *p_context, * `p_output` buffer * \param[out] p_output_length After completion, will contain the number * of bytes placed in the `p_output` buffer - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_cipher_opaque_update_t)(void *p_context, @@ -533,7 +533,7 @@ typedef psa_status_t (*pcd_cipher_opaque_update_t)(void *p_context, * buffer * \param[out] p_output_length After completion, will contain the number of * bytes placed in the `p_output` buffer - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_cipher_opaque_finish_t)(void *p_context, @@ -551,10 +551,10 @@ typedef psa_status_t (*pcd_cipher_opaque_abort_t)(void *p_context); /** \brief A function that performs the ECB block mode for opaque-key cipher * operations - * + * * Note: this function should only be used with implementations that do not * provide a needed higher-level operation. - * + * * \param[in] key_slot The slot of the key to be used for the operation * \param[in] algorithm The algorithm to be used in the cipher operation * \param[in] direction Indicates whether the operation is an encrypt or @@ -567,7 +567,7 @@ typedef psa_status_t (*pcd_cipher_opaque_abort_t)(void *p_context); * be placed * \param[in] output_size The allocated size in bytes of the `p_output` * buffer - * + * * \retval PSA_SUCCESS * \retval PSA_ERROR_NOT_SUPPORTED */ @@ -582,10 +582,10 @@ typedef psa_status_t (*pcd_cipher_opaque_ecb_t)(psa_key_slot_t key_slot, /** * \brief A struct containing all of the function pointers needed to implement * cipher operations using opaque keys. - * + * * PSA Crypto API implementations should populate instances of the table as * appropriate upon startup. - * + * * If one of the functions is not implemented (such as * `pcd_cipher_opaque_ecb_t`), it should be set to NULL. */ @@ -630,7 +630,7 @@ struct pcd_cipher_opaque_t { /**@{*/ /** \brief The hardware-specific transparent-key Cipher context structure - * + * * The contents of this structure are implementation dependent and are * therefore not described here. */ @@ -651,7 +651,7 @@ typedef struct pcd_cipher_transparent_context_s pcd_cipher_transparent_context_t * pcd_cipher_transparent_setup_ * ~~~~~~~~~~~~~ * Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4) - * + * * \param[in,out] p_context A structure that will contain the * hardware-specific cipher context * \param[in] direction Indicates if the operation is an encrypt or a @@ -659,7 +659,7 @@ typedef struct pcd_cipher_transparent_context_s pcd_cipher_transparent_context_t * \param[in] p_key_data A buffer containing the cleartext key material * to be used in the operation * \param[in] key_data_size The size in bytes of the key material - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_cipher_transparent_setup_t)(pcd_cipher_transparent_context_t *p_context, @@ -677,12 +677,12 @@ typedef psa_status_t (*pcd_cipher_transparent_setup_t)(pcd_cipher_transparent_co * Where * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) - * + * * \param[in,out] p_context A structure that contains the previously setup * hardware-specific cipher context * \param[in] p_iv A buffer containing the initialization vecotr * \param[in] iv_length The size in bytes of the contents of `p_iv` - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_cipher_transparent_set_iv_t)(pcd_cipher_transparent_context_t *p_context, @@ -700,7 +700,7 @@ typedef psa_status_t (*pcd_cipher_transparent_set_iv_t)(pcd_cipher_transparent_c * Where * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started cipher operation * \param[in] p_input A buffer containing the data to be @@ -711,7 +711,7 @@ typedef psa_status_t (*pcd_cipher_transparent_set_iv_t)(pcd_cipher_transparent_c * \param[in] output_size The size in bytes of the `p_output` buffer * \param[out] p_output_length After completion, will contain the number * of bytes placed in the `p_output` buffer - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_cipher_transparent_update_t)(pcd_cipher_transparent_context_t *p_context, @@ -740,7 +740,7 @@ typedef psa_status_t (*pcd_cipher_transparent_update_t)(pcd_cipher_transparent_c * \param[in] output_size The size in bytes of the `p_output` buffer * \param[out] p_output_length After completion, will contain the number of * bytes placed in the `p_output` buffer - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_cipher_transparent_finish_t)(pcd_cipher_transparent_context_t *p_context, @@ -750,7 +750,7 @@ typedef psa_status_t (*pcd_cipher_transparent_finish_t)(pcd_cipher_transparent_c /** \brief The function prototype for the abort operation of transparent-key * block cipher operations. - * + * * Functions that implement the following prototype should be named in the * following convention: * ~~~~~~~~~~~~~{.c} @@ -759,10 +759,10 @@ typedef psa_status_t (*pcd_cipher_transparent_finish_t)(pcd_cipher_transparent_c * Where * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started cipher operation - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_cipher_transparent_abort_t)(pcd_cipher_transparent_context_t *p_context); @@ -770,14 +770,14 @@ typedef psa_status_t (*pcd_cipher_transparent_abort_t)(pcd_cipher_transparent_co /**@}*/ /** \defgroup driver_digest Message Digests - * + * * Generation and authentication of Message Digests (aka hashes) must be done * in parts using the following sequence: * - `psa_hash_setup_t` * - `psa_hash_update_t` * - ... * - `psa_hash_finish_t` - * + * * If a previously started Message Digest operation needs to be terminated * before the `psa_hash_finish_t` operation is complete, it should be aborted * by the `psa_hash_abort_t`. Failure to do so may result in allocated @@ -786,7 +786,7 @@ typedef psa_status_t (*pcd_cipher_transparent_abort_t)(pcd_cipher_transparent_co /**@{*/ /** \brief The hardware-specific hash context structure - * + * * The contents of this structure are implementation dependent and are * therefore not described here */ @@ -794,17 +794,17 @@ typedef struct pcd_hash_context_s pcd_hash_context_t; /** \brief The function prototype for the start operation of a hash (message * digest) operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} * pcd_hash__setup * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying hash function - * + * * \param[in,out] p_context A structure that will contain the * hardware-specific hash context - * + * * \retval PSA_SUCCESS Success. */ typedef psa_status_t (*pcd_hash_setup_t)(pcd_hash_context_t *p_context); @@ -818,7 +818,7 @@ typedef psa_status_t (*pcd_hash_setup_t)(pcd_hash_context_t *p_context); * pcd_hash__update * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm - * + * * \param[in,out] p_context A hardware-specific structure for the * previously-established hash operation to be * continued @@ -832,14 +832,14 @@ typedef psa_status_t (*pcd_hash_update_t)(pcd_hash_context_t *p_context, /** \brief The prototype for the finish operation of a hash (message digest) * operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} * pcd_hash__finish * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started hash operation to be * fiinished @@ -849,7 +849,7 @@ typedef psa_status_t (*pcd_hash_update_t)(pcd_hash_context_t *p_context, * allocated for the `p_output` buffer * \param[out] p_output_length The number of bytes placed in `p_output` after * success - * + * * \retval PSA_SUCCESS * Success. */ @@ -860,14 +860,14 @@ typedef psa_status_t (*pcd_hash_finish_t)(pcd_hash_context_t *p_context, /** \brief The function prototype for the abort operation of a hash (message * digest) operation - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} * pcd_hash__abort * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm - * + * * \param[in,out] p_context A hardware-specific structure for the previously * started hash operation to be aborted */ @@ -877,7 +877,7 @@ typedef void (*pcd_hash_abort_t)(pcd_hash_context_t *p_context); /** \defgroup opaque_asymmetric Opaque Asymmetric Cryptography - * + * * Since the amount of data that can (or should) be encrypted or signed using * asymmetric keys is limited by the key size, asymmetric key operations using * opaque keys must be done in single function calls. @@ -1009,10 +1009,10 @@ typedef psa_status_t (*pcd_asymmetric_opaque_decrypt_t)(psa_key_slot_t key_slot, /** * \brief A struct containing all of the function pointers needed to implement * asymmetric cryptographic operations using opaque keys. - * + * * PSA Crypto API implementations should populate instances of the table as * appropriate upon startup. - * + * * If one of the functions is not implemented, it should be set to NULL. */ struct pcd_asymmetric_opaque_t { @@ -1040,14 +1040,14 @@ struct pcd_asymmetric_opaque_t { /** * \brief A function that signs a hash or short message with a transparent * asymmetric private key - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} * pcd_asymmetric__sign * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the signing algorithm - * + * * \param[in] p_key A buffer containing the private key * material * \param[in] key_size The size in bytes of the `p_key` data @@ -1080,8 +1080,8 @@ typedef psa_status_t (*pcd_asymmetric_transparent_sign_t)(const uint8_t *p_key, * ~~~~~~~~~~~~~{.c} * pcd_asymmetric__verify * ~~~~~~~~~~~~~ - * Where `ALGO` is the name of the signing algorithm - * + * Where `ALGO` is the name of the signing algorithm + * * \param[in] p_key A buffer containing the public key material * \param[in] key_size The size in bytes of the `p_key` data * \param[in] alg A signature algorithm that is compatible with @@ -1113,7 +1113,7 @@ typedef psa_status_t (*pcd_asymmetric_transparent_verify_t)(const uint8_t *p_key * pcd_asymmetric__encrypt * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the encryption algorithm - * + * * \param[in] p_key A buffer containing the public key material * \param[in] key_size The size in bytes of the `p_key` data * \param[in] alg An asymmetric encryption algorithm that is @@ -1159,7 +1159,7 @@ typedef psa_status_t (*pcd_asymmetric_transparent_encrypt_t)(const uint8_t *p_ke * pcd_asymmetric__decrypt * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the encryption algorithm - * + * * \param[in] p_key A buffer containing the private key material * \param[in] key_size The size in bytes of the `p_key` data * \param[in] alg An asymmetric encryption algorithm that is @@ -1200,7 +1200,7 @@ typedef psa_status_t (*pcd_asymmetric_transparent_decrypt_t)(const uint8_t *p_ke /** \defgroup aead_opaque AEAD Opaque * Authenticated Encryption with Additional Data (AEAD) operations with opaque - * keys must be done in one function call. While this creates a burden for + * keys must be done in one function call. While this creates a burden for * implementers as there must be sufficient space in memory for the entire * message, it prevents decrypted data from being made available before the * authentication operation is complete and the data is known to be authentic. @@ -1291,10 +1291,10 @@ typedef psa_status_t (*psa_aead_opaque_decrypt_t)(psa_key_slot_t key_slot, /** * \brief A struct containing all of the function pointers needed to implement * Authenticated Encryption with Additional Data operations using opaque keys - * + * * PSA Crypto API implementations should populate instances of the table as * appropriate upon startup. - * + * * If one of the functions is not implemented, it should be set to NULL. */ struct psa_aead_opaque_t { @@ -1306,7 +1306,7 @@ struct psa_aead_opaque_t { /**@}*/ /** \defgroup aead_transparent AEAD Transparent - * + * * Authenticated Encryption with Additional Data (AEAD) operations with * transparent keys must be done in one function call. While this creates a * burden for implementers as there must be sufficient space in memory for the @@ -1317,7 +1317,7 @@ struct psa_aead_opaque_t { /**@{*/ /** Process an authenticated encryption operation using an opaque key. - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} @@ -1354,7 +1354,7 @@ struct psa_aead_opaque_t { * the `ciphertext` buffer * * \retval #PSA_SUCCESS - + */ typedef psa_status_t (*psa_aead_transparent_encrypt_t)(const uint8_t *p_key, size_t key_length, @@ -1370,7 +1370,7 @@ typedef psa_status_t (*psa_aead_transparent_encrypt_t)(const uint8_t *p_key, size_t *ciphertext_length); /** Process an authenticated decryption operation using an opaque key. - * + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} @@ -1433,7 +1433,7 @@ typedef struct pcd_entropy_context_s pcd_entropy_context_t; /** \brief Initialize an entropy driver * - * + * * \param[in,out] p_context A hardware-specific structure * containing any context information for * the implementation @@ -1443,7 +1443,7 @@ typedef struct pcd_entropy_context_s pcd_entropy_context_t; typedef psa_status_t (*pcd_entropy_init_t)(pcd_entropy_context_t *p_context); /** \brief Get a specified number of bits from the entropy source - * + * * It retrives `buffer_size` bytes of data from the entropy source. The entropy * source will always fill the provided buffer to its full size, however, most * entropy sources have biases, and the actual amount of entropy contained in @@ -1456,7 +1456,7 @@ typedef psa_status_t (*pcd_entropy_init_t)(pcd_entropy_context_t *p_context); * To accomplish this, the PSA Crypto implementation should be designed to call * this function multiple times until it has received the required amount of * entropy from the entropy source. - * + * * \param[in,out] p_context A hardware-specific structure * containing any context information * for the implementation @@ -1465,7 +1465,7 @@ typedef psa_status_t (*pcd_entropy_init_t)(pcd_entropy_context_t *p_context); * \param[in] buffer_size The allocated size of `p_buffer` * \param[out] p_received_entropy_bits The amount of entropy (in bits) * actually provided in `p_buffer` - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_entropy_get_bits_t)(pcd_entropy_context_t *p_context, @@ -1476,10 +1476,10 @@ typedef psa_status_t (*pcd_entropy_get_bits_t)(pcd_entropy_context_t *p_context, /** * \brief A struct containing all of the function pointers needed to interface * to an entropy source - * + * * PSA Crypto API implementations should populate instances of the table as * appropriate upon startup. - * + * * If one of the functions is not implemented, it should be set to NULL. */ struct pcd_entropy_t { @@ -1615,10 +1615,10 @@ typedef psa_status_t (*pcd_export_public_key_t)(psa_key_slot_t key, /** * \brief A struct containing all of the function pointers needed to for key * management using opaque keys - * + * * PSA Crypto API implementations should populate instances of the table as * appropriate upon startup. - * + * * If one of the functions is not implemented, it should be set to NULL. */ struct pcd_key_management_t { @@ -1643,14 +1643,14 @@ struct pcd_key_management_t { * material. * The flows are similar, and the PSA Crypto Driver API uses the same functions * for both of the flows. - * + * * There are two different final functions for the flows, * `pcd_key_derivation_derive` and `pcd_key_derivation_export`. * `pcd_key_derivation_derive` is used when the key material should be placed * in a slot on the hardware and not exposed to the caller. * `pcd_key_derivation_export` is used when the key material should be returned * to the PSA Cryptographic API implementation. - * + * * Different key derivation algorithms require a different number of inputs. * Instead of having an API that takes as input variable length arrays, which * can be problemmatic to manage on embedded platforms, the inputs are passed @@ -1671,7 +1671,7 @@ struct pcd_key_management_t { * collateral_2_size); * pcd_key_derivation_derive(); * ~~~~~~~~~~~~~ - * + * * key agreement example: * ~~~~~~~~~~~~~{.c} * pcd_key_derivation_setup(alg, source_key. dest_key_size_bytes); @@ -1684,7 +1684,7 @@ struct pcd_key_management_t { /**@{*/ /** \brief The hardware-specific key derivation context structure - * + * * The contents of this structure are implementation dependent and are * therefore not described here */ @@ -1692,13 +1692,13 @@ typedef struct pcd_key_derivation_context_s pcd_key_derivation_context_t; /** \brief Set up a key derivation operation by specifying the algorithm and * the source key sot - * + * * \param[in,out] p_context A hardware-specific structure containing any * context information for the implementation * \param[in] kdf_alg The algorithm to be used for the key derivation * \param[in] souce_key The key to be used as the source material for the * key derivation - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_key_derivation_setup_t)(pcd_key_derivation_context_t *p_context, @@ -1707,17 +1707,17 @@ typedef psa_status_t (*pcd_key_derivation_setup_t)(pcd_key_derivation_context_t /** \brief Provide collateral (parameters) needed for a key derivation or key * agreement operation - * + * * Since many key derivation algorithms require multiple parameters, it is * expeced that this function may be called multiple times for the same * operation, each with a different algorithm-specific `collateral_id` - * + * * \param[in,out] p_context A hardware-specific structure containing any * context information for the implementation * \param[in] collateral_id An ID for the collateral being provided * \param[in] p_collateral A buffer containing the collateral data * \param[in] collateral_size The size in bytes of the collateral - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_key_derivation_collateral_t)(pcd_key_derivation_context_t *p_context, @@ -1731,7 +1731,7 @@ typedef psa_status_t (*pcd_key_derivation_collateral_t)(pcd_key_derivation_conte * context information for the implementation * \param[in] dest_key The slot where the generated key material * should be placed - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_key_derivation_derive_t)(pcd_key_derivation_context_t *p_context, @@ -1739,13 +1739,13 @@ typedef psa_status_t (*pcd_key_derivation_derive_t)(pcd_key_derivation_context_t /** \brief Perform the final step of a key agreement and place the generated * key material in a buffer - * + * * \param[out] p_output Buffer in which to place the generated key * material * \param[in] output_size The size in bytes of `p_output` * \param[out] p_output_length Upon success, contains the number of bytes of * key material placed in `p_output` - * + * * \retval PSA_SUCCESS */ typedef psa_status_t (*pcd_key_derivation_export_t)(uint8_t *p_output, @@ -1755,10 +1755,10 @@ typedef psa_status_t (*pcd_key_derivation_export_t)(uint8_t *p_output, /** * \brief A struct containing all of the function pointers needed to for key * derivation and agreement - * + * * PSA Crypto API implementations should populate instances of the table as * appropriate upon startup. - * + * * If one of the functions is not implemented, it should be set to NULL. */ struct pcd_key_derivation_t { @@ -1775,4 +1775,4 @@ struct pcd_key_derivation_t { /**@}*/ -#endif // __PSA_CRYPTO_DRIVER_H__ \ No newline at end of file +#endif // __PSA_CRYPTO_DRIVER_H__ From 0a09f77357737a4df763a3c13131519a82984db5 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 11:42:32 +0100 Subject: [PATCH 03/10] psa: driver: Fix comment whitespace format Fix comment formatting whitespace issues in crypto_driver.h to match our style. --- include/psa/crypto_driver.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index 9bf00d513..737476a9d 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -684,7 +684,7 @@ typedef psa_status_t (*pcd_cipher_transparent_setup_t)(pcd_cipher_transparent_co * \param[in] iv_length The size in bytes of the contents of `p_iv` * * \retval PSA_SUCCESS -*/ + */ typedef psa_status_t (*pcd_cipher_transparent_set_iv_t)(pcd_cipher_transparent_context_t *p_context, const uint8_t *p_iv, size_t iv_length); @@ -723,7 +723,7 @@ typedef psa_status_t (*pcd_cipher_transparent_update_t)(pcd_cipher_transparent_c /** \brief The function prototype for the finish operation of transparent-key * block cipher operations. -* + * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} From 72244ae5954c76f7ebe21929fe64dfdd6fc88680 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 10:59:12 +0100 Subject: [PATCH 04/10] psa: driver: Fix names of AEAD functions The driver AEAD functions had a `psa_` prefix. They should have had a `pcd_` prefix like the other driver functions. --- include/psa/crypto_driver.h | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index 737476a9d..0e07eef0e 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -1236,7 +1236,7 @@ typedef psa_status_t (*pcd_asymmetric_transparent_decrypt_t)(const uint8_t *p_ke * \retval #PSA_SUCCESS * Success. */ -typedef psa_status_t (*psa_aead_opaque_encrypt_t)(psa_key_slot_t key_slot, +typedef psa_status_t (*pcd_aead_opaque_encrypt_t)(psa_key_slot_t key_slot, psa_algorithm_t algorithm, const uint8_t *p_nonce, size_t nonce_length, @@ -1276,7 +1276,7 @@ typedef psa_status_t (*psa_aead_opaque_encrypt_t)(psa_key_slot_t key_slot, * \retval #PSA_SUCCESS * Success. */ -typedef psa_status_t (*psa_aead_opaque_decrypt_t)(psa_key_slot_t key_slot, +typedef psa_status_t (*pcd_aead_opaque_decrypt_t)(psa_key_slot_t key_slot, psa_algorithm_t algorithm, const uint8_t *p_nonce, size_t nonce_length, @@ -1297,11 +1297,11 @@ typedef psa_status_t (*psa_aead_opaque_decrypt_t)(psa_key_slot_t key_slot, * * If one of the functions is not implemented, it should be set to NULL. */ -struct psa_aead_opaque_t { +struct pcd_aead_opaque_t { /** Function that performs the AEAD encrypt operation */ - psa_aead_opaque_encrypt_t *p_encrypt; + pcd_aead_opaque_encrypt_t *p_encrypt; /** Function that performs the AEAD decrypt operation */ - psa_aead_opaque_decrypt_t *p_decrypt; + pcd_aead_opaque_decrypt_t *p_decrypt; }; /**@}*/ @@ -1356,7 +1356,7 @@ struct psa_aead_opaque_t { * \retval #PSA_SUCCESS */ -typedef psa_status_t (*psa_aead_transparent_encrypt_t)(const uint8_t *p_key, +typedef psa_status_t (*pcd_aead_transparent_encrypt_t)(const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, const uint8_t *nonce, @@ -1407,7 +1407,7 @@ typedef psa_status_t (*psa_aead_transparent_encrypt_t)(const uint8_t *p_key, * \retval #PSA_SUCCESS * Success. */ -typedef psa_status_t (*psa_aead_transparent_decrypt_t)(const uint8_t *p_key, +typedef psa_status_t (*pcd_aead_transparent_decrypt_t)(const uint8_t *p_key, size_t key_length, psa_algorithm_t alg, const uint8_t *nonce, From e095d60d95f587aeeb1ab054eed9b11a18d0ad3e Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 12:09:31 +0100 Subject: [PATCH 05/10] psa: driver: Use "Driver Model" terminology "Driver APIs" can be interpreted to mean APIs used when you want to write a driver, not the set of functions you implement to make a driver. See https://www.kernel.org/doc/html/latest/driver-api/index.html "The kernel offers a wide variety of interfaces to support the development of device drivers." As such, we are renaming "Driver API" to "Driver Model" and updating our work so far to reflect this change. --- include/psa/crypto_driver.h | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index 0e07eef0e..a59ff6e29 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -2,10 +2,11 @@ * \file psa/crypto_driver.h * \brief Platform Security Architecture cryptographic driver module * - * This file describes an API for driver developers to implement to enable - * hardware to be called in a standardized way by a PSA Cryptographic API - * implementation. The API described is not intended to be called by - * application developers. + * This file describes the PSA Crypto Driver Model, containing functions for + * driver developers to implement to enable hardware to be called in a + * standardized way by a PSA Cryptographic API implementation. The functions + * comprising the driver model, which driver authors implement, are not + * intended to be called by application developers. */ /* @@ -483,8 +484,8 @@ typedef psa_status_t (*pcd_cipher_opaque_setup_t)(void *p_context, * * Rationale: The `psa_cipher_*` function in the PSA Cryptographic API has two * IV functions: one to set the IV, and one to generate it internally. The - * generate function is not necessary for the driver API as the PSA Crypto - * implementation can do the generation using its RNG features. + * generate function is not necessary for the drivers to implement as the PSA + * Crypto implementation can do the generation using its RNG features. * * \param[in,out] p_context A structure that contains the previously set up * hardware-specific cipher context @@ -1641,7 +1642,7 @@ struct pcd_key_management_t { * Key agreement is a part of cryptographic protocols that allows two parties * to agree on the same key value, but starting from different original key * material. - * The flows are similar, and the PSA Crypto Driver API uses the same functions + * The flows are similar, and the PSA Crypto Driver Model uses the same functions * for both of the flows. * * There are two different final functions for the flows, From 1acb2c43179837c8adcb5f167fb8d29cff9be201 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 10:49:58 +0100 Subject: [PATCH 06/10] psa: driver: Replace `pcd_` prefix with `psa_drv_` The `pcd_` prefix is ambiguous and does not make it clear that the types and symbols are standardized by PSA. Replace `pcd_` with a prefix that can be shared with all PSA drivers, `psa_drv_`. --- include/psa/crypto_driver.h | 698 ++++++++++++++++++------------------ 1 file changed, 349 insertions(+), 349 deletions(-) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index a59ff6e29..9acd33066 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -48,7 +48,7 @@ typedef uint32_t psa_key_usage_t; /** \defgroup opaque_mac Opaque Message Authentication Code * Generation and authentication of Message Authentication Codes (MACs) using * opaque keys can be done either as a single function call (via the - * `pcd_mac_opaque_generate_t` or `psa_mac_opaque_verify_t` functions), or in + * `psa_drv_mac_opaque_generate_t` or `psa_mac_opaque_verify_t` functions), or in * parts using the following sequence: * - `psa_mac_opaque_setup_t` * - `psa_mac_opaque_update_t` @@ -75,9 +75,9 @@ typedef uint32_t psa_key_usage_t; * \retval PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_mac_opaque_setup_t)(void *p_context, - psa_key_slot_t key_slot, - psa_algorithm_t algorithm); +typedef psa_status_t (*psa_drv_mac_opaque_setup_t)(void *p_context, + psa_key_slot_t key_slot, + psa_algorithm_t algorithm); /** \brief A function that continues a previously started MAC operation using * an opaque key @@ -89,9 +89,9 @@ typedef psa_status_t (*pcd_mac_opaque_setup_t)(void *p_context, * to the MAC operation * \param[in] input_length The size in bytes of the input message buffer */ -typedef psa_status_t (*pcd_mac_opaque_update_t)(void *p_context, - const uint8_t *p_input, - size_t input_length); +typedef psa_status_t (*psa_drv_mac_opaque_update_t)(void *p_context, + const uint8_t *p_input, + size_t input_length); /** \brief a function that completes a previously started MAC operation by * returning the resulting MAC using an opaque key @@ -109,10 +109,10 @@ typedef psa_status_t (*pcd_mac_opaque_update_t)(void *p_context, * \retval PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_mac_opaque_finish_t)(void *p_context, - uint8_t *p_mac, - size_t mac_size, - size_t *p_mac_length); +typedef psa_status_t (*psa_drv_mac_opaque_finish_t)(void *p_context, + uint8_t *p_mac, + size_t mac_size, + size_t *p_mac_length); /** \brief A function that completes a previously started MAC operation by * comparing the resulting MAC against a known value using an opaque key @@ -130,16 +130,16 @@ typedef psa_status_t (*pcd_mac_opaque_finish_t)(void *p_context, * The operation completed successfully, but the calculated MAC did * not match the provided MAC */ -typedef psa_status_t (*pcd_mac_opaque_finish_verify_t)(void *p_context, - const uint8_t *p_mac, - size_t mac_length); +typedef psa_status_t (*psa_drv_mac_opaque_finish_verify_t)(void *p_context, + const uint8_t *p_mac, + size_t mac_length); /** \brief A function that aborts a previous started opaque-key MAC operation * \param[in,out] p_context A hardware-specific structure for the previously * started MAC operation to be aborted */ -typedef psa_status_t (*pcd_mac_opaque_abort_t)(void *p_context); +typedef psa_status_t (*psa_drv_mac_opaque_abort_t)(void *p_context); /** \brief A function that performs a MAC operation in one command and returns * the calculated MAC using an opaque key @@ -158,13 +158,13 @@ typedef psa_status_t (*pcd_mac_opaque_abort_t)(void *p_context); * \retval PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_mac_opaque_generate_t)(const uint8_t *p_input, - size_t input_length, - psa_key_slot_t key_slot, - psa_algorithm_t alg, - uint8_t *p_mac, - size_t mac_size, - size_t *p_mac_length); +typedef psa_status_t (*psa_drv_mac_opaque_generate_t)(const uint8_t *p_input, + size_t input_length, + psa_key_slot_t key_slot, + psa_algorithm_t alg, + uint8_t *p_mac, + size_t mac_size, + size_t *p_mac_length); /** \brief A function that performs an MAC operation in one command and * compare the resulting MAC against a known value using an opaque key @@ -185,12 +185,12 @@ typedef psa_status_t (*pcd_mac_opaque_generate_t)(const uint8_t *p_input, * The operation completed successfully, but the calculated MAC did * not match the provided MAC */ -typedef psa_status_t (*pcd_mac_opaque_verify_t)(const uint8_t *p_input, - size_t input_length, - psa_key_slot_t key_slot, - psa_algorithm_t alg, - const uint8_t *p_mac, - size_t mac_length); +typedef psa_status_t (*psa_drv_mac_opaque_verify_t)(const uint8_t *p_input, + size_t input_length, + psa_key_slot_t key_slot, + psa_algorithm_t alg, + const uint8_t *p_mac, + size_t mac_length); /** \brief A struct containing all of the function pointers needed to * implement MAC operations using opaque keys. @@ -199,7 +199,7 @@ typedef psa_status_t (*pcd_mac_opaque_verify_t)(const uint8_t *p_input, * upon startup. * * If one of the functions is not implemented (such as - * `pcd_mac_opaque_generate_t`), it should be set to NULL. + * `psa_drv_mac_opaque_generate_t`), it should be set to NULL. * * Driver implementers should ensure that they implement all of the functions * that make sense for their hardware, and that they provide a full solution @@ -207,38 +207,38 @@ typedef psa_status_t (*pcd_mac_opaque_verify_t)(const uint8_t *p_input, * `p_update` and at least one of `p_finish` or `p_finish_verify`). * */ -struct pcd_mac_opaque_t { +struct psa_drv_mac_opaque_t { /**The size in bytes of the hardware-specific Opaque-MAC Context structure */ - size_t context_size; + size_t context_size; /** Function that performs the setup operation */ - pcd_mac_opaque_setup_t *p_setup; + psa_drv_mac_opaque_setup_t *p_setup; /** Function that performs the update operation */ - pcd_mac_opaque_update_t *p_update; + psa_drv_mac_opaque_update_t *p_update; /** Function that completes the operation */ - pcd_mac_opaque_finish_t *p_finish; + psa_drv_mac_opaque_finish_t *p_finish; /** Function that completed a MAC operation with a verify check */ - pcd_mac_opaque_finish_verify_t *p_finish_verify; + psa_drv_mac_opaque_finish_verify_t *p_finish_verify; /** Function that aborts a previoustly started operation */ - pcd_mac_opaque_abort_t *p_abort; + psa_drv_mac_opaque_abort_t *p_abort; /** Function that performs the MAC operation in one call */ - pcd_mac_opaque_generate_t *p_mac; + psa_drv_mac_opaque_generate_t *p_mac; /** Function that performs the MAC and verify operation in one call */ - pcd_mac_opaque_verify_t *p_mac_verify; + psa_drv_mac_opaque_verify_t *p_mac_verify; }; /**@}*/ /** \defgroup transparent_mac Transparent Message Authentication Code * Generation and authentication of Message Authentication Codes (MACs) using * transparent keys can be done either as a single function call (via the - * `pcd_mac_transparent_generate_t` or `psa_mac_transparent_verify_t` + * `psa_drv_mac_transparent_generate_t` or `psa_mac_transparent_verify_t` * functions), or in parts using the following sequence: * - `psa_mac_transparent_setup_t` * - `psa_mac_transparent_update_t` @@ -259,7 +259,7 @@ struct pcd_mac_opaque_t { * The contents of this structure are implementation dependent and are * therefore not described here. */ -typedef struct pcd_mac_transparent_context_s pcd_mac_transparent_context_t; +typedef struct psa_drv_mac_transparent_context_s psa_drv_mac_transparent_context_t; /** \brief The function prototype for the setup operation of a * transparent-key MAC operation @@ -267,7 +267,7 @@ typedef struct pcd_mac_transparent_context_s pcd_mac_transparent_context_t; * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_mac_transparent___setup + * psa_drv_mac_transparent___setup * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying primitive, and `MAC_VARIANT` * is the specific variant of a MAC operation (such as HMAC or CMAC) @@ -281,9 +281,9 @@ typedef struct pcd_mac_transparent_context_s pcd_mac_transparent_context_t; * \retval PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_mac_transparent_setup_t)(pcd_mac_transparent_context_t *p_context, - const uint8_t *p_key, - size_t key_length); +typedef psa_status_t (*psa_drv_mac_transparent_setup_t)(psa_drv_mac_transparent_context_t *p_context, + const uint8_t *p_key, + size_t key_length); /** \brief The function prototype for the update operation of a * transparent-key MAC operation @@ -291,7 +291,7 @@ typedef psa_status_t (*pcd_mac_transparent_setup_t)(pcd_mac_transparent_context_ * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_mac_transparent___update + * psa_drv_mac_transparent___update * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` * is the specific variant of a MAC operation (such as HMAC or CMAC) @@ -303,9 +303,9 @@ typedef psa_status_t (*pcd_mac_transparent_setup_t)(pcd_mac_transparent_context_ * to the MAC operation * \param[in] input_length The size in bytes of the input message buffer */ -typedef psa_status_t (*pcd_mac_transparent_update_t)(pcd_mac_transparent_context_t *p_context, - const uint8_t *p_input, - size_t input_length); +typedef psa_status_t (*psa_drv_mac_transparent_update_t)(psa_drv_mac_transparent_context_t *p_context, + const uint8_t *p_input, + size_t input_length); /** \brief The function prototype for the finish operation of a * transparent-key MAC operation @@ -313,7 +313,7 @@ typedef psa_status_t (*pcd_mac_transparent_update_t)(pcd_mac_transparent_context * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_mac_transparent___finish + * psa_drv_mac_transparent___finish * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) @@ -328,9 +328,9 @@ typedef psa_status_t (*pcd_mac_transparent_update_t)(pcd_mac_transparent_context * \retval PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_mac_transparent_finish_t)(pcd_mac_transparent_context_t *p_context, - uint8_t *p_mac, - size_t mac_length); +typedef psa_status_t (*psa_drv_mac_transparent_finish_t)(psa_drv_mac_transparent_context_t *p_context, + uint8_t *p_mac, + size_t mac_length); /** \brief The function prototype for the finish and verify operation of a * transparent-key MAC operation @@ -338,7 +338,7 @@ typedef psa_status_t (*pcd_mac_transparent_finish_t)(pcd_mac_transparent_context * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_mac_transparent___finish_verify + * psa_drv_mac_transparent___finish_verify * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) @@ -354,9 +354,9 @@ typedef psa_status_t (*pcd_mac_transparent_finish_t)(pcd_mac_transparent_context * \retval PSA_SUCCESS * The operation completed successfully and the comparison matched */ -typedef psa_status_t (*pcd_mac_transparent_finish_verify_t)(pcd_mac_transparent_context_t *p_context, - const uint8_t *p_mac, - size_t mac_length); +typedef psa_status_t (*psa_drv_mac_transparent_finish_verify_t)(psa_drv_mac_transparent_context_t *p_context, + const uint8_t *p_mac, + size_t mac_length); /** \brief The function prototype for the abort operation for a previously * started transparent-key MAC operation @@ -364,7 +364,7 @@ typedef psa_status_t (*pcd_mac_transparent_finish_verify_t)(pcd_mac_transparent_ * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_mac_transparent___abort + * psa_drv_mac_transparent___abort * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) @@ -374,7 +374,7 @@ typedef psa_status_t (*pcd_mac_transparent_finish_verify_t)(pcd_mac_transparent_ * aborted * */ -typedef psa_status_t (*pcd_mac_transparent_abort_t)(pcd_mac_transparent_context_t *p_context); +typedef psa_status_t (*psa_drv_mac_transparent_abort_t)(psa_drv_mac_transparent_context_t *p_context); /** \brief The function prototype for a one-shot operation of a transparent-key * MAC operation @@ -382,7 +382,7 @@ typedef psa_status_t (*pcd_mac_transparent_abort_t)(pcd_mac_transparent_context_ * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_mac_transparent__ + * psa_drv_mac_transparent__ * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) @@ -397,13 +397,13 @@ typedef psa_status_t (*pcd_mac_transparent_abort_t)(pcd_mac_transparent_context_ * upon success * \param[in] mac_length The length in bytes of the `p_mac` buffer */ -typedef psa_status_t (*pcd_mac_transparent_t)(const uint8_t *p_input, - size_t input_length, - const uint8_t *p_key, - size_t key_length, - psa_algorithm_t alg, - uint8_t *p_mac, - size_t mac_length); +typedef psa_status_t (*psa_drv_mac_transparent_t)(const uint8_t *p_input, + size_t input_length, + const uint8_t *p_key, + size_t key_length, + psa_algorithm_t alg, + uint8_t *p_mac, + size_t mac_length); /** \brief The function prototype for a one-shot operation of a transparent-key * MAC Verify operation @@ -411,7 +411,7 @@ typedef psa_status_t (*pcd_mac_transparent_t)(const uint8_t *p_input, * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_mac_transparent___verify + * psa_drv_mac_transparent___verify * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is * the specific variant of a MAC operation (such as HMAC or CMAC) @@ -428,24 +428,24 @@ typedef psa_status_t (*pcd_mac_transparent_t)(const uint8_t *p_input, * \retval PSA_SUCCESS * The operation completed successfully and the comparison matched */ -typedef psa_status_t (*pcd_mac_transparent_verify_t)(const uint8_t *p_input, - size_t input_length, - const uint8_t *p_key, - size_t key_length, - psa_algorithm_t alg, - const uint8_t *p_mac, - size_t mac_length); +typedef psa_status_t (*psa_drv_mac_transparent_verify_t)(const uint8_t *p_input, + size_t input_length, + const uint8_t *p_key, + size_t key_length, + psa_algorithm_t alg, + const uint8_t *p_mac, + size_t mac_length); /**@}*/ /** \defgroup opaque_cipher Opaque Symmetric Ciphers * * Encryption and Decryption using opaque keys in block modes other than ECB * must be done in multiple parts, using the following flow: - * - `pcd_cipher_opaque_setup_t` - * - `pcd_cipher_opaque_set_iv_t` (optional depending upon block mode) - * - `pcd_cipher_opaque_update_t` + * - `psa_drv_cipher_opaque_setup_t` + * - `psa_drv_cipher_opaque_set_iv_t` (optional depending upon block mode) + * - `psa_drv_cipher_opaque_update_t` * - ... - * - `pcd_cipher_opaque_finish_t` + * - `psa_drv_cipher_opaque_finish_t` * If a previously started Opaque Cipher operation needs to be terminated, it * should be done so by the `psa_cipher_opaque_abort_t`. Failure to do so may @@ -454,7 +454,7 @@ typedef psa_status_t (*pcd_mac_transparent_verify_t)(const uint8_t *p_input, * * In situations where a PSA Cryptographic API implementation is using a block * mode not-supported by the underlying hardware or driver, it can construct - * the block mode itself, while calling the `pcd_cipher_opaque_ecb_t` function + * the block mode itself, while calling the `psa_drv_cipher_opaque_ecb_t` function * pointer for the cipher operations. */ /**@{*/ @@ -474,10 +474,10 @@ typedef psa_status_t (*pcd_mac_transparent_verify_t)(const uint8_t *p_input, * \retval PSA_SUCCESS * \retval PSA_ERROR_NOT_SUPPORTED */ -typedef psa_status_t (*pcd_cipher_opaque_setup_t)(void *p_context, - psa_key_slot_t key_slot, - psa_algorithm_t algorithm, - encrypt_or_decrypt_t direction); +typedef psa_status_t (*psa_drv_cipher_opaque_setup_t)(void *p_context, + psa_key_slot_t key_slot, + psa_algorithm_t algorithm, + encrypt_or_decrypt_t direction); /** \brief A function pointer that sets the initialization vector (if * necessary) for an opaque cipher operation @@ -494,9 +494,9 @@ typedef psa_status_t (*pcd_cipher_opaque_setup_t)(void *p_context, * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_cipher_opaque_set_iv_t)(void *p_context, - const uint8_t *p_iv, - size_t iv_length); +typedef psa_status_t (*psa_drv_cipher_opaque_set_iv_t)(void *p_context, + const uint8_t *p_iv, + size_t iv_length); /** \brief A function that continues a previously started opaque-key cipher * operation @@ -516,12 +516,12 @@ typedef psa_status_t (*pcd_cipher_opaque_set_iv_t)(void *p_context, * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_cipher_opaque_update_t)(void *p_context, - const uint8_t *p_input, - size_t input_size, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_cipher_opaque_update_t)(void *p_context, + const uint8_t *p_input, + size_t input_size, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** \brief A function that completes a previously started opaque-key cipher * operation @@ -537,10 +537,10 @@ typedef psa_status_t (*pcd_cipher_opaque_update_t)(void *p_context, * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_cipher_opaque_finish_t)(void *p_context, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_cipher_opaque_finish_t)(void *p_context, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** \brief A function that aborts a previously started opaque-key cipher * operation @@ -548,7 +548,7 @@ typedef psa_status_t (*pcd_cipher_opaque_finish_t)(void *p_context, * \param[in,out] p_context A hardware-specific structure for the * previously started cipher operation */ -typedef psa_status_t (*pcd_cipher_opaque_abort_t)(void *p_context); +typedef psa_status_t (*psa_drv_cipher_opaque_abort_t)(void *p_context); /** \brief A function that performs the ECB block mode for opaque-key cipher * operations @@ -572,13 +572,13 @@ typedef psa_status_t (*pcd_cipher_opaque_abort_t)(void *p_context); * \retval PSA_SUCCESS * \retval PSA_ERROR_NOT_SUPPORTED */ -typedef psa_status_t (*pcd_cipher_opaque_ecb_t)(psa_key_slot_t key_slot, - psa_algorithm_t algorithm, - encrypt_or_decrypt_t direction, - const uint8_t *p_input, - size_t input_size, - uint8_t *p_output, - size_t output_size); +typedef psa_status_t (*psa_drv_cipher_opaque_ecb_t)(psa_key_slot_t key_slot, + psa_algorithm_t algorithm, + encrypt_or_decrypt_t direction, + const uint8_t *p_input, + size_t input_size, + uint8_t *p_output, + size_t output_size); /** * \brief A struct containing all of the function pointers needed to implement @@ -588,28 +588,28 @@ typedef psa_status_t (*pcd_cipher_opaque_ecb_t)(psa_key_slot_t key_slot, * appropriate upon startup. * * If one of the functions is not implemented (such as - * `pcd_cipher_opaque_ecb_t`), it should be set to NULL. + * `psa_drv_cipher_opaque_ecb_t`), it should be set to NULL. */ -struct pcd_cipher_opaque_t { +struct psa_drv_cipher_opaque_t { /** The size in bytes of the hardware-specific Opaque Cipher context * structure */ - size_t size; + size_t size; /** Function that performs the setup operation */ - pcd_cipher_opaque_setup_t *p_setup; + psa_drv_cipher_opaque_setup_t *p_setup; /** Function that sets the IV (if necessary) */ - pcd_cipher_opaque_set_iv_t *p_set_iv; + psa_drv_cipher_opaque_set_iv_t *p_set_iv; /** Function that performs the update operation */ - pcd_cipher_opaque_update_t *p_update; + psa_drv_cipher_opaque_update_t *p_update; /** Function that completes the operation */ - pcd_cipher_opaque_finish_t *p_finish; + psa_drv_cipher_opaque_finish_t *p_finish; /** Function that aborts the operation */ - pcd_cipher_opaque_abort_t *p_abort; + psa_drv_cipher_opaque_abort_t *p_abort; /** Function that performs ECB mode for the cipher * (Danger: ECB mode should not be used directly by clients of the PSA * Crypto Client API) */ - pcd_cipher_opaque_ecb_t *p_ecb; + psa_drv_cipher_opaque_ecb_t *p_ecb; }; /**@}*/ @@ -617,11 +617,11 @@ struct pcd_cipher_opaque_t { /** \defgroup transparent_cipher Transparent Block Cipher * Encryption and Decryption using transparent keys in block modes other than * ECB must be done in multiple parts, using the following flow: - * - `pcd_cipher_transparent_setup_t` - * - `pcd_cipher_transparent_set_iv_t` (optional depending upon block mode) - * - `pcd_cipher_transparent_update_t` + * - `psa_drv_cipher_transparent_setup_t` + * - `psa_drv_cipher_transparent_set_iv_t` (optional depending upon block mode) + * - `psa_drv_cipher_transparent_update_t` * - ... - * - `pcd_cipher_transparent_finish_t` + * - `psa_drv_cipher_transparent_finish_t` * If a previously started Transparent Cipher operation needs to be terminated, * it should be done so by the `psa_cipher_transparent_abort_t`. Failure to do @@ -635,21 +635,21 @@ struct pcd_cipher_opaque_t { * The contents of this structure are implementation dependent and are * therefore not described here. */ -typedef struct pcd_cipher_transparent_context_s pcd_cipher_transparent_context_t; +typedef struct psa_drv_cipher_transparent_context_s psa_drv_cipher_transparent_context_t; /** \brief The function prototype for the setup operation of transparent-key * block cipher operations. * Functions that implement the prototype should be named in the following * conventions: * ~~~~~~~~~~~~~{.c} - * pcd_cipher_transparent_setup__ + * psa_drv_cipher_transparent_setup__ * ~~~~~~~~~~~~~ * Where * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR) * or for stream ciphers: * ~~~~~~~~~~~~~{.c} - * pcd_cipher_transparent_setup_ + * psa_drv_cipher_transparent_setup_ * ~~~~~~~~~~~~~ * Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4) * @@ -663,17 +663,17 @@ typedef struct pcd_cipher_transparent_context_s pcd_cipher_transparent_context_t * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_cipher_transparent_setup_t)(pcd_cipher_transparent_context_t *p_context, - encrypt_or_decrypt_t direction, - const uint8_t *p_key_data, - size_t key_data_size); +typedef psa_status_t (*psa_drv_cipher_transparent_setup_t)(psa_drv_cipher_transparent_context_t *p_context, + encrypt_or_decrypt_t direction, + const uint8_t *p_key_data, + size_t key_data_size); /** \brief The function prototype for the set initialization vector operation * of transparent-key block cipher operations * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_cipher_transparent_set_iv__ + * psa_drv_cipher_transparent_set_iv__ * ~~~~~~~~~~~~~ * Where * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) @@ -686,9 +686,9 @@ typedef psa_status_t (*pcd_cipher_transparent_setup_t)(pcd_cipher_transparent_co * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_cipher_transparent_set_iv_t)(pcd_cipher_transparent_context_t *p_context, - const uint8_t *p_iv, - size_t iv_length); +typedef psa_status_t (*psa_drv_cipher_transparent_set_iv_t)(psa_drv_cipher_transparent_context_t *p_context, + const uint8_t *p_iv, + size_t iv_length); /** \brief The function prototype for the update operation of transparent-key * block cipher operations. @@ -696,7 +696,7 @@ typedef psa_status_t (*pcd_cipher_transparent_set_iv_t)(pcd_cipher_transparent_c * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_cipher_transparent_update__ + * psa_drv_cipher_transparent_update__ * ~~~~~~~~~~~~~ * Where * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) @@ -715,12 +715,12 @@ typedef psa_status_t (*pcd_cipher_transparent_set_iv_t)(pcd_cipher_transparent_c * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_cipher_transparent_update_t)(pcd_cipher_transparent_context_t *p_context, - const uint8_t *p_input, - size_t input_size, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_cipher_transparent_update_t)(psa_drv_cipher_transparent_context_t *p_context, + const uint8_t *p_input, + size_t input_size, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** \brief The function prototype for the finish operation of transparent-key * block cipher operations. @@ -728,7 +728,7 @@ typedef psa_status_t (*pcd_cipher_transparent_update_t)(pcd_cipher_transparent_c * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_cipher_transparent_finish__ + * psa_drv_cipher_transparent_finish__ * ~~~~~~~~~~~~~ * Where * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) @@ -744,10 +744,10 @@ typedef psa_status_t (*pcd_cipher_transparent_update_t)(pcd_cipher_transparent_c * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_cipher_transparent_finish_t)(pcd_cipher_transparent_context_t *p_context, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_cipher_transparent_finish_t)(psa_drv_cipher_transparent_context_t *p_context, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** \brief The function prototype for the abort operation of transparent-key * block cipher operations. @@ -755,7 +755,7 @@ typedef psa_status_t (*pcd_cipher_transparent_finish_t)(pcd_cipher_transparent_c * Functions that implement the following prototype should be named in the * following convention: * ~~~~~~~~~~~~~{.c} - * pcd_cipher_transparent_abort__ + * psa_drv_cipher_transparent_abort__ * ~~~~~~~~~~~~~ * Where * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES) @@ -766,7 +766,7 @@ typedef psa_status_t (*pcd_cipher_transparent_finish_t)(pcd_cipher_transparent_c * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_cipher_transparent_abort_t)(pcd_cipher_transparent_context_t *p_context); +typedef psa_status_t (*psa_drv_cipher_transparent_abort_t)(psa_drv_cipher_transparent_context_t *p_context); /**@}*/ @@ -791,7 +791,7 @@ typedef psa_status_t (*pcd_cipher_transparent_abort_t)(pcd_cipher_transparent_co * The contents of this structure are implementation dependent and are * therefore not described here */ -typedef struct pcd_hash_context_s pcd_hash_context_t; +typedef struct psa_drv_hash_context_s psa_drv_hash_context_t; /** \brief The function prototype for the start operation of a hash (message * digest) operation @@ -799,7 +799,7 @@ typedef struct pcd_hash_context_s pcd_hash_context_t; * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_hash__setup + * psa_drv_hash__setup * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying hash function * @@ -808,7 +808,7 @@ typedef struct pcd_hash_context_s pcd_hash_context_t; * * \retval PSA_SUCCESS Success. */ -typedef psa_status_t (*pcd_hash_setup_t)(pcd_hash_context_t *p_context); +typedef psa_status_t (*psa_drv_hash_setup_t)(psa_drv_hash_context_t *p_context); /** \brief The function prototype for the update operation of a hash (message * digest) operation @@ -816,7 +816,7 @@ typedef psa_status_t (*pcd_hash_setup_t)(pcd_hash_context_t *p_context); * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_hash__update + * psa_drv_hash__update * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm * @@ -827,9 +827,9 @@ typedef psa_status_t (*pcd_hash_setup_t)(pcd_hash_context_t *p_context); * to the hash operation * \param[in] input_length The size in bytes of the input message buffer */ -typedef psa_status_t (*pcd_hash_update_t)(pcd_hash_context_t *p_context, - const uint8_t *p_input, - size_t input_length); +typedef psa_status_t (*psa_drv_hash_update_t)(psa_drv_hash_context_t *p_context, + const uint8_t *p_input, + size_t input_length); /** \brief The prototype for the finish operation of a hash (message digest) * operation @@ -837,7 +837,7 @@ typedef psa_status_t (*pcd_hash_update_t)(pcd_hash_context_t *p_context, * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_hash__finish + * psa_drv_hash__finish * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm * @@ -854,10 +854,10 @@ typedef psa_status_t (*pcd_hash_update_t)(pcd_hash_context_t *p_context, * \retval PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_hash_finish_t)(pcd_hash_context_t *p_context, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_hash_finish_t)(psa_drv_hash_context_t *p_context, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** \brief The function prototype for the abort operation of a hash (message * digest) operation @@ -865,14 +865,14 @@ typedef psa_status_t (*pcd_hash_finish_t)(pcd_hash_context_t *p_context, * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_hash__abort + * psa_drv_hash__abort * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the underlying algorithm * * \param[in,out] p_context A hardware-specific structure for the previously * started hash operation to be aborted */ -typedef void (*pcd_hash_abort_t)(pcd_hash_context_t *p_context); +typedef void (*psa_drv_hash_abort_t)(psa_drv_hash_context_t *p_context); /**@}*/ @@ -900,13 +900,13 @@ typedef void (*pcd_hash_abort_t)(pcd_hash_context_t *p_context); * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_asymmetric_opaque_sign_t)(psa_key_slot_t key_slot, - psa_algorithm_t alg, - const uint8_t *p_hash, - size_t hash_length, - uint8_t *p_signature, - size_t signature_size, - size_t *p_signature_length); +typedef psa_status_t (*psa_drv_asymmetric_opaque_sign_t)(psa_key_slot_t key_slot, + psa_algorithm_t alg, + const uint8_t *p_hash, + size_t hash_length, + uint8_t *p_signature, + size_t signature_size, + size_t *p_signature_length); /** * \brief A function that verifies the signature a hash or short message using @@ -924,12 +924,12 @@ typedef psa_status_t (*pcd_asymmetric_opaque_sign_t)(psa_key_slot_t key_slot, * \retval PSA_SUCCESS * The signature is valid. */ -typedef psa_status_t (*pcd_asymmetric_opaque_verify_t)(psa_key_slot_t key_slot, - psa_algorithm_t alg, - const uint8_t *p_hash, - size_t hash_length, - const uint8_t *p_signature, - size_t signature_length); +typedef psa_status_t (*psa_drv_asymmetric_opaque_verify_t)(psa_key_slot_t key_slot, + psa_algorithm_t alg, + const uint8_t *p_hash, + size_t hash_length, + const uint8_t *p_signature, + size_t signature_length); /** * \brief A function that encrypts a short message with an asymmetric public @@ -960,15 +960,15 @@ typedef psa_status_t (*pcd_asymmetric_opaque_verify_t)(psa_key_slot_t key_slot, * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_asymmetric_opaque_encrypt_t)(psa_key_slot_t key_slot, - psa_algorithm_t alg, - const uint8_t *p_input, - size_t input_length, - const uint8_t *p_salt, - size_t salt_length, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_asymmetric_opaque_encrypt_t)(psa_key_slot_t key_slot, + psa_algorithm_t alg, + const uint8_t *p_input, + size_t input_length, + const uint8_t *p_salt, + size_t salt_length, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** * \brief Decrypt a short message with an asymmetric private key. @@ -997,15 +997,15 @@ typedef psa_status_t (*pcd_asymmetric_opaque_encrypt_t)(psa_key_slot_t key_slot, * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_asymmetric_opaque_decrypt_t)(psa_key_slot_t key_slot, - psa_algorithm_t alg, - const uint8_t *p_input, - size_t input_length, - const uint8_t *p_salt, - size_t salt_length, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_asymmetric_opaque_decrypt_t)(psa_key_slot_t key_slot, + psa_algorithm_t alg, + const uint8_t *p_input, + size_t input_length, + const uint8_t *p_salt, + size_t salt_length, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** * \brief A struct containing all of the function pointers needed to implement @@ -1016,15 +1016,15 @@ typedef psa_status_t (*pcd_asymmetric_opaque_decrypt_t)(psa_key_slot_t key_slot, * * If one of the functions is not implemented, it should be set to NULL. */ -struct pcd_asymmetric_opaque_t { +struct psa_drv_asymmetric_opaque_t { /** Function that performs the asymmetric sign operation */ - pcd_asymmetric_opaque_sign_t *p_sign; + psa_drv_asymmetric_opaque_sign_t *p_sign; /** Function that performs the asymmetric verify operation */ - pcd_asymmetric_opaque_verify_t *p_verify; + psa_drv_asymmetric_opaque_verify_t *p_verify; /** Function that performs the asymmetric encrypt operation */ - pcd_asymmetric_opaque_encrypt_t *p_encrypt; + psa_drv_asymmetric_opaque_encrypt_t *p_encrypt; /** Function that performs the asymmetric decrypt operation */ - pcd_asymmetric_opaque_decrypt_t *p_decrypt; + psa_drv_asymmetric_opaque_decrypt_t *p_decrypt; }; /**@}*/ @@ -1045,7 +1045,7 @@ struct pcd_asymmetric_opaque_t { * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_asymmetric__sign + * psa_drv_asymmetric__sign * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the signing algorithm * @@ -1063,14 +1063,14 @@ struct pcd_asymmetric_opaque_t { * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_asymmetric_transparent_sign_t)(const uint8_t *p_key, - size_t key_size, - psa_algorithm_t alg, - const uint8_t *p_hash, - size_t hash_length, - uint8_t *p_signature, - size_t signature_size, - size_t *p_signature_length); +typedef psa_status_t (*psa_drv_asymmetric_transparent_sign_t)(const uint8_t *p_key, + size_t key_size, + psa_algorithm_t alg, + const uint8_t *p_hash, + size_t hash_length, + uint8_t *p_signature, + size_t signature_size, + size_t *p_signature_length); /** * \brief A function that verifies the signature a hash or short message using @@ -1079,7 +1079,7 @@ typedef psa_status_t (*pcd_asymmetric_transparent_sign_t)(const uint8_t *p_key, * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_asymmetric__verify + * psa_drv_asymmetric__verify * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the signing algorithm * @@ -1096,13 +1096,13 @@ typedef psa_status_t (*pcd_asymmetric_transparent_sign_t)(const uint8_t *p_key, * \retval PSA_SUCCESS * The signature is valid. */ -typedef psa_status_t (*pcd_asymmetric_transparent_verify_t)(const uint8_t *p_key, - size_t key_size, - psa_algorithm_t alg, - const uint8_t *p_hash, - size_t hash_length, - const uint8_t *p_signature, - size_t signature_length); +typedef psa_status_t (*psa_drv_asymmetric_transparent_verify_t)(const uint8_t *p_key, + size_t key_size, + psa_algorithm_t alg, + const uint8_t *p_hash, + size_t hash_length, + const uint8_t *p_signature, + size_t signature_length); /** * \brief A function that encrypts a short message with a transparent @@ -1111,7 +1111,7 @@ typedef psa_status_t (*pcd_asymmetric_transparent_verify_t)(const uint8_t *p_key * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_asymmetric__encrypt + * psa_drv_asymmetric__encrypt * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the encryption algorithm * @@ -1140,16 +1140,16 @@ typedef psa_status_t (*pcd_asymmetric_transparent_verify_t)(const uint8_t *p_key * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_asymmetric_transparent_encrypt_t)(const uint8_t *p_key, - size_t key_size, - psa_algorithm_t alg, - const uint8_t *p_input, - size_t input_length, - const uint8_t *p_salt, - size_t salt_length, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_asymmetric_transparent_encrypt_t)(const uint8_t *p_key, + size_t key_size, + psa_algorithm_t alg, + const uint8_t *p_input, + size_t input_length, + const uint8_t *p_salt, + size_t salt_length, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** * \brief Decrypt a short message with a transparent asymmetric private key @@ -1157,7 +1157,7 @@ typedef psa_status_t (*pcd_asymmetric_transparent_encrypt_t)(const uint8_t *p_ke * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_asymmetric__decrypt + * psa_drv_asymmetric__decrypt * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the encryption algorithm * @@ -1186,16 +1186,16 @@ typedef psa_status_t (*pcd_asymmetric_transparent_encrypt_t)(const uint8_t *p_ke * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_asymmetric_transparent_decrypt_t)(const uint8_t *p_key, - size_t key_size, - psa_algorithm_t alg, - const uint8_t *p_input, - size_t input_length, - const uint8_t *p_salt, - size_t salt_length, - uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_asymmetric_transparent_decrypt_t)(const uint8_t *p_key, + size_t key_size, + psa_algorithm_t alg, + const uint8_t *p_input, + size_t input_length, + const uint8_t *p_salt, + size_t salt_length, + uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /**@}*/ @@ -1237,17 +1237,17 @@ typedef psa_status_t (*pcd_asymmetric_transparent_decrypt_t)(const uint8_t *p_ke * \retval #PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_aead_opaque_encrypt_t)(psa_key_slot_t key_slot, - psa_algorithm_t algorithm, - const uint8_t *p_nonce, - size_t nonce_length, - const uint8_t *p_additional_data, - size_t additional_data_length, - const uint8_t *p_plaintext, - size_t plaintext_length, - uint8_t *p_ciphertext, - size_t ciphertext_size, - size_t *p_ciphertext_length); +typedef psa_status_t (*psa_drv_aead_opaque_encrypt_t)(psa_key_slot_t key_slot, + psa_algorithm_t algorithm, + const uint8_t *p_nonce, + size_t nonce_length, + const uint8_t *p_additional_data, + size_t additional_data_length, + const uint8_t *p_plaintext, + size_t plaintext_length, + uint8_t *p_ciphertext, + size_t ciphertext_size, + size_t *p_ciphertext_length); /** Process an authenticated decryption operation using an opaque key * @@ -1277,17 +1277,17 @@ typedef psa_status_t (*pcd_aead_opaque_encrypt_t)(psa_key_slot_t key_slot, * \retval #PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_aead_opaque_decrypt_t)(psa_key_slot_t key_slot, - psa_algorithm_t algorithm, - const uint8_t *p_nonce, - size_t nonce_length, - const uint8_t *p_additional_data, - size_t additional_data_length, - const uint8_t *p_ciphertext, - size_t ciphertext_length, - uint8_t *p_plaintext, - size_t plaintext_size, - size_t *p_plaintext_length); +typedef psa_status_t (*psa_drv_aead_opaque_decrypt_t)(psa_key_slot_t key_slot, + psa_algorithm_t algorithm, + const uint8_t *p_nonce, + size_t nonce_length, + const uint8_t *p_additional_data, + size_t additional_data_length, + const uint8_t *p_ciphertext, + size_t ciphertext_length, + uint8_t *p_plaintext, + size_t plaintext_size, + size_t *p_plaintext_length); /** * \brief A struct containing all of the function pointers needed to implement @@ -1298,11 +1298,11 @@ typedef psa_status_t (*pcd_aead_opaque_decrypt_t)(psa_key_slot_t key_slot, * * If one of the functions is not implemented, it should be set to NULL. */ -struct pcd_aead_opaque_t { +struct psa_drv_aead_opaque_t { /** Function that performs the AEAD encrypt operation */ - pcd_aead_opaque_encrypt_t *p_encrypt; + psa_drv_aead_opaque_encrypt_t *p_encrypt; /** Function that performs the AEAD decrypt operation */ - pcd_aead_opaque_decrypt_t *p_decrypt; + psa_drv_aead_opaque_decrypt_t *p_decrypt; }; /**@}*/ @@ -1322,7 +1322,7 @@ struct pcd_aead_opaque_t { * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_aead__encrypt + * psa_drv_aead__encrypt * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the AEAD algorithm * @@ -1357,25 +1357,25 @@ struct pcd_aead_opaque_t { * \retval #PSA_SUCCESS */ -typedef psa_status_t (*pcd_aead_transparent_encrypt_t)(const uint8_t *p_key, - size_t key_length, - psa_algorithm_t alg, - const uint8_t *nonce, - size_t nonce_length, - const uint8_t *additional_data, - size_t additional_data_length, - const uint8_t *plaintext, - size_t plaintext_length, - uint8_t *ciphertext, - size_t ciphertext_size, - size_t *ciphertext_length); +typedef psa_status_t (*psa_drv_aead_transparent_encrypt_t)(const uint8_t *p_key, + size_t key_length, + psa_algorithm_t alg, + const uint8_t *nonce, + size_t nonce_length, + const uint8_t *additional_data, + size_t additional_data_length, + const uint8_t *plaintext, + size_t plaintext_length, + uint8_t *ciphertext, + size_t ciphertext_size, + size_t *ciphertext_length); /** Process an authenticated decryption operation using an opaque key. * * Functions that implement the prototype should be named in the following * convention: * ~~~~~~~~~~~~~{.c} - * pcd_aead__decrypt + * psa_drv_aead__decrypt * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the AEAD algorithm * \param[in] p_key A pointer to the key material @@ -1408,18 +1408,18 @@ typedef psa_status_t (*pcd_aead_transparent_encrypt_t)(const uint8_t *p_key, * \retval #PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_aead_transparent_decrypt_t)(const uint8_t *p_key, - size_t key_length, - psa_algorithm_t alg, - const uint8_t *nonce, - size_t nonce_length, - const uint8_t *additional_data, - size_t additional_data_length, - const uint8_t *ciphertext, - size_t ciphertext_length, - uint8_t *plaintext, - size_t plaintext_size, - size_t *plaintext_length); +typedef psa_status_t (*psa_drv_aead_transparent_decrypt_t)(const uint8_t *p_key, + size_t key_length, + psa_algorithm_t alg, + const uint8_t *nonce, + size_t nonce_length, + const uint8_t *additional_data, + size_t additional_data_length, + const uint8_t *ciphertext, + size_t ciphertext_length, + uint8_t *plaintext, + size_t plaintext_size, + size_t *plaintext_length); /**@}*/ @@ -1430,7 +1430,7 @@ typedef psa_status_t (*pcd_aead_transparent_decrypt_t)(const uint8_t *p_key, /** \brief A hardware-specific structure for a entropy providing hardware */ -typedef struct pcd_entropy_context_s pcd_entropy_context_t; +typedef struct psa_drv_entropy_context_s psa_drv_entropy_context_t; /** \brief Initialize an entropy driver * @@ -1441,7 +1441,7 @@ typedef struct pcd_entropy_context_s pcd_entropy_context_t; * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_entropy_init_t)(pcd_entropy_context_t *p_context); +typedef psa_status_t (*psa_drv_entropy_init_t)(psa_drv_entropy_context_t *p_context); /** \brief Get a specified number of bits from the entropy source * @@ -1469,10 +1469,10 @@ typedef psa_status_t (*pcd_entropy_init_t)(pcd_entropy_context_t *p_context); * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_entropy_get_bits_t)(pcd_entropy_context_t *p_context, - uint8_t *p_buffer, - uint32_t buffer_size, - uint32_t *p_received_entropy_bits); +typedef psa_status_t (*psa_drv_entropy_get_bits_t)(psa_drv_entropy_context_t *p_context, + uint8_t *p_buffer, + uint32_t buffer_size, + uint32_t *p_received_entropy_bits); /** * \brief A struct containing all of the function pointers needed to interface @@ -1483,12 +1483,12 @@ typedef psa_status_t (*pcd_entropy_get_bits_t)(pcd_entropy_context_t *p_context, * * If one of the functions is not implemented, it should be set to NULL. */ -struct pcd_entropy_t { +struct psa_drv_entropy_t { /** Function that performs initialization for the entropy source */ - pcd_entropy_init_t *p_init; + psa_drv_entropy_init_t *p_init; /** Function that performs the get_bits operation for the entropy source */ - pcd_entropy_get_bits_t *p_get_bits; + psa_drv_entropy_get_bits_t *p_get_bits; }; /**@}*/ @@ -1517,12 +1517,12 @@ struct pcd_entropy_t { * \retval #PSA_SUCCESS * Success. */ -typedef psa_status_t (*pcd_opaque_import_key_t)(psa_key_slot_t key_slot, - psa_key_type_t type, - psa_algorithm_t algorithm, - psa_key_usage_t usage, - const uint8_t *p_data, - size_t data_length); +typedef psa_status_t (*psa_drv_opaque_import_key_t)(psa_key_slot_t key_slot, + psa_key_type_t type, + psa_algorithm_t algorithm, + psa_key_usage_t usage, + const uint8_t *p_data, + size_t data_length); /** * \brief Destroy a key and restore the slot to its default state @@ -1540,7 +1540,7 @@ typedef psa_status_t (*pcd_opaque_import_key_t)(psa_key_slot_t key_slot, * \retval #PSA_SUCCESS * The slot's content, if any, has been erased. */ -typedef psa_status_t (*pcd_destroy_key_t)(psa_key_slot_t key); +typedef psa_status_t (*psa_drv_destroy_key_t)(psa_key_slot_t key); /** * \brief Export a key in binary format @@ -1582,10 +1582,10 @@ typedef psa_status_t (*pcd_destroy_key_t)(psa_key_slot_t key); * \retval #PSA_ERROR_HARDWARE_FAILURE * \retval #PSA_ERROR_TAMPERING_DETECTED */ -typedef psa_status_t (*pcd_export_key_t)(psa_key_slot_t key, - uint8_t *p_data, - size_t data_size, - size_t *p_data_length); +typedef psa_status_t (*psa_drv_export_key_t)(psa_key_slot_t key, + uint8_t *p_data, + size_t data_size, + size_t *p_data_length); /** * \brief Export a public key or the public part of a key pair in binary format @@ -1608,10 +1608,10 @@ typedef psa_status_t (*pcd_export_key_t)(psa_key_slot_t key, * * \retval #PSA_SUCCESS */ -typedef psa_status_t (*pcd_export_public_key_t)(psa_key_slot_t key, - uint8_t *p_data, - size_t data_size, - size_t *p_data_length); +typedef psa_status_t (*psa_drv_export_public_key_t)(psa_key_slot_t key, + uint8_t *p_data, + size_t data_size, + size_t *p_data_length); /** * \brief A struct containing all of the function pointers needed to for key @@ -1622,15 +1622,15 @@ typedef psa_status_t (*pcd_export_public_key_t)(psa_key_slot_t key, * * If one of the functions is not implemented, it should be set to NULL. */ -struct pcd_key_management_t { +struct psa_drv_key_management_t { /** Function that performs the key import operation */ - pcd_opaque_import_key_t *p_import; + psa_drv_opaque_import_key_t *p_import; /** Function that performs the key destroy operation */ - pcd_destroy_key_t *p_destroy; + psa_drv_destroy_key_t *p_destroy; /** Function that performs the key export operation */ - pcd_export_key_t *p_export; + psa_drv_export_key_t *p_export; /** Function that perforsm the public key export operation */ - pcd_export_public_key_t *p_export_public; + psa_drv_export_public_key_t *p_export_public; }; /**@}*/ @@ -1646,40 +1646,40 @@ struct pcd_key_management_t { * for both of the flows. * * There are two different final functions for the flows, - * `pcd_key_derivation_derive` and `pcd_key_derivation_export`. - * `pcd_key_derivation_derive` is used when the key material should be placed + * `psa_drv_key_derivation_derive` and `psa_drv_key_derivation_export`. + * `psa_drv_key_derivation_derive` is used when the key material should be placed * in a slot on the hardware and not exposed to the caller. - * `pcd_key_derivation_export` is used when the key material should be returned + * `psa_drv_key_derivation_export` is used when the key material should be returned * to the PSA Cryptographic API implementation. * * Different key derivation algorithms require a different number of inputs. * Instead of having an API that takes as input variable length arrays, which * can be problemmatic to manage on embedded platforms, the inputs are passed - * to the driver via a function, `pcd_key_derivation_collateral`, that is + * to the driver via a function, `psa_drv_key_derivation_collateral`, that is * called multiple times with different `collateral_id`s. Thus, for a key * derivation algorithm that required 3 paramter inputs, the flow would look * something like: * ~~~~~~~~~~~~~{.c} - * pcd_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes); - * pcd_key_derivation_collateral(kdf_algorithm_collateral_id_0, - * p_collateral_0, - * collateral_0_size); - * pcd_key_derivation_collateral(kdf_algorithm_collateral_id_1, - * p_collateral_1, - * collateral_1_size); - * pcd_key_derivation_collateral(kdf_algorithm_collateral_id_2, - * p_collateral_2, - * collateral_2_size); - * pcd_key_derivation_derive(); + * psa_drv_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes); + * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_0, + * p_collateral_0, + * collateral_0_size); + * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_1, + * p_collateral_1, + * collateral_1_size); + * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_2, + * p_collateral_2, + * collateral_2_size); + * psa_drv_key_derivation_derive(); * ~~~~~~~~~~~~~ * * key agreement example: * ~~~~~~~~~~~~~{.c} - * pcd_key_derivation_setup(alg, source_key. dest_key_size_bytes); - * pcd_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size); - * pcd_key_derivation_export(p_session_key, - * session_key_size, - * &session_key_length); + * psa_drv_key_derivation_setup(alg, source_key. dest_key_size_bytes); + * psa_drv_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size); + * psa_drv_key_derivation_export(p_session_key, + * session_key_size, + * &session_key_length); * ~~~~~~~~~~~~~ */ /**@{*/ @@ -1689,7 +1689,7 @@ struct pcd_key_management_t { * The contents of this structure are implementation dependent and are * therefore not described here */ -typedef struct pcd_key_derivation_context_s pcd_key_derivation_context_t; +typedef struct psa_drv_key_derivation_context_s psa_drv_key_derivation_context_t; /** \brief Set up a key derivation operation by specifying the algorithm and * the source key sot @@ -1702,9 +1702,9 @@ typedef struct pcd_key_derivation_context_s pcd_key_derivation_context_t; * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_key_derivation_setup_t)(pcd_key_derivation_context_t *p_context, - psa_algorithm_t kdf_alg, - psa_key_slot_t source_key); +typedef psa_status_t (*psa_drv_key_derivation_setup_t)(psa_drv_key_derivation_context_t *p_context, + psa_algorithm_t kdf_alg, + psa_key_slot_t source_key); /** \brief Provide collateral (parameters) needed for a key derivation or key * agreement operation @@ -1721,10 +1721,10 @@ typedef psa_status_t (*pcd_key_derivation_setup_t)(pcd_key_derivation_context_t * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_key_derivation_collateral_t)(pcd_key_derivation_context_t *p_context, - uint32_t collateral_id, - const uint8_t *p_collateral, - size_t collateral_size); +typedef psa_status_t (*psa_drv_key_derivation_collateral_t)(psa_drv_key_derivation_context_t *p_context, + uint32_t collateral_id, + const uint8_t *p_collateral, + size_t collateral_size); /** \brief Perform the final key derivation step and place the generated key * material in a slot @@ -1735,8 +1735,8 @@ typedef psa_status_t (*pcd_key_derivation_collateral_t)(pcd_key_derivation_conte * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_key_derivation_derive_t)(pcd_key_derivation_context_t *p_context, - psa_key_slot_t dest_key); +typedef psa_status_t (*psa_drv_key_derivation_derive_t)(psa_drv_key_derivation_context_t *p_context, + psa_key_slot_t dest_key); /** \brief Perform the final step of a key agreement and place the generated * key material in a buffer @@ -1749,9 +1749,9 @@ typedef psa_status_t (*pcd_key_derivation_derive_t)(pcd_key_derivation_context_t * * \retval PSA_SUCCESS */ -typedef psa_status_t (*pcd_key_derivation_export_t)(uint8_t *p_output, - size_t output_size, - size_t *p_output_length); +typedef psa_status_t (*psa_drv_key_derivation_export_t)(uint8_t *p_output, + size_t output_size, + size_t *p_output_length); /** * \brief A struct containing all of the function pointers needed to for key @@ -1762,16 +1762,16 @@ typedef psa_status_t (*pcd_key_derivation_export_t)(uint8_t *p_output, * * If one of the functions is not implemented, it should be set to NULL. */ -struct pcd_key_derivation_t { +struct psa_drv_key_derivation_t { /** Function that performs the key derivation setup */ - pcd_key_derivation_setup_t *p_setup; + psa_drv_key_derivation_setup_t *p_setup; /** Function that sets the key derivation collateral */ - pcd_key_derivation_collateral_t *p_collateral; + psa_drv_key_derivation_collateral_t *p_collateral; /** Function that performs the final key derivation step */ - pcd_key_derivation_derive_t *p_derive; + psa_drv_key_derivation_derive_t *p_derive; /** Function that perforsm the final key derivation or agreement and * exports the key */ - pcd_key_derivation_export_t *p_export; + psa_drv_key_derivation_export_t *p_export; }; /**@}*/ From 7632f628d7b336c51a6fd396fc088630f1babea0 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 11:26:45 +0100 Subject: [PATCH 07/10] psa: driver: Prefix "encrypt or decrypt" type The driver model's "encrypt or decrypt" type, encrypt_or_decrypt_t, is publicly exposed and needs to have a `psa_` prefix in order to properly communicate that it is part of the PSA driver model. --- include/psa/crypto_driver.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index 9acd33066..25cbf3ed4 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -37,7 +37,7 @@ */ typedef uint32_t psa_status_t; typedef uint32_t psa_algorithm_t; -typedef uint8_t encrypt_or_decrypt_t; +typedef uint8_t psa_encrypt_or_decrypt_t; typedef uint32_t psa_key_slot_t; typedef uint32_t psa_key_type_t; typedef uint32_t psa_key_usage_t; @@ -477,7 +477,7 @@ typedef psa_status_t (*psa_drv_mac_transparent_verify_t)(const uint8_t *p_input, typedef psa_status_t (*psa_drv_cipher_opaque_setup_t)(void *p_context, psa_key_slot_t key_slot, psa_algorithm_t algorithm, - encrypt_or_decrypt_t direction); + psa_encrypt_or_decrypt_t direction); /** \brief A function pointer that sets the initialization vector (if * necessary) for an opaque cipher operation @@ -574,7 +574,7 @@ typedef psa_status_t (*psa_drv_cipher_opaque_abort_t)(void *p_context); */ typedef psa_status_t (*psa_drv_cipher_opaque_ecb_t)(psa_key_slot_t key_slot, psa_algorithm_t algorithm, - encrypt_or_decrypt_t direction, + psa_encrypt_or_decrypt_t direction, const uint8_t *p_input, size_t input_size, uint8_t *p_output, @@ -664,7 +664,7 @@ typedef struct psa_drv_cipher_transparent_context_s psa_drv_cipher_transparent_c * \retval PSA_SUCCESS */ typedef psa_status_t (*psa_drv_cipher_transparent_setup_t)(psa_drv_cipher_transparent_context_t *p_context, - encrypt_or_decrypt_t direction, + psa_encrypt_or_decrypt_t direction, const uint8_t *p_key_data, size_t key_data_size); From 4155850dd9283acfde4124c669042ed54c019631 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 11:44:33 +0100 Subject: [PATCH 08/10] psa: driver: Use header guard style consistently The file crypto_driver.h was not using the header guard style as other PSA Crypto header files. Remove the `__` prefix and suffix. Use C-style comments for the end-of-guard comment. --- include/psa/crypto_driver.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index 25cbf3ed4..006453151 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -25,8 +25,8 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -#ifndef __PSA_CRYPTO_DRIVER_H__ -#define __PSA_CRYPTO_DRIVER_H__ +#ifndef PSA_CRYPTO_DRIVER_H +#define PSA_CRYPTO_DRIVER_H #include #include @@ -1776,4 +1776,4 @@ struct psa_drv_key_derivation_t { /**@}*/ -#endif // __PSA_CRYPTO_DRIVER_H__ +#endif /* PSA_CRYPTO_DRIVER_H */ From 20b8a4f2ffb9d794b517ad69a971515e68307c08 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 11:57:26 +0100 Subject: [PATCH 09/10] psa: driver: Convert struct types to typedefs Convert PSA Crypto driver model structs to typedefs so that the `struct` name doesn't need to be used and for consistent style with other PSA structures. --- include/psa/crypto_driver.h | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index 006453151..f6fe04835 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -207,7 +207,7 @@ typedef psa_status_t (*psa_drv_mac_opaque_verify_t)(const uint8_t *p_input, * `p_update` and at least one of `p_finish` or `p_finish_verify`). * */ -struct psa_drv_mac_opaque_t { +typedef struct { /**The size in bytes of the hardware-specific Opaque-MAC Context structure */ size_t context_size; @@ -232,7 +232,7 @@ struct psa_drv_mac_opaque_t { /** Function that performs the MAC and verify operation in one call */ psa_drv_mac_opaque_verify_t *p_mac_verify; -}; +} psa_drv_mac_opaque_t; /**@}*/ /** \defgroup transparent_mac Transparent Message Authentication Code @@ -590,7 +590,7 @@ typedef psa_status_t (*psa_drv_cipher_opaque_ecb_t)(psa_key_slot_t key_slot, * If one of the functions is not implemented (such as * `psa_drv_cipher_opaque_ecb_t`), it should be set to NULL. */ -struct psa_drv_cipher_opaque_t { +typedef struct { /** The size in bytes of the hardware-specific Opaque Cipher context * structure */ @@ -610,7 +610,7 @@ struct psa_drv_cipher_opaque_t { * Crypto Client API) */ psa_drv_cipher_opaque_ecb_t *p_ecb; -}; +} psa_drv_cipher_opaque_t; /**@}*/ @@ -1016,7 +1016,7 @@ typedef psa_status_t (*psa_drv_asymmetric_opaque_decrypt_t)(psa_key_slot_t key_s * * If one of the functions is not implemented, it should be set to NULL. */ -struct psa_drv_asymmetric_opaque_t { +typedef struct { /** Function that performs the asymmetric sign operation */ psa_drv_asymmetric_opaque_sign_t *p_sign; /** Function that performs the asymmetric verify operation */ @@ -1025,7 +1025,7 @@ struct psa_drv_asymmetric_opaque_t { psa_drv_asymmetric_opaque_encrypt_t *p_encrypt; /** Function that performs the asymmetric decrypt operation */ psa_drv_asymmetric_opaque_decrypt_t *p_decrypt; -}; +} psa_drv_asymmetric_opaque_t; /**@}*/ @@ -1298,12 +1298,12 @@ typedef psa_status_t (*psa_drv_aead_opaque_decrypt_t)(psa_key_slot_t key_slot, * * If one of the functions is not implemented, it should be set to NULL. */ -struct psa_drv_aead_opaque_t { +typedef struct { /** Function that performs the AEAD encrypt operation */ psa_drv_aead_opaque_encrypt_t *p_encrypt; /** Function that performs the AEAD decrypt operation */ psa_drv_aead_opaque_decrypt_t *p_decrypt; -}; +} psa_drv_aead_opaque_t; /**@}*/ /** \defgroup aead_transparent AEAD Transparent @@ -1483,13 +1483,13 @@ typedef psa_status_t (*psa_drv_entropy_get_bits_t)(psa_drv_entropy_context_t *p_ * * If one of the functions is not implemented, it should be set to NULL. */ -struct psa_drv_entropy_t { +typedef struct { /** Function that performs initialization for the entropy source */ psa_drv_entropy_init_t *p_init; /** Function that performs the get_bits operation for the entropy source */ psa_drv_entropy_get_bits_t *p_get_bits; -}; +} psa_drv_entropy_t; /**@}*/ /** \defgroup driver_key_management Key Management @@ -1622,7 +1622,7 @@ typedef psa_status_t (*psa_drv_export_public_key_t)(psa_key_slot_t key, * * If one of the functions is not implemented, it should be set to NULL. */ -struct psa_drv_key_management_t { +typedef struct { /** Function that performs the key import operation */ psa_drv_opaque_import_key_t *p_import; /** Function that performs the key destroy operation */ @@ -1631,7 +1631,7 @@ struct psa_drv_key_management_t { psa_drv_export_key_t *p_export; /** Function that perforsm the public key export operation */ psa_drv_export_public_key_t *p_export_public; -}; +} psa_drv_key_management_t; /**@}*/ @@ -1762,7 +1762,7 @@ typedef psa_status_t (*psa_drv_key_derivation_export_t)(uint8_t *p_output, * * If one of the functions is not implemented, it should be set to NULL. */ -struct psa_drv_key_derivation_t { +typedef struct { /** Function that performs the key derivation setup */ psa_drv_key_derivation_setup_t *p_setup; /** Function that sets the key derivation collateral */ @@ -1772,7 +1772,7 @@ struct psa_drv_key_derivation_t { /** Function that perforsm the final key derivation or agreement and * exports the key */ psa_drv_key_derivation_export_t *p_export; -}; +} psa_drv_key_derivation_t; /**@}*/ From 9411db74c4917490ff02eebf298b70cbcba6d918 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Fri, 26 Oct 2018 11:59:58 +0100 Subject: [PATCH 10/10] psa: driver: Wrap types and symbols for C/C++ use Add extern "C" wrappers around type and function declarations to enable C++ interoperability of the driver header. This is done so that the driver functions and types can be used or implmented by C++ code. --- include/psa/crypto_driver.h | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index f6fe04835..b2e3a1d5f 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -31,6 +31,10 @@ #include #include +#ifdef __cplusplus +extern "C" { +#endif + /** The following types are redefinitions from the psa/crypto.h file. * It is intended that these will be moved to a new common header file to * avoid duplication. They are included here for expediency in publication. @@ -1776,4 +1780,8 @@ typedef struct { /**@}*/ +#ifdef __cplusplus +} +#endif + #endif /* PSA_CRYPTO_DRIVER_H */