Merge remote-tracking branch 'upstream-crypto/development' into psa-api-beta2-merge-development
Merge the Mbed Crypto development branch a little after
mbedcrypto-1.0.0 into the PSA Crypto API 1.0 beta branch a little
after beta 2.
Summary of merge conflicts:
* Some features (psa_copy_key, public key format without
SubjectPublicKeyInfo wrapping) went into both sides, but with a few
improvements on the implementation side. For those, take the
implementation side.
* The key derivation API changed considerably on the API side. This
merge commit generally goes with the updated API except in the tests
where it keeps some aspects of the implementation.
Due to the divergence between the two branches on key derivation and
key agreement, test_suite_psa_crypto does not compile. This will be
resolved in subsequent commits.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index bdbbc1f..6a7bce8 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -193,7 +193,7 @@
* the policy has been saved to persistent storage. Implementations
* may defer saving the policy until the key material is created.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
@@ -285,7 +285,7 @@
* Success. The application can now use the value of `*handle`
* to access the newly allocated key slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
* \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -322,7 +322,7 @@
* to access the newly allocated key slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key with the identifier \p id in the storage
* area designated by \p lifetime.
* \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -404,7 +404,7 @@
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The key slot is invalid,
* or the key data is not correctly formatted.
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key in the specified slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
@@ -476,7 +476,7 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* The handle is to a key slot which does not contain key material yet.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -655,7 +655,7 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
@@ -723,7 +723,7 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The key is neither a public key nor a key pair.
* \retval #PSA_ERROR_NOT_SUPPORTED
@@ -750,8 +750,9 @@
*
* Copy key material from one location to another.
*
- * This function is primarily useful to copy a key from one lifetime
- * to another. The target key retains its lifetime and location.
+ * This function is primarily useful to copy a key from one location
+ * to another, since it populates a key using the material from
+ * another key which may have a different lifetime.
*
* In an implementation where slots have different ownerships,
* this function may be used to share a key with a different party,
@@ -791,9 +792,9 @@
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* \p target_handle already contains key material.
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \p source_handle does not contain key material.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The policy constraints on the source, on the target and
@@ -956,6 +957,9 @@
* Success.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \p alg is not supported or is not a hash algorithm.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -1291,7 +1295,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -1302,6 +1306,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
@@ -1348,7 +1355,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c key is not compatible with \c alg.
@@ -1359,6 +1366,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
@@ -1677,7 +1687,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -1688,6 +1698,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
@@ -1736,7 +1749,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -1747,6 +1760,9 @@
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
* \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (already set up and not
+ * subsequently completed).
+ * \retval #PSA_ERROR_BAD_STATE
* The library has not been previously initialized by psa_crypto_init().
* It is implementation-dependent whether a failure to initialize
* results in this error code.
@@ -1964,7 +1980,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p handle is not compatible with \p alg.
@@ -2020,7 +2036,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_INVALID_SIGNATURE
* The ciphertext is not authentic.
* \retval #PSA_ERROR_NOT_PERMITTED
@@ -2861,7 +2877,7 @@
* \param output_length Number of bytes to output.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
* There were fewer than \p output_length bytes
* in the generator. Note that in this case, no
* output is written to the output buffer.
@@ -2968,7 +2984,7 @@
* Success.
* If the key is persistent, the key material and the key's metadata
* have been saved to persistent storage.
- * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
* There was not enough data to create the desired key.
* Note that in this case, no output is written to the output buffer.
* The generator's capacity is set to 0, thus subsequent calls to
@@ -2978,7 +2994,7 @@
* implementation in general or in this particular slot.
* \retval #PSA_ERROR_BAD_STATE
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key in the specified slot.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
@@ -3140,7 +3156,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c step is not compatible with the generator's algorithm.
@@ -3201,7 +3217,7 @@
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c private_key is not compatible with \c alg,
@@ -3368,7 +3384,7 @@
* If the key is persistent, the key material and the key's metadata
* have been saved to persistent storage.
* \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
* There is already a key in the specified slot.
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_INVALID_ARGUMENT
diff --git a/include/psa/crypto_accel_driver.h b/include/psa/crypto_accel_driver.h
index b752fed..4a540f0 100644
--- a/include/psa/crypto_accel_driver.h
+++ b/include/psa/crypto_accel_driver.h
@@ -38,12 +38,13 @@
extern "C" {
#endif
-/** \defgroup driver_digest Message Digests
+/** \defgroup driver_digest Hardware-Accelerated Message Digests
*
* Generation and authentication of Message Digests (aka hashes) must be done
* in parts using the following sequence:
* - `psa_drv_hash_setup_t`
* - `psa_drv_hash_update_t`
+ * - `psa_drv_hash_update_t`
* - ...
* - `psa_drv_hash_finish_t`
*
@@ -64,7 +65,7 @@
/** \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
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
* psa_drv_hash_<ALGO>_setup
@@ -81,7 +82,7 @@
/** \brief The function prototype for the update operation of a hash (message
* digest) operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
* psa_drv_hash_<ALGO>_update
@@ -99,10 +100,10 @@
const uint8_t *p_input,
size_t input_length);
-/** \brief The prototype for the finish operation of a hash (message digest)
- * operation
+/** \brief The function prototype for the finish operation of a hash (message
+ * digest) operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
* psa_drv_hash_<ALGO>_finish
@@ -130,7 +131,7 @@
/** \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
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
* psa_drv_hash_<ALGO>_abort
@@ -144,39 +145,39 @@
/**@}*/
-/** \defgroup transparent_mac Transparent Message Authentication Code
+/** \defgroup accel_mac Hardware-Accelerated 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
- * `psa_drv_mac_transparent_generate_t` or `psa_drv_mac_transparent_verify_t`
+ * cryptographic accelerators can be done either as a single function call (via the
+ * `psa_drv_accel_mac_generate_t` or `psa_drv_accel_mac_verify_t`
* functions), or in parts using the following sequence:
- * - `psa_drv_mac_transparent_setup_t`
- * - `psa_drv_mac_transparent_update_t`
- * - `psa_drv_mac_transparent_update_t`
+ * - `psa_drv_accel_mac_setup_t`
+ * - `psa_drv_accel_mac_update_t`
+ * - `psa_drv_accel_mac_update_t`
* - ...
- * - `psa_drv_mac_transparent_finish_t` or `psa_drv_mac_transparent_finish_verify_t`
+ * - `psa_drv_accel_mac_finish_t` or `psa_drv_accel_mac_finish_verify_t`
*
- * If a previously started Transparent MAC operation needs to be terminated, it
- * should be done so by the `psa_drv_mac_transparent_abort_t`. Failure to do so may
+ * If a previously started MAC operation needs to be terminated, it
+ * should be done so by the `psa_drv_accel_mac_abort_t`. Failure to do so may
* result in allocated resources not being freed or in other undefined
* behavior.
*
*/
/**@{*/
-/** \brief The hardware-specific transparent-key MAC context structure
+/** \brief The hardware-accelerator-specific MAC context structure
*
* The contents of this structure are implementation dependent and are
* therefore not described here.
*/
-typedef struct psa_drv_mac_transparent_context_s psa_drv_mac_transparent_context_t;
+typedef struct psa_drv_accel_mac_context_s psa_drv_accel_mac_context_t;
/** \brief The function prototype for the setup operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_setup
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_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)
@@ -190,17 +191,17 @@
* \retval PSA_SUCCESS
* Success.
*/
-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);
+typedef psa_status_t (*psa_drv_accel_mac_setup_t)(psa_drv_accel_mac_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
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_update
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_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)
@@ -212,17 +213,17 @@
* to the MAC operation
* \param[in] input_length The size in bytes of the input message buffer
*/
-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);
+typedef psa_status_t (*psa_drv_accel_mac_update_t)(psa_drv_accel_mac_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
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_finish
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_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)
@@ -237,17 +238,17 @@
* \retval PSA_SUCCESS
* Success.
*/
-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);
+typedef psa_status_t (*psa_drv_accel_mac_finish_t)(psa_drv_accel_mac_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
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_finish_verify
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_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)
@@ -263,17 +264,17 @@
* \retval PSA_SUCCESS
* The operation completed successfully and the comparison matched
*/
-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);
+typedef psa_status_t (*psa_drv_accel_mac_finish_verify_t)(psa_drv_accel_mac_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
+ * started hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_abort
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_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)
@@ -283,15 +284,15 @@
* aborted
*
*/
-typedef psa_status_t (*psa_drv_mac_transparent_abort_t)(psa_drv_mac_transparent_context_t *p_context);
+typedef psa_status_t (*psa_drv_accel_mac_abort_t)(psa_drv_accel_mac_context_t *p_context);
-/** \brief The function prototype for a one-shot operation of a transparent-key
- * MAC operation
+/** \brief The function prototype for the one-shot operation of a
+ * hardware-accelerated MAC operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>
* ~~~~~~~~~~~~~
* 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)
@@ -306,21 +307,21 @@
* upon success
* \param[in] mac_length The length in bytes of the `p_mac` buffer
*/
-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);
+typedef psa_status_t (*psa_drv_accel_mac_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
+/** \brief The function prototype for the one-shot hardware-accelerated MAC
+ * Verify operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_verify
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_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)
@@ -337,51 +338,53 @@
* \retval PSA_SUCCESS
* The operation completed successfully and the comparison matched
*/
-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);
+typedef psa_status_t (*psa_drv_accel_mac_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 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:
- * - `psa_drv_cipher_transparent_setup_t`
- * - `psa_drv_cipher_transparent_set_iv_t` (optional depending upon block mode)
- * - `psa_drv_cipher_transparent_update_t`
+/** \defgroup accel_cipher Hardware-Accelerated Block Ciphers
+ * Encryption and Decryption using hardware-acceleration in block modes other
+ * than ECB must be done in multiple parts, using the following flow:
+ * - `psa_drv_accel_ciphersetup_t`
+ * - `psa_drv_accel_cipher_set_iv_t` (optional depending upon block mode)
+ * - `psa_drv_accel_cipher_update_t`
+ * - `psa_drv_accel_cipher_update_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_drv_cipher_transparent_abort_t`. Failure to do
- * so may result in allocated resources not being freed or in other undefined
- * behavior.
+ * - `psa_drv_accel_cipher_finish_t`
+ *
+ * If a previously started hardware-accelerated Cipher operation needs to be
+ * terminated, it should be done so by the `psa_drv_accel_cipher_abort_t`.
+ * Failure to do so may result in allocated resources not being freed or in
+ * other undefined behavior.
*/
/**@{*/
-/** \brief The hardware-specific transparent-key Cipher context structure
+/** \brief The hardware-accelerator-specific cipher context structure
*
* The contents of this structure are implementation dependent and are
* therefore not described here.
*/
-typedef struct psa_drv_cipher_transparent_context_s psa_drv_cipher_transparent_context_t;
+typedef struct psa_drv_accel_cipher_context_s psa_drv_accel_cipher_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
+/** \brief The function prototype for the setup operation of
+ * hardware-accelerated block cipher operations.
+ * Functions that implement this prototype should be named in the following
* conventions:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_setup_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_setup_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* 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:
+ *
+ * For stream ciphers:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_setup_<CIPHER_NAME>
+ * psa_drv_accel_cipher_setup_<CIPHER_NAME>
* ~~~~~~~~~~~~~
* Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4)
*
@@ -395,17 +398,17 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_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
+ * of hardware-accelerated block cipher operations
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_set_iv_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_set_iv_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -418,17 +421,17 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_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.
+/** \brief The function prototype for the update operation of
+ * hardware-accelerated block cipher operations.
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_update_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_update_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -447,20 +450,20 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_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.
+/** \brief The function prototype for the finish operation of
+ * hardware-accelerated block cipher operations.
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_finish_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_finish_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -476,18 +479,18 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_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.
+/** \brief The function prototype for the abort operation of
+ * hardware-accelerated block cipher operations.
*
* Functions that implement the following prototype should be named in the
* following convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_abort_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_abort_<CIPHER_NAME>_<MODE>
* ~~~~~~~~~~~~~
* Where
* - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -498,27 +501,27 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_transparent_abort_t)(psa_drv_cipher_transparent_context_t *p_context);
+typedef psa_status_t (*psa_drv_accel_cipher_abort_t)(psa_drv_accel_cipher_context_t *p_context);
/**@}*/
-/** \defgroup aead_transparent AEAD Transparent
+/** \defgroup accel_aead Hardware-Accelerated Authenticated Encryption with Additional Data
*
- * 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
- * entire message, it prevents decrypted data from being made available before
- * the authentication operation is complete and the data is known to be
- * authentic.
+ * Hardware-accelerated Authenticated Encryption with Additional Data (AEAD)
+ * operations 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.
*/
/**@{*/
-/** Process an authenticated encryption operation using an opaque key.
+/** \brief The function prototype for the hardware-accelerated authenticated
+ * encryption operation.
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_aead_<ALGO>_encrypt
+ * psa_drv_accel_aead_<ALGO>_encrypt
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the AEAD algorithm
*
@@ -551,27 +554,28 @@
* the `ciphertext` buffer
*
* \retval #PSA_SUCCESS
-
- */
-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
+ */
+typedef psa_status_t (*psa_drv_accel_aead_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);
+
+/** \brief The function prototype for the hardware-accelerated authenticated
+ * decryption operation.
+ *
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_aead_<ALGO>_decrypt
+ * psa_drv_accel_aead_<ALGO>_decrypt
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the AEAD algorithm
* \param[in] p_key A pointer to the key material
@@ -604,41 +608,45 @@
* \retval #PSA_SUCCESS
* Success.
*/
-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);
+typedef psa_status_t (*psa_drv_accel_aead_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);
/**@}*/
-/** \defgroup transparent_asymmetric Transparent Asymmetric Cryptography
+/** \defgroup accel_asymmetric Hardware-Accelerated 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
- * transparent keys must be done in single function calls.
+ * asymmetric keys is limited by the key size, hardware-accelerated asymmetric
+ * key operations must be done in single function calls.
*/
/**@{*/
/**
- * \brief A function that signs a hash or short message with a transparent
- * asymmetric private key
+ * \brief The function prototype for the hardware-accelerated asymmetric sign
+ * operation.
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_sign
+ * psa_drv_accel_asymmetric_<ALGO>_sign
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the signing algorithm
*
+ * This function supports any asymmetric-key output from psa_export_key() as
+ * the buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_key() for the formats.
+ *
* \param[in] p_key A buffer containing the private key
* material
* \param[in] key_size The size in bytes of the `p_key` data
@@ -653,26 +661,32 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_accel_asymmetric_sign_t)(const uint8_t *p_key,
+ size_t key_size,
+ psa_algorithm_t alg,
+ psa_key_type_t key_type,
+ 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
- * a transparent asymmetric public key
+ * \brief The function prototype for the hardware-accelerated signature verify
+ * operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_verify
+ * psa_drv_accel_asymmetric_<ALGO>_verify
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the signing algorithm
*
+ * This function supports any output from \ref psa_export_public_key() as the
+ * buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_public_key() for the format of public keys and to the
+ * documentation of \ref psa_export_key() for the format for other key types.
+ *
* \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
@@ -686,25 +700,31 @@
* \retval PSA_SUCCESS
* The signature is valid.
*/
-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);
+typedef psa_status_t (*psa_drv_accel_asymmetric_verify_t)(const uint8_t *p_key,
+ size_t key_size,
+ psa_algorithm_t alg,
+ psa_key_type_t key_type,
+ 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
- * asymmetric public key
+ * \brief The function prototype for the hardware-accelerated asymmetric
+ * encrypt operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_encrypt
+ * psa_drv_accel_asymmetric_<ALGO>_encrypt
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the encryption algorithm
*
+ * This function supports any output from \ref psa_export_public_key() as the
+ * buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_public_key() for the format of public keys and to the
+ * documentation of \ref psa_export_key() for the format for other key types.
+ *
* \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
@@ -730,27 +750,33 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_accel_asymmetric_encrypt_t)(const uint8_t *p_key,
+ size_t key_size,
+ psa_algorithm_t alg,
+ psa_key_type_t key_type,
+ 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
+ * \brief The function prototype for the hardware=acce;erated asymmetric
+ * decrypt operation
*
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
* convention:
* ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_decrypt
+ * psa_drv_accel_asymmetric_<ALGO>_decrypt
* ~~~~~~~~~~~~~
* Where `ALGO` is the name of the encryption algorithm
*
+ * This function supports any asymmetric-key output from psa_export_key() as
+ * the buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_key() for the formats.
+ *
* \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
@@ -776,16 +802,17 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_accel_asymmetric_decrypt_t)(const uint8_t *p_key,
+ size_t key_size,
+ psa_algorithm_t alg,
+ psa_key_type_t key_type,
+ 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);
/**@}*/
diff --git a/include/psa/crypto_entropy_driver.h b/include/psa/crypto_entropy_driver.h
index f5e383e..f596b6b 100644
--- a/include/psa/crypto_entropy_driver.h
+++ b/include/psa/crypto_entropy_driver.h
@@ -40,10 +40,6 @@
*/
/**@{*/
-/** \brief A hardware-specific structure for a entropy providing hardware
- */
-typedef struct psa_drv_entropy_context_s psa_drv_entropy_context_t;
-
/** \brief Initialize an entropy driver
*
*
@@ -53,7 +49,7 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_entropy_init_t)(psa_drv_entropy_context_t *p_context);
+typedef psa_status_t (*psa_drv_entropy_init_t)(void *p_context);
/** \brief Get a specified number of bits from the entropy source
*
@@ -81,7 +77,7 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_entropy_get_bits_t)(psa_drv_entropy_context_t *p_context,
+typedef psa_status_t (*psa_drv_entropy_get_bits_t)(void *p_context,
uint8_t *p_buffer,
uint32_t buffer_size,
uint32_t *p_received_entropy_bits);
@@ -96,11 +92,12 @@
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
+ /** The driver-specific size of the entropy context */
+ const size_t context_size;
/** 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_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;
/**@}*/
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index d14edd9..093355d 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -30,6 +30,8 @@
#ifndef PSA_CRYPTO_EXTRA_H
#define PSA_CRYPTO_EXTRA_H
+#include "mbedtls/platform_util.h"
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -37,6 +39,29 @@
/* UID for secure storage seed */
#define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
+/*
+ * Deprecated PSA Crypto error code definitions
+ */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_UNKNOWN_ERROR \
+ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_GENERIC_ERROR )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_OCCUPIED_SLOT \
+ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_ALREADY_EXISTS )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_EMPTY_SLOT \
+ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_DOES_NOT_EXIST )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_INSUFFICIENT_CAPACITY \
+ MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_INSUFFICIENT_DATA )
+#endif
+
/**
* \brief Library deinitialization.
*
@@ -89,10 +114,9 @@
* This is an Mbed TLS extension.
*
* \note This function is only available on the following platforms:
- * * If the compile-time options MBEDTLS_ENTROPY_NV_SEED and
- * MBEDTLS_PSA_HAS_ITS_IO are both enabled. Note that you
- * must provide compatible implementations of mbedtls_nv_seed_read
- * and mbedtls_nv_seed_write.
+ * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
+ * Note that you must provide compatible implementations of
+ * mbedtls_nv_seed_read and mbedtls_nv_seed_write.
* * In a client-server integration of PSA Cryptography, on the client side,
* if the server supports this feature.
* \param[in] seed Buffer containing the seed value to inject.
@@ -111,7 +135,6 @@
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \p seed_size is out of range.
* \retval #PSA_ERROR_STORAGE_FAILURE
- * \retval `PSA_ITS_ERROR_XXX`
* There was a failure reading or writing from storage.
* \retval #PSA_ERROR_NOT_PERMITTED
* The library has already been initialized. It is no longer
diff --git a/include/psa/crypto_platform.h b/include/psa/crypto_platform.h
index 50ca546..42cdad3 100644
--- a/include/psa/crypto_platform.h
+++ b/include/psa/crypto_platform.h
@@ -49,4 +49,53 @@
/* Integral type representing a key handle. */
typedef uint16_t psa_key_handle_t;
+/* This implementation distinguishes *application key identifiers*, which
+ * are the key identifiers specified by the application, from
+ * *key file identifiers*, which are the key identifiers that the library
+ * sees internally. The two types can be different if there is a remote
+ * call layer between the application and the library which supports
+ * multiple client applications that do not have access to each others'
+ * keys. The point of having different types is that the key file
+ * identifier may encode not only the key identifier specified by the
+ * application, but also the the identity of the application.
+ *
+ * Note that this is an internal concept of the library and the remote
+ * call layer. The application itself never sees anything other than
+ * #psa_app_key_id_t with its standard definition.
+ */
+
+/* The application key identifier is always what the application sees as
+ * #psa_key_id_t. */
+typedef uint32_t psa_app_key_id_t;
+
+#if defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
+
+#if defined(PSA_CRYPTO_SECURE)
+/* Building for the PSA Crypto service on a PSA platform. */
+/* A key owner is a PSA partition identifier. */
+typedef int32_t psa_key_owner_id_t;
+#endif
+
+typedef struct
+{
+ uint32_t key_id;
+ psa_key_owner_id_t owner;
+} psa_key_file_id_t;
+#define PSA_KEY_FILE_GET_KEY_ID( file_id ) ( ( file_id ).key_id )
+
+/* Since crypto.h is used as part of the PSA Cryptography API specification,
+ * it must use standard types for things like the argument of psa_open_key().
+ * If it wasn't for that constraint, psa_open_key() would take a
+ * `psa_key_file_id_t` argument. As a workaround, make `psa_key_id_t` an
+ * alias for `psa_key_file_id_t` when building for a multi-client service. */
+typedef psa_key_file_id_t psa_key_id_t;
+
+#else /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
+
+/* By default, a key file identifier is just the application key identifier. */
+typedef psa_app_key_id_t psa_key_file_id_t;
+#define PSA_KEY_FILE_GET_KEY_ID( id ) ( id )
+
+#endif /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
+
#endif /* PSA_CRYPTO_PLATFORM_H */
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index 0578664..5fb7bc3 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -3,10 +3,10 @@
* \brief PSA external cryptoprocessor driver module
*
* This header declares types and function signatures for cryptography
- * drivers that access key material via opaque references. This is
- * meant for cryptoprocessors that have a separate key storage from the
+ * drivers that access key material via opaque references.
+ * This is meant for cryptoprocessors that have a separate key storage from the
* space in which the PSA Crypto implementation runs, typically secure
- * elements.
+ * elements (SEs).
*
* This file is part of the PSA Crypto Driver Model, containing functions for
* driver developers to implement to enable hardware to be called in a
@@ -43,27 +43,27 @@
/** An internal designation of a key slot between the core part of the
* PSA Crypto implementation and the driver. The meaning of this value
* is driver-dependent. */
-typedef uint32_t psa_key_slot_t;
+typedef uint32_t psa_key_slot_number_t; // Change this to psa_key_slot_t after psa_key_slot_t is removed from Mbed crypto
-/** \defgroup opaque_mac Opaque Message Authentication Code
+/** \defgroup se_mac Secure Element Message Authentication Codes
* Generation and authentication of Message Authentication Codes (MACs) using
- * opaque keys can be done either as a single function call (via the
- * `psa_drv_mac_opaque_generate_t` or `psa_drv_mac_opaque_verify_t` functions), or in
+ * a secure element can be done either as a single function call (via the
+ * `psa_drv_se_mac_generate_t` or `psa_drv_se_mac_verify_t` functions), or in
* parts using the following sequence:
- * - `psa_drv_mac_opaque_setup_t`
- * - `psa_drv_mac_opaque_update_t`
- * - `psa_drv_mac_opaque_update_t`
+ * - `psa_drv_se_mac_setup_t`
+ * - `psa_drv_se_mac_update_t`
+ * - `psa_drv_se_mac_update_t`
* - ...
- * - `psa_drv_mac_opaque_finish_t` or `psa_drv_mac_opaque_finish_verify_t`
+ * - `psa_drv_se_mac_finish_t` or `psa_drv_se_mac_finish_verify_t`
*
- * If a previously started Opaque MAC operation needs to be terminated, it
- * should be done so by the `psa_drv_mac_opaque_abort_t`. Failure to do so may
+ * If a previously started secure element MAC operation needs to be terminated,
+ * it should be done so by the `psa_drv_se_mac_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
- * implementation using an opaque key
+/** \brief A function that starts a secure element MAC operation for a PSA
+ * Crypto Driver implementation
*
* \param[in,out] p_context A structure that will contain the
* hardware-specific MAC context
@@ -75,26 +75,26 @@
* \retval PSA_SUCCESS
* Success.
*/
-typedef psa_status_t (*psa_drv_mac_opaque_setup_t)(void *p_context,
- psa_key_slot_t key_slot,
- psa_algorithm_t algorithm);
+typedef psa_status_t (*psa_drv_se_mac_setup_t)(void *p_context,
+ psa_key_slot_number_t key_slot,
+ psa_algorithm_t algorithm);
-/** \brief A function that continues a previously started MAC operation using
- * an opaque key
+/** \brief A function that continues a previously started secure element MAC
+ * operation
*
* \param[in,out] p_context A hardware-specific structure for the
* previously-established MAC operation to be
- * continued
+ * updated
* \param[in] p_input A buffer containing the message to be appended
* to the MAC operation
* \param[in] input_length The size in bytes of the input message buffer
*/
-typedef psa_status_t (*psa_drv_mac_opaque_update_t)(void *p_context,
- const uint8_t *p_input,
- size_t input_length);
+typedef psa_status_t (*psa_drv_se_mac_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
+/** \brief a function that completes a previously started secure element MAC
+ * operation by returning the resulting MAC.
*
* \param[in,out] p_context A hardware-specific structure for the
* previously started MAC operation to be
@@ -109,13 +109,13 @@
* \retval PSA_SUCCESS
* Success.
*/
-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);
+typedef psa_status_t (*psa_drv_se_mac_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
+/** \brief A function that completes a previously started secure element MAC
+ * operation by comparing the resulting MAC against a provided value
*
* \param[in,out] p_context A hardware-specific structure for the previously
* started MAC operation to be fiinished
@@ -130,19 +130,20 @@
* The operation completed successfully, but the calculated MAC did
* not match the provided MAC
*/
-typedef psa_status_t (*psa_drv_mac_opaque_finish_verify_t)(void *p_context,
- const uint8_t *p_mac,
- size_t mac_length);
+typedef psa_status_t (*psa_drv_se_mac_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
-
+/** \brief A function that aborts a previous started secure element MAC
+ * operation
+ *
* \param[in,out] p_context A hardware-specific structure for the previously
* started MAC operation to be aborted
*/
-typedef psa_status_t (*psa_drv_mac_opaque_abort_t)(void *p_context);
+typedef psa_status_t (*psa_drv_se_mac_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
+/** \brief A function that performs a secure element MAC operation in one
+ * command and returns the calculated MAC
*
* \param[in] p_input A buffer containing the message to be MACed
* \param[in] input_length The size in bytes of `p_input`
@@ -158,16 +159,16 @@
* \retval PSA_SUCCESS
* Success.
*/
-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);
+typedef psa_status_t (*psa_drv_se_mac_generate_t)(const uint8_t *p_input,
+ size_t input_length,
+ psa_key_slot_number_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
+/** \brief A function that performs a secure element MAC operation in one
+ * command and compares the resulting MAC against a provided value
*
* \param[in] p_input A buffer containing the message to be MACed
* \param[in] input_length The size in bytes of `input`
@@ -185,21 +186,21 @@
* The operation completed successfully, but the calculated MAC did
* not match the provided MAC
*/
-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);
+typedef psa_status_t (*psa_drv_se_mac_verify_t)(const uint8_t *p_input,
+ size_t input_length,
+ psa_key_slot_number_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.
+ * perform secure element MAC operations
*
* PSA Crypto API implementations should populate the table as appropriate
* upon startup.
*
* If one of the functions is not implemented (such as
- * `psa_drv_mac_opaque_generate_t`), it should be set to NULL.
+ * `psa_drv_se_mac_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
@@ -208,57 +209,59 @@
*
*/
typedef struct {
- /**The size in bytes of the hardware-specific Opaque-MAC Context structure
+ /**The size in bytes of the hardware-specific secure element MAC context
+ * structure
*/
- size_t context_size;
- /** Function that performs the setup operation
+ size_t context_size;
+ /** Function that performs a MAC setup operation
*/
- psa_drv_mac_opaque_setup_t *p_setup;
- /** Function that performs the update operation
+ psa_drv_se_mac_setup_t p_setup;
+ /** Function that performs a MAC update operation
*/
- psa_drv_mac_opaque_update_t *p_update;
- /** Function that completes the operation
+ psa_drv_se_mac_update_t p_update;
+ /** Function that completes a MAC operation
*/
- psa_drv_mac_opaque_finish_t *p_finish;
- /** Function that completed a MAC operation with a verify check
+ psa_drv_se_mac_finish_t p_finish;
+ /** Function that completes a MAC operation with a verify check
*/
- psa_drv_mac_opaque_finish_verify_t *p_finish_verify;
- /** Function that aborts a previoustly started operation
+ psa_drv_se_mac_finish_verify_t p_finish_verify;
+ /** Function that aborts a previoustly started MAC operation
*/
- psa_drv_mac_opaque_abort_t *p_abort;
- /** Function that performs the MAC operation in one call
+ psa_drv_se_mac_abort_t p_abort;
+ /** Function that performs a MAC operation in one call
*/
- psa_drv_mac_opaque_generate_t *p_mac;
- /** Function that performs the MAC and verify operation in one call
+ psa_drv_se_mac_generate_t p_mac;
+ /** Function that performs a MAC and verify operation in one call
*/
- psa_drv_mac_opaque_verify_t *p_mac_verify;
-} psa_drv_mac_opaque_t;
+ psa_drv_se_mac_verify_t p_mac_verify;
+} psa_drv_se_mac_t;
/**@}*/
-/** \defgroup opaque_cipher Opaque Symmetric Ciphers
+/** \defgroup se_cipher Secure Element Symmetric Ciphers
*
- * Encryption and Decryption using opaque keys in block modes other than ECB
- * must be done in multiple parts, using the following flow:
- * - `psa_drv_cipher_opaque_setup_t`
- * - `psa_drv_cipher_opaque_set_iv_t` (optional depending upon block mode)
- * - `psa_drv_cipher_opaque_update_t`
+ * Encryption and Decryption using secure element keys in block modes other
+ * than ECB must be done in multiple parts, using the following flow:
+ * - `psa_drv_se_cipher_setup_t`
+ * - `psa_drv_se_cipher_set_iv_t` (optional depending upon block mode)
+ * - `psa_drv_se_cipher_update_t`
+ * - `psa_drv_se_cipher_update_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_drv_cipher_opaque_abort_t`. Failure to do so may
- * result in allocated resources not being freed or in other undefined
- * behavior.
+ * - `psa_drv_se_cipher_finish_t`
+ *
+ * If a previously started secure element Cipher operation needs to be
+ * terminated, it should be done so by the `psa_drv_se_cipher_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 `psa_drv_cipher_opaque_ecb_t` function
- * pointer for the cipher operations.
+ * the block mode itself, while calling the `psa_drv_se_cipher_ecb_t` function
+ * for the cipher operations.
*/
/**@{*/
-/** \brief A function pointer that provides the cipher setup function for
- * opaque-key operations
+/** \brief A function that provides the cipher setup function for a
+ * secure element driver
*
* \param[in,out] p_context A structure that will contain the
* hardware-specific cipher context.
@@ -272,16 +275,16 @@
* \retval PSA_SUCCESS
* \retval PSA_ERROR_NOT_SUPPORTED
*/
-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);
+typedef psa_status_t (*psa_drv_se_cipher_setup_t)(void *p_context,
+ psa_key_slot_number_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
+/** \brief A function that sets the initialization vector (if
+ * necessary) for an secure element 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
+ * Rationale: The `psa_se_cipher_*` operation 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 drivers to implement as the PSA
* Crypto implementation can do the generation using its RNG features.
*
@@ -292,11 +295,11 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_cipher_opaque_set_iv_t)(void *p_context,
- const uint8_t *p_iv,
- size_t iv_length);
+typedef psa_status_t (*psa_drv_se_cipher_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
+/** \brief A function that continues a previously started secure element cipher
* operation
*
* \param[in,out] p_context A hardware-specific structure for the
@@ -314,14 +317,14 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_se_cipher_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
+/** \brief A function that completes a previously started secure element cipher
* operation
*
* \param[in,out] p_context A hardware-specific structure for the
@@ -335,21 +338,21 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_se_cipher_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
+/** \brief A function that aborts a previously started secure element cipher
* operation
*
* \param[in,out] p_context A hardware-specific structure for the
* previously started cipher operation
*/
-typedef psa_status_t (*psa_drv_cipher_opaque_abort_t)(void *p_context);
+typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *p_context);
-/** \brief A function that performs the ECB block mode for opaque-key cipher
- * operations
+/** \brief A function that performs the ECB block mode for secure element
+ * cipher operations
*
* Note: this function should only be used with implementations that do not
* provide a needed higher-level operation.
@@ -370,58 +373,59 @@
* \retval PSA_SUCCESS
* \retval PSA_ERROR_NOT_SUPPORTED
*/
-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);
+typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_key_slot_number_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.
+ * cipher operations using secure elements.
*
* PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
*
* If one of the functions is not implemented (such as
- * `psa_drv_cipher_opaque_ecb_t`), it should be set to NULL.
+ * `psa_drv_se_cipher_ecb_t`), it should be set to NULL.
*/
typedef struct {
- /** The size in bytes of the hardware-specific Opaque Cipher context
- * structure
+ /** The size in bytes of the hardware-specific secure element cipher
+ * context structure
*/
- size_t size;
- /** Function that performs the setup operation */
- psa_drv_cipher_opaque_setup_t *p_setup;
- /** Function that sets the IV (if necessary) */
- psa_drv_cipher_opaque_set_iv_t *p_set_iv;
- /** Function that performs the update operation */
- psa_drv_cipher_opaque_update_t *p_update;
- /** Function that completes the operation */
- psa_drv_cipher_opaque_finish_t *p_finish;
- /** Function that aborts the operation */
- psa_drv_cipher_opaque_abort_t *p_abort;
- /** Function that performs ECB mode for the cipher
+ size_t context_size;
+ /** Function that performs a cipher setup operation */
+ psa_drv_se_cipher_setup_t p_setup;
+ /** Function that sets a cipher IV (if necessary) */
+ psa_drv_se_cipher_set_iv_t p_set_iv;
+ /** Function that performs a cipher update operation */
+ psa_drv_se_cipher_update_t p_update;
+ /** Function that completes a cipher operation */
+ psa_drv_se_cipher_finish_t p_finish;
+ /** Function that aborts a cipher operation */
+ psa_drv_se_cipher_abort_t p_abort;
+ /** Function that performs ECB mode for a cipher operation
* (Danger: ECB mode should not be used directly by clients of the PSA
* Crypto Client API)
*/
- psa_drv_cipher_opaque_ecb_t *p_ecb;
-} psa_drv_cipher_opaque_t;
+ psa_drv_se_cipher_ecb_t p_ecb;
+} psa_drv_se_cipher_t;
/**@}*/
-/** \defgroup opaque_asymmetric Opaque Asymmetric Cryptography
+/** \defgroup se_asymmetric Secure Element 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.
+ * keys in a secure element must be done in single function calls.
*/
/**@{*/
/**
- * \brief A function that signs a hash or short message with a private key
+ * \brief A function that signs a hash or short message with a private key in
+ * a secure element
*
* \param[in] key_slot Key slot of an asymmetric key pair
* \param[in] alg A signature algorithm that is compatible
@@ -435,17 +439,17 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_key_slot_number_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
- * an asymmetric public key
+ * an asymmetric public key in a secure element
*
* \param[in] key_slot Key slot of a public key or an asymmetric key
* pair
@@ -459,16 +463,16 @@
* \retval PSA_SUCCESS
* The signature is valid.
*/
-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);
+typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_key_slot_number_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
- * key
+ * key in a secure element
*
* \param[in] key_slot Key slot of a public key or an asymmetric key
* pair
@@ -495,18 +499,19 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_key_slot_number_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.
+ * \brief A function that decrypts a short message with an asymmetric private
+ * key in a secure element.
*
* \param[in] key_slot Key slot of an asymmetric key pair
* \param[in] alg An asymmetric encryption algorithm that is
@@ -532,48 +537,49 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_key_slot_number_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.
+ * asymmetric cryptographic operations using secure elements.
*
* PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
*
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
- /** Function that performs the asymmetric sign operation */
- psa_drv_asymmetric_opaque_sign_t *p_sign;
- /** Function that performs the asymmetric verify operation */
- psa_drv_asymmetric_opaque_verify_t *p_verify;
- /** Function that performs the asymmetric encrypt operation */
- 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;
+ /** Function that performs an asymmetric sign operation */
+ psa_drv_se_asymmetric_sign_t p_sign;
+ /** Function that performs an asymmetric verify operation */
+ psa_drv_se_asymmetric_verify_t p_verify;
+ /** Function that performs an asymmetric encrypt operation */
+ psa_drv_se_asymmetric_encrypt_t p_encrypt;
+ /** Function that performs an asymmetric decrypt operation */
+ psa_drv_se_asymmetric_decrypt_t p_decrypt;
+} psa_drv_se_asymmetric_t;
/**@}*/
-/** \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
+/** \defgroup se_aead Secure Element Authenticated Encryption with Additional Data
+ * Authenticated Encryption with Additional Data (AEAD) operations with secure
+ * elements 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.
*/
/**@{*/
-/** \brief Process an authenticated encryption operation using an opaque key
+/** \brief A function that performs a secure element authenticated encryption
+ * operation
*
* \param[in] key_slot Slot containing the key to use.
* \param[in] algorithm The AEAD algorithm to compute
@@ -602,19 +608,19 @@
* \retval #PSA_SUCCESS
* Success.
*/
-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);
+typedef psa_status_t (*psa_drv_se_aead_encrypt_t)(psa_key_slot_number_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
+/** A function that peforms a secure element authenticated decryption operation
*
* \param[in] key_slot Slot containing the key to use
* \param[in] algorithm The AEAD algorithm to compute
@@ -642,21 +648,21 @@
* \retval #PSA_SUCCESS
* Success.
*/
-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);
+typedef psa_status_t (*psa_drv_se_aead_decrypt_t)(psa_key_slot_number_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
+ * secure element Authenticated Encryption with Additional Data operations
*
* PSA Crypto API implementations should populate instances of the table as
* appropriate upon startup.
@@ -665,13 +671,13 @@
*/
typedef struct {
/** Function that performs the AEAD encrypt operation */
- psa_drv_aead_opaque_encrypt_t *p_encrypt;
+ psa_drv_se_aead_encrypt_t p_encrypt;
/** Function that performs the AEAD decrypt operation */
- psa_drv_aead_opaque_decrypt_t *p_decrypt;
-} psa_drv_aead_opaque_t;
+ psa_drv_se_aead_decrypt_t p_decrypt;
+} psa_drv_se_aead_t;
/**@}*/
-/** \defgroup driver_key_management Key Management
+/** \defgroup se_key_management Secure Element Key Management
* Currently, key management is limited to importing keys in the clear,
* destroying keys, and exporting keys in the clear.
* Whether a key may be exported is determined by the key policies in place
@@ -679,7 +685,7 @@
*/
/**@{*/
-/** \brief Import a key in binary format
+/** \brief A function that imports a key into a secure element in binary format
*
* This function can support any output from psa_export_key(). Refer to the
* documentation of psa_export_key() for the format for each key type.
@@ -687,6 +693,7 @@
* \param[in] key_slot Slot where the key will be stored
* This must be a valid slot for a key of the chosen
* type. It must be unoccupied.
+ * \param[in] lifetime The required lifetime of the key storage
* \param[in] type Key type (a \c PSA_KEY_TYPE_XXX value)
* \param[in] algorithm Key algorithm (a \c PSA_ALG_XXX value)
* \param[in] usage The allowed uses of the key
@@ -696,33 +703,33 @@
* \retval #PSA_SUCCESS
* Success.
*/
-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);
+typedef psa_status_t (*psa_drv_se_import_key_t)(psa_key_slot_number_t key_slot,
+ psa_key_lifetime_t lifetime,
+ 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
+ * \brief A function that destroys a secure element key and restore the slot to
+ * its default state
*
- * This function destroys the content of the key slot from both volatile
- * memory and, if applicable, non-volatile storage. Implementations shall
- * make a best effort to ensure that any previous content of the slot is
- * unrecoverable.
+ * This function destroys the content of the key from a secure element.
+ * Implementations shall make a best effort to ensure that any previous content
+ * of the slot is unrecoverable.
*
- * This function also erases any metadata such as policies. It returns the
- * specified slot to its default state.
+ * This function returns the specified slot to its default state.
*
* \param[in] key_slot The key slot to erase.
*
* \retval #PSA_SUCCESS
* The slot's content, if any, has been erased.
*/
-typedef psa_status_t (*psa_drv_destroy_key_t)(psa_key_slot_t key);
+typedef psa_status_t (*psa_drv_se_destroy_key_t)(psa_key_slot_number_t key);
/**
- * \brief Export a key in binary format
+ * \brief A function that exports a secure element key in binary format
*
* The output of this function can be passed to psa_import_key() to
* create an equivalent object.
@@ -732,19 +739,9 @@
* identical: the implementation may choose a different representation
* of the same key if the format permits it.
*
- * For standard key types, the output format is as follows:
- *
- * - For symmetric keys (including MAC keys), the format is the
- * raw bytes of the key.
- * - For DES, the key data consists of 8 bytes. The parity bits must be
- * correct.
- * - For Triple-DES, the format is the concatenation of the
- * two or three DES keys.
- * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
- * is the non-encrypted DER representation defined by PKCS\#1 (RFC 8017)
- * as RSAPrivateKey.
- * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
- * is the DER representation defined by RFC 5280 as SubjectPublicKeyInfo.
+ * This function should generate output in the same format that
+ * `psa_export_key()` does. Refer to the
+ * documentation of `psa_export_key()` for the format for each key type.
*
* \param[in] key Slot whose content is to be exported. This must
* be an occupied key slot.
@@ -754,67 +751,79 @@
* that make up the key data.
*
* \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
* \retval #PSA_ERROR_NOT_PERMITTED
* \retval #PSA_ERROR_NOT_SUPPORTED
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_TAMPERING_DETECTED
*/
-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);
+typedef psa_status_t (*psa_drv_se_export_key_t)(psa_key_slot_number_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
+ * \brief A function that generates a symmetric or asymmetric key on a secure
+ * element
*
- * The output of this function can be passed to psa_import_key() to
- * create an object that is equivalent to the public key.
+ * If \p type is asymmetric (`#PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) == 1`),
+ * the public component of the generated key will be placed in `p_pubkey_out`.
+ * The format of the public key information will match the format specified for
+ * the psa_export_key() function for the key type.
*
- * For standard key types, the output format is as follows:
- *
- * - For RSA keys (#PSA_KEY_TYPE_RSA_KEYPAIR or #PSA_KEY_TYPE_RSA_PUBLIC_KEY),
- * the format is the DER representation of the public key defined by RFC 5280
- * as SubjectPublicKeyInfo.
- *
- * \param[in] key_slot Slot whose content is to be exported. This must
- * be an occupied key slot.
- * \param[out] p_data Buffer where the key data is to be written.
- * \param[in] data_size Size of the `data` buffer in bytes.
- * \param[out] p_data_length On success, the number of bytes
- * that make up the key data.
- *
- * \retval #PSA_SUCCESS
+ * \param[in] key_slot Slot where the generated key will be placed
+ * \param[in] type The type of the key to be generated
+ * \param[in] usage The prescribed usage of the generated key
+ * Note: Not all Secure Elements support the same
+ * restrictions that PSA Crypto does (and vice versa).
+ * Driver developers should endeavor to match the
+ * usages as close as possible.
+ * \param[in] bits The size in bits of the key to be generated.
+ * \param[in] extra Extra parameters for key generation. The
+ * interpretation of this parameter should match the
+ * interpretation in the `extra` parameter is the
+ * `psa_generate_key` function
+ * \param[in] extra_size The size in bytes of the \p extra buffer
+ * \param[out] p_pubkey_out The buffer where the public key information will
+ * be placed
+ * \param[in] pubkey_out_size The size in bytes of the `p_pubkey_out` buffer
+ * \param[out] p_pubkey_length Upon successful completion, will contain the
+ * size of the data placed in `p_pubkey_out`.
*/
-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);
+typedef psa_status_t (*psa_drv_se_generate_key_t)(psa_key_slot_number_t key_slot,
+ psa_key_type_t type,
+ psa_key_usage_t usage,
+ size_t bits,
+ const void *extra,
+ size_t extra_size,
+ uint8_t *p_pubkey_out,
+ size_t pubkey_out_size,
+ size_t *p_pubkey_length);
/**
- * \brief A struct containing all of the function pointers needed to for key
- * management using opaque keys
+ * \brief A struct containing all of the function pointers needed to for secure
+ * element key management
*
* PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
*
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
- /** Function that performs the key import operation */
- psa_drv_opaque_import_key_t *p_import;
- /** Function that performs the key destroy operation */
- psa_drv_destroy_key_t *p_destroy;
- /** Function that performs the key export operation */
- 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;
+ /** Function that performs a key import operation */
+ psa_drv_se_import_key_t p_import;
+ /** Function that performs a generation */
+ psa_drv_se_generate_key_t p_generate;
+ /** Function that performs a key destroy operation */
+ psa_drv_se_destroy_key_t p_destroy;
+ /** Function that performs a key export operation */
+ psa_drv_se_export_key_t p_export;
+} psa_drv_se_key_management_t;
/**@}*/
-/** \defgroup driver_derivation Key Derivation and Agreement
+/** \defgroup driver_derivation Secure Element Key Derivation and Agreement
* Key derivation is the process of generating new key material using an
* existing key and additional parameters, iterating through a basic
* cryptographic function, such as a hash.
@@ -825,53 +834,46 @@
* for both of the flows.
*
* There are two different final functions for the flows,
- * `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.
- * `psa_drv_key_derivation_export` is used when the key material should be returned
- * to the PSA Cryptographic API implementation.
+ * `psa_drv_se_key_derivation_derive` and `psa_drv_se_key_derivation_export`.
+ * `psa_drv_se_key_derivation_derive` is used when the key material should be
+ * placed in a slot on the hardware and not exposed to the caller.
+ * `psa_drv_se_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, `psa_drv_key_derivation_collateral`, that is
- * called multiple times with different `collateral_id`s. Thus, for a key
+ * to the driver via a function, `psa_drv_se_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}
- * 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();
+ * psa_drv_se_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_0,
+ * p_collateral_0,
+ * collateral_0_size);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_1,
+ * p_collateral_1,
+ * collateral_1_size);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_2,
+ * p_collateral_2,
+ * collateral_2_size);
+ * psa_drv_se_key_derivation_derive();
* ~~~~~~~~~~~~~
*
* key agreement example:
* ~~~~~~~~~~~~~{.c}
- * 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);
+ * psa_drv_se_key_derivation_setup(alg, source_key. dest_key_size_bytes);
+ * psa_drv_se_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size);
+ * psa_drv_se_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 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
+/** \brief A function that Sets up a secure element 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
@@ -881,12 +883,12 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(void *p_context,
+ psa_algorithm_t kdf_alg,
+ psa_key_slot_number_t source_key);
-/** \brief Provide collateral (parameters) needed for a key derivation or key
- * agreement operation
+/** \brief A function that provides collateral (parameters) needed for a secure
+ * element 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
@@ -900,13 +902,14 @@
*
* \retval PSA_SUCCESS
*/
-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);
+typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *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
+/** \brief A function that performs the final secure element key derivation
+ * step and place the generated key material in a slot
+ *
* \param[in,out] p_context A hardware-specific structure containing any
* context information for the implementation
* \param[in] dest_key The slot where the generated key material
@@ -914,11 +917,11 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_key_derivation_derive_t)(psa_drv_key_derivation_context_t *p_context,
- psa_key_slot_t dest_key);
+typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *p_context,
+ psa_key_slot_number_t dest_key);
-/** \brief Perform the final step of a key agreement and place the generated
- * key material in a buffer
+/** \brief A function that performs the final step of a secure element key
+ * agreement and place the generated key material in a buffer
*
* \param[out] p_output Buffer in which to place the generated key
* material
@@ -928,13 +931,14 @@
*
* \retval PSA_SUCCESS
*/
-typedef psa_status_t (*psa_drv_key_derivation_export_t)(uint8_t *p_output,
- size_t output_size,
- size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *p_context,
+ 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
+ * \brief A struct containing all of the function pointers needed to for secure
+ * element key derivation and agreement
*
* PSA Crypto API implementations should populate instances of the table as
* appropriate upon startup.
@@ -942,16 +946,18 @@
* If one of the functions is not implemented, it should be set to NULL.
*/
typedef struct {
- /** Function that performs the key derivation setup */
- psa_drv_key_derivation_setup_t *p_setup;
- /** Function that sets the key derivation collateral */
- psa_drv_key_derivation_collateral_t *p_collateral;
- /** Function that performs the final key derivation step */
- psa_drv_key_derivation_derive_t *p_derive;
- /** Function that perforsm the final key derivation or agreement and
+ /** The driver-specific size of the key derivation context */
+ size_t context_size;
+ /** Function that performs a key derivation setup */
+ psa_drv_se_key_derivation_setup_t p_setup;
+ /** Function that sets key derivation collateral */
+ psa_drv_se_key_derivation_collateral_t p_collateral;
+ /** Function that performs a final key derivation step */
+ psa_drv_se_key_derivation_derive_t p_derive;
+ /** Function that perforsm a final key derivation or agreement and
* exports the key */
- psa_drv_key_derivation_export_t *p_export;
-} psa_drv_key_derivation_t;
+ psa_drv_se_key_derivation_export_t p_export;
+} psa_drv_se_key_derivation_t;
/**@}*/
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index e1ac630..3c879e8 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -313,9 +313,9 @@
(plaintext_length) - PSA_AEAD_TAG_LENGTH(alg) : \
0)
-#define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
- (PSA_ALG_IS_RSA_OAEP(alg) ? \
- 2 * PSA_HASH_FINAL_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
+#define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
+ (PSA_ALG_IS_RSA_OAEP(alg) ? \
+ 2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
11 /*PKCS#1v1.5*/)
/**
@@ -438,25 +438,16 @@
/* Maximum size of the export encoding of an RSA public key.
* Assumes that the public exponent is less than 2^32.
*
- * SubjectPublicKeyInfo ::= SEQUENCE {
- * algorithm AlgorithmIdentifier,
- * subjectPublicKey BIT STRING } -- contains RSAPublicKey
- * AlgorithmIdentifier ::= SEQUENCE {
- * algorithm OBJECT IDENTIFIER,
- * parameters NULL }
* RSAPublicKey ::= SEQUENCE {
* modulus INTEGER, -- n
* publicExponent INTEGER } -- e
*
- * - 3 * 4 bytes of SEQUENCE overhead;
- * - 1 + 1 + 9 bytes of algorithm (RSA OID);
- * - 2 bytes of NULL;
- * - 4 bytes of BIT STRING overhead;
+ * - 4 bytes of SEQUENCE overhead;
* - n : INTEGER;
* - 7 bytes for the public exponent.
*/
#define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) \
- (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 36)
+ (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11)
/* Maximum size of the export encoding of an RSA key pair.
* Assumes thatthe public exponent is less than 2^32 and that the size
@@ -523,26 +514,16 @@
/* Maximum size of the export encoding of an ECC public key.
*
- * SubjectPublicKeyInfo ::= SEQUENCE {
- * algorithm AlgorithmIdentifier,
- * subjectPublicKey BIT STRING } -- contains ECPoint
- * AlgorithmIdentifier ::= SEQUENCE {
- * algorithm OBJECT IDENTIFIER,
- * parameters OBJECT IDENTIFIER } -- namedCurve
- * ECPoint ::= ...
- * -- first 8 bits: 0x04;
- * -- then x_P as a `ceiling(m/8)`-byte string, big endian;
- * -- then y_P as a `ceiling(m/8)`-byte string, big endian;
- * -- where `m` is the bit size associated with the curve.
+ * The representation of an ECC public key is:
+ * - The byte 0x04;
+ * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
+ * - `y_P` as a `ceiling(m/8)`-byte string, big-endian;
+ * - where m is the bit size associated with the curve.
*
- * - 2 * 4 bytes of SEQUENCE overhead;
- * - 1 + 1 + 7 bytes of algorithm (id-ecPublicKey OID);
- * - 1 + 1 + 12 bytes of namedCurve OID;
- * - 4 bytes of BIT STRING overhead;
- * - 1 byte + 2 * point size in ECPoint.
+ * - 1 byte + 2 * point size.
*/
#define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) \
- (2 * PSA_BITS_TO_BYTES(key_bits) + 36)
+ (2 * PSA_BITS_TO_BYTES(key_bits) + 1)
/* Maximum size of the export encoding of an ECC key pair.
*
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 637e07c..7054de7 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -47,8 +47,13 @@
* This is either #PSA_SUCCESS (which is zero), indicating success,
* or a nonzero value indicating that an error occurred. Errors are
* encoded as one of the \c PSA_ERROR_xxx values defined here.
+ * If #PSA_SUCCESS is already defined, it means that #psa_status_t
+ * is also defined in an external header, so prevent its multiple
+ * definition.
*/
+#ifndef PSA_SUCCESS
typedef int32_t psa_status_t;
+#endif
/**@}*/
@@ -85,7 +90,14 @@
/** Encoding of identifiers of persistent keys.
*/
+/* Implementation-specific quirk: The Mbed Crypto library can be built as
+ * part of a multi-client service that exposes the PSA Crypto API in each
+ * client and encodes the client identity in the key id argument of functions
+ * such as psa_open_key(). In this build configuration, we define
+ * psa_key_id_t in crypto_platform.h instead of here. */
+#if !defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
typedef uint32_t psa_key_id_t;
+#endif
/**@}*/
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index f6ce04e..f9ac00a 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -40,25 +40,17 @@
* @{
*/
-#if !defined(PSA_SUCCESS)
-/* If PSA_SUCCESS is defined, assume that PSA crypto is being used
- * together with PSA IPC, which also defines the identifier
- * PSA_SUCCESS. We must not define PSA_SUCCESS ourselves in that case;
- * the other error code names don't clash. This is a temporary hack
- * until we unify error reporting in PSA IPC and PSA crypto.
- *
- * Note that psa_defs.h must be included before this header!
- */
+/* PSA error codes */
+
/** The action was completed successfully. */
#define PSA_SUCCESS ((psa_status_t)0)
-#endif /* !defined(PSA_SUCCESS) */
/** An error occurred that does not correspond to any defined
* failure cause.
*
* Implementations may use this error code if none of the other standard
* error codes are applicable. */
-#define PSA_ERROR_UNKNOWN_ERROR ((psa_status_t)1)
+#define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132)
/** The requested operation or a parameter is not supported
* by this implementation.
@@ -67,7 +59,7 @@
* parameter such as a key type, algorithm, etc. is not recognized.
* If a combination of parameters is recognized and identified as
* not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */
-#define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)2)
+#define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)-134)
/** The requested action is denied by a policy.
*
@@ -80,7 +72,7 @@
* not valid or not supported, it is unspecified whether the function
* returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or
* #PSA_ERROR_INVALID_ARGUMENT. */
-#define PSA_ERROR_NOT_PERMITTED ((psa_status_t)3)
+#define PSA_ERROR_NOT_PERMITTED ((psa_status_t)-133)
/** An output buffer is too small.
*
@@ -92,23 +84,19 @@
* buffer would succeed. However implementations may return this
* error if a function has invalid or unsupported parameters in addition
* to the parameters that determine the necessary output buffer size. */
-#define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)4)
+#define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)-138)
-/** A slot is occupied, but must be empty to carry out the
- * requested action.
+/** Asking for an item that already exists
*
- * If a handle is invalid, it does not designate an occupied slot.
- * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
- */
-#define PSA_ERROR_OCCUPIED_SLOT ((psa_status_t)5)
+ * Implementations should return this error, when attempting
+ * to write an item (like a key) that already exists. */
+#define PSA_ERROR_ALREADY_EXISTS ((psa_status_t)-139)
-/** A slot is empty, but must be occupied to carry out the
- * requested action.
+/** Asking for an item that doesn't exist
*
- * If a handle is invalid, it does not designate an empty slot.
- * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
- */
-#define PSA_ERROR_EMPTY_SLOT ((psa_status_t)6)
+ * Implementations should return this error, if a requested item (like
+ * a key) does not exist. */
+#define PSA_ERROR_DOES_NOT_EXIST ((psa_status_t)-140)
/** The requested action cannot be performed in the current state.
*
@@ -118,9 +106,9 @@
*
* Implementations shall not return this error code to indicate
* that a key slot is occupied when it needs to be free or vice versa,
- * but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
+ * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
* as applicable. */
-#define PSA_ERROR_BAD_STATE ((psa_status_t)7)
+#define PSA_ERROR_BAD_STATE ((psa_status_t)-137)
/** The parameters passed to the function are invalid.
*
@@ -129,20 +117,20 @@
*
* Implementations shall not return this error code to indicate
* that a key slot is occupied when it needs to be free or vice versa,
- * but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
+ * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
* as applicable.
*
* Implementation shall not return this error code to indicate that a
* key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE
* instead.
*/
-#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)8)
+#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135)
/** There is not enough runtime memory.
*
* If the action is carried out across multiple security realms, this
* error can refer to available memory in any of the security realms. */
-#define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)9)
+#define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)-141)
/** There is not enough persistent storage.
*
@@ -151,7 +139,7 @@
* many functions that do not otherwise access storage may return this
* error code if the implementation requires a mandatory log entry for
* the requested action and the log storage space is full. */
-#define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)10)
+#define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)-142)
/** There was a communication failure inside the implementation.
*
@@ -168,7 +156,7 @@
* cryptoprocessor but there was a breakdown of communication before
* the cryptoprocessor could report the status to the application.
*/
-#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)11)
+#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145)
/** There was a storage failure that may have led to data loss.
*
@@ -193,13 +181,13 @@
* permanent storage corruption. However application writers should
* keep in mind that transient errors while reading the storage may be
* reported using this error code. */
-#define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)12)
+#define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)-146)
/** A hardware failure was detected.
*
* A hardware failure may be transient or permanent depending on the
* cause. */
-#define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)13)
+#define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)-147)
/** A tampering attempt was detected.
*
@@ -230,7 +218,7 @@
* This error indicates an attack against the application. Implementations
* shall not return this error code as a consequence of the behavior of
* the application itself. */
-#define PSA_ERROR_TAMPERING_DETECTED ((psa_status_t)14)
+#define PSA_ERROR_TAMPERING_DETECTED ((psa_status_t)-151)
/** There is not enough entropy to generate random data needed
* for the requested action.
@@ -249,7 +237,7 @@
* secure pseudorandom generator (PRNG). However implementations may return
* this error at any time if a policy requires the PRNG to be reseeded
* during normal operation. */
-#define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)15)
+#define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148)
/** The signature, MAC or hash is incorrect.
*
@@ -259,7 +247,7 @@
*
* If the value to verify has an invalid size, implementations may return
* either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */
-#define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)16)
+#define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149)
/** The decrypted padding is incorrect.
*
@@ -275,17 +263,15 @@
* as close as possible to indistinguishable to an external observer.
* In particular, the timing of a decryption operation should not
* depend on the validity of the padding. */
-#define PSA_ERROR_INVALID_PADDING ((psa_status_t)17)
+#define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150)
-/** The generator has insufficient capacity left.
- *
- * Once a function returns this error, attempts to read from the
- * generator will always return this error. */
-#define PSA_ERROR_INSUFFICIENT_CAPACITY ((psa_status_t)18)
+/** Return this error when there's insufficient data when attempting
+ * to read from a resource. */
+#define PSA_ERROR_INSUFFICIENT_DATA ((psa_status_t)-143)
/** The key handle is not valid.
*/
-#define PSA_ERROR_INVALID_HANDLE ((psa_status_t)19)
+#define PSA_ERROR_INVALID_HANDLE ((psa_status_t)-136)
/**@}*/
@@ -663,15 +649,18 @@
/** SHA3-512 */
#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013)
-/** Allow any hash algorithm.
+/** In a hash-and-sign algorithm policy, allow any hash algorithm.
*
- * This value may only be used to form the algorithm usage field of a policy
- * for a signature algorithm that is parametrized by a hash. That is,
- * suppose that `PSA_xxx_SIGNATURE` is one of the following macros:
+ * This value may be used to form the algorithm usage field of a policy
+ * for a signature algorithm that is parametrized by a hash. The key
+ * may then be used to perform operations using the same signature
+ * algorithm parametrized with any supported hash.
+ *
+ * That is, suppose that `PSA_xxx_SIGNATURE` is one of the following macros:
* - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS,
* - #PSA_ALG_DSA, #PSA_ALG_DETERMINISTIC_DSA,
* - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA.
- * Then you may create a key as follows:
+ * Then you may create and use a key as follows:
* - Set the key usage field using #PSA_ALG_ANY_HASH, for example:
* ```
* psa_key_policy_set_usage(&policy,
@@ -758,7 +747,7 @@
* algorithm is considered identical to the untruncated algorithm
* for policy comparison purposes.
*
- * \param alg A MAC algorithm identifier (value of type
+ * \param mac_alg A MAC algorithm identifier (value of type
* #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
@@ -774,14 +763,14 @@
* MAC algorithm or if \p mac_length is too small or
* too large for the specified MAC algorithm.
*/
-#define PSA_ALG_TRUNCATED_MAC(alg, mac_length) \
- (((alg) & ~PSA_ALG_MAC_TRUNCATION_MASK) | \
+#define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
+ (((mac_alg) & ~PSA_ALG_MAC_TRUNCATION_MASK) | \
((mac_length) << PSA_MAC_TRUNCATION_OFFSET & PSA_ALG_MAC_TRUNCATION_MASK))
/** Macro to build the base MAC algorithm corresponding to a truncated
* MAC algorithm.
*
- * \param alg A MAC algorithm identifier (value of type
+ * \param mac_alg A MAC algorithm identifier (value of type
* #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
@@ -790,12 +779,12 @@
* \return Unspecified if \p alg is not a supported
* MAC algorithm.
*/
-#define PSA_ALG_FULL_LENGTH_MAC(alg) \
- ((alg) & ~PSA_ALG_MAC_TRUNCATION_MASK)
+#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \
+ ((mac_alg) & ~PSA_ALG_MAC_TRUNCATION_MASK)
/** Length to which a MAC algorithm is truncated.
*
- * \param alg A MAC algorithm identifier (value of type
+ * \param mac_alg A MAC algorithm identifier (value of type
* #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
* is true).
*
@@ -804,8 +793,8 @@
* \return Unspecified if \p alg is not a supported
* MAC algorithm.
*/
-#define PSA_MAC_TRUNCATED_LENGTH(alg) \
- (((alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET)
+#define PSA_MAC_TRUNCATED_LENGTH(mac_alg) \
+ (((mac_alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET)
#define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x02c00000)
#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02c00001)
@@ -907,7 +896,7 @@
* Depending on the algorithm, the tag length may affect the calculation
* of the ciphertext.
*
- * \param alg A AEAD algorithm identifier (value of type
+ * \param aead_alg An AEAD algorithm identifier (value of type
* #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
* is true).
* \param tag_length Desired length of the authentication tag in bytes.
@@ -918,26 +907,26 @@
* AEAD algorithm or if \p tag_length is not valid
* for the specified AEAD algorithm.
*/
-#define PSA_ALG_AEAD_WITH_TAG_LENGTH(alg, tag_length) \
- (((alg) & ~PSA_ALG_AEAD_TAG_LENGTH_MASK) | \
+#define PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, tag_length) \
+ (((aead_alg) & ~PSA_ALG_AEAD_TAG_LENGTH_MASK) | \
((tag_length) << PSA_AEAD_TAG_LENGTH_OFFSET & \
PSA_ALG_AEAD_TAG_LENGTH_MASK))
/** Calculate the corresponding AEAD algorithm with the default tag length.
*
- * \param alg An AEAD algorithm (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(\p alg) is true).
+ * \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_AEAD(\p alg) is true).
*
- * \return The corresponding AEAD algorithm with the default tag length
- * for that algorithm.
+ * \return The corresponding AEAD algorithm with the default
+ * tag length for that algorithm.
*/
-#define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(alg) \
+#define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(aead_alg) \
( \
- PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, PSA_ALG_CCM) \
- PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, PSA_ALG_GCM) \
+ PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_CCM) \
+ PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_GCM) \
0)
-#define PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, ref) \
- PSA_ALG_AEAD_WITH_TAG_LENGTH(alg, 0) == \
+#define PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, ref) \
+ PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, 0) == \
PSA_ALG_AEAD_WITH_TAG_LENGTH(ref, 0) ? \
ref :