diff --git a/include/psa/crypto_driver.h b/include/psa/crypto_driver.h index d2008b7c3..b2e3a1d5f 100644 --- a/include/psa/crypto_driver.h +++ b/include/psa/crypto_driver.h @@ -1,11 +1,12 @@ /** * \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. */ /* @@ -24,19 +25,23 @@ * 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 +#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 + * 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; 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; @@ -46,41 +51,41 @@ 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 + * opaque keys can be done either as a single function call (via the + * `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` * - `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. */ -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 - * + * * \param[in,out] p_context A hardware-specific structure for the * previously-established MAC operation to be * continued @@ -88,15 +93,15 @@ 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 - * - * \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,24 +109,24 @@ 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. */ -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 - * + * * \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 @@ -129,20 +134,20 @@ 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 - * + * * \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,21 +158,21 @@ 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. */ -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 - * + * * \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 +181,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 @@ -184,72 +189,72 @@ 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. - * + * * 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. - * + * `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 * (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 { +typedef struct { /**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; +} psa_drv_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 - * `pcd_mac_transparent_generate_t` or `psa_mac_transparent_verify_t` + * transparent keys can be done either as a single function call (via the + * `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` * - `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. - * + * */ /**@{*/ @@ -258,31 +263,31 @@ 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 - * + * * 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) - * - * \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. */ -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 @@ -290,11 +295,11 @@ 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) - * + * * \param[in,out] p_context A hardware-specific structure for the * previously-established MAC operation to be * continued @@ -302,46 +307,46 @@ 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 - * + * * 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) - * + * * \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. */ -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 - * + * * 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) - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started MAC operation to be * verified and finished @@ -349,43 +354,43 @@ 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 */ -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 - * + * * 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) - * + * * \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); +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 - * + * * 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 + * 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 @@ -396,25 +401,25 @@ 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 - * + * * 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) - * + * * \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,37 +428,37 @@ 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 */ -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 + * 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 + * the block mode itself, while calling the `psa_drv_cipher_opaque_ecb_t` function * pointer for the cipher operations. */ /**@{*/ @@ -469,37 +474,37 @@ 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 */ -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, + psa_encrypt_or_decrypt_t direction); /** \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. - * + * 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 * \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, - 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 - * + * * \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,15 +517,15 @@ 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, - 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 @@ -533,13 +538,13 @@ 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, - 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 @@ -547,14 +552,14 @@ 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 - * + * * 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,60 +572,60 @@ 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 */ -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, + psa_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 * 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. + * `psa_drv_cipher_opaque_ecb_t`), it should be set to NULL. */ -struct pcd_cipher_opaque_t { +typedef struct { /** 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; +} psa_drv_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 @@ -630,28 +635,28 @@ 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. */ -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) - * + * * \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,35 +664,35 @@ 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, - 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, + psa_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) * - `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, - 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. @@ -695,12 +700,12 @@ 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) * - `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,23 +716,23 @@ 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, - 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. -* + * * 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) @@ -740,44 +745,44 @@ 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, - 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. - * + * * 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) * - `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); +typedef psa_status_t (*psa_drv_cipher_transparent_abort_t)(psa_drv_cipher_transparent_context_t *p_context); /**@}*/ /** \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,28 +791,28 @@ 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 */ -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 - * + * * 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 - * + * * \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); +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 @@ -815,10 +820,10 @@ 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 - * + * * \param[in,out] p_context A hardware-specific structure for the * previously-established hash operation to be * continued @@ -826,20 +831,20 @@ 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 - * + * * 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 - * + * * \param[in,out] p_context A hardware-specific structure for the * previously started hash operation to be * fiinished @@ -849,35 +854,35 @@ 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. */ -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 - * + * * 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); /**@}*/ /** \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. @@ -899,13 +904,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 @@ -923,12 +928,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 @@ -959,15 +964,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. @@ -996,35 +1001,35 @@ 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 * 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 { +typedef struct { /** 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; +} psa_drv_asymmetric_opaque_t; /**@}*/ @@ -1040,14 +1045,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 + * psa_drv_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 @@ -1062,14 +1067,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 @@ -1078,10 +1083,10 @@ 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 - * + * 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 @@ -1095,13 +1100,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 @@ -1110,10 +1115,10 @@ 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 - * + * * \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 @@ -1139,16 +1144,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 @@ -1156,10 +1161,10 @@ 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 - * + * * \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 @@ -1185,22 +1190,22 @@ 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); /**@}*/ /** \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. @@ -1236,17 +1241,17 @@ 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, - 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 * @@ -1276,37 +1281,37 @@ 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, - 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 * 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 { +typedef struct { /** Function that performs the AEAD encrypt operation */ - psa_aead_opaque_encrypt_t *p_encrypt; + psa_drv_aead_opaque_encrypt_t *p_encrypt; /** Function that performs the AEAD decrypt operation */ - psa_aead_opaque_decrypt_t *p_decrypt; -}; + psa_drv_aead_opaque_decrypt_t *p_decrypt; +} psa_drv_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,11 +1322,11 @@ 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} - * pcd_aead__encrypt + * psa_drv_aead__encrypt * ~~~~~~~~~~~~~ * Where `ALGO` is the name of the AEAD algorithm * @@ -1354,27 +1359,27 @@ 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, - 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 @@ -1407,18 +1412,18 @@ 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, - 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); /**@}*/ @@ -1429,21 +1434,21 @@ typedef psa_status_t (*psa_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 * - * + * * \param[in,out] p_context A hardware-specific structure * containing any context information for * the implementation * * \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 - * + * * 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 +1461,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,30 +1470,30 @@ 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, - 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 * 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 { +typedef struct { /** 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; +} psa_drv_entropy_t; /**@}*/ /** \defgroup driver_key_management Key Management @@ -1516,12 +1521,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 @@ -1539,7 +1544,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 @@ -1581,10 +1586,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 @@ -1607,30 +1612,30 @@ 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 * 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 { +typedef struct { /** 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; +} psa_drv_key_management_t; /**@}*/ @@ -1641,89 +1646,89 @@ 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, - * `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); * ~~~~~~~~~~~~~ */ /**@{*/ /** \brief The hardware-specific key derivation context structure - * + * * 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 - * + * * \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, - 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 - * + * * 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, - 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 @@ -1731,48 +1736,52 @@ 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, - 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 - * + * * \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, - 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 * 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 { +typedef struct { /** 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; +} psa_drv_key_derivation_t; /**@}*/ -#endif // __PSA_CRYPTO_DRIVER_H__ \ No newline at end of file +#ifdef __cplusplus +} +#endif + +#endif /* PSA_CRYPTO_DRIVER_H */ 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 @@ +