Crypto: Align to PSA Crypto headers 0.1.0a
This patch updates the PSA Crypto API headers to version
0.1.0a. The Crypto service implementation is updated when
needed to make sure the service is buildable and functional.
Change-Id: I63709db0d87f449012d0c8355658f1af1583b3ab
Signed-off-by: Antonio de Angelis <antonio.deangelis@arm.com>
diff --git a/interface/include/psa_crypto.h b/interface/include/psa_crypto.h
index 0bc8ad3..8db3767 100644
--- a/interface/include/psa_crypto.h
+++ b/interface/include/psa_crypto.h
@@ -4,7 +4,6 @@
* SPDX-License-Identifier: BSD-3-Clause
*
*/
-
/**
* \file psa_crypto.h
* \brief Platform Security Architecture cryptography module
@@ -13,9 +12,6 @@
#ifndef PSA_CRYPTO_H
#define PSA_CRYPTO_H
-/* The psa_crypto_platform.h header provides fundamental definitions used by
- * this header, which are specific to the platform being used.
- */
#include "psa_crypto_platform.h"
#include <stddef.h>
@@ -24,8 +20,7 @@
/* This __DOXYGEN_ONLY__ block contains mock definitions for things that
* must be defined in the psa_crypto_platform.h header. These mock definitions
* are present in this file as a convenience to generate pretty-printed
- * documentation that includes those definitions.
- */
+ * documentation that includes those definitions. */
/** \defgroup platform Implementation-specific definitions
* @{
@@ -58,20 +53,35 @@
#if !defined(PSA_SUCCESS)
+/**
+ * \brief Function return status.
+ *
+ * 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.
+ */
+typedef int32_t psa_status_t;
+
/** 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)
+
/** The requested operation or a parameter is not supported
* by this implementation.
*
* Implementations should return this error code when an enumeration
* 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)1)
+ * not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */
+#define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)2)
/** The requested action is denied by a policy.
*
@@ -83,40 +93,36 @@
* forbidden operation, and another subset of the parameters are
* 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)2)
+ * #PSA_ERROR_INVALID_ARGUMENT. */
+#define PSA_ERROR_NOT_PERMITTED ((psa_status_t)3)
/** An output buffer is too small.
*
- * Applications can call the `PSA_xxx_SIZE` macro listed in the function
+ * Applications can call the \c PSA_xxx_SIZE macro listed in the function
* description to determine a sufficient buffer size.
*
* Implementations should preferably return this error code only
* in cases when performing the operation with a larger output
* 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)3)
+ * to the parameters that determine the necessary output buffer size. */
+#define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)4)
/** A slot is occupied, but must be empty to carry out the
* requested action.
*
* If the slot number is invalid (i.e. the requested action could
* not be performed even after erasing the slot's content),
- * implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead.
- */
-#define PSA_ERROR_OCCUPIED_SLOT ((psa_status_t)4)
+ * implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
+#define PSA_ERROR_OCCUPIED_SLOT ((psa_status_t)5)
/** A slot is empty, but must be occupied to carry out the
* requested action.
*
* If the slot number is invalid (i.e. the requested action could
* not be performed even after creating appropriate content in the slot),
- * implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead.
- */
-#define PSA_ERROR_EMPTY_SLOT ((psa_status_t)5)
+ * implementations shall return #PSA_ERROR_INVALID_ARGUMENT instead. */
+#define PSA_ERROR_EMPTY_SLOT ((psa_status_t)6)
/** The requested action cannot be performed in the current state.
*
@@ -127,9 +133,8 @@
* 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
- * as applicable.
- */
-#define PSA_ERROR_BAD_STATE ((psa_status_t)6)
+ * as applicable. */
+#define PSA_ERROR_BAD_STATE ((psa_status_t)7)
/** The parameters passed to the function are invalid.
*
@@ -139,16 +144,14 @@
* 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
- * as applicable.
- */
-#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)7)
+ * as applicable. */
+#define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)8)
/** 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)8)
+ * error can refer to available memory in any of the security realms. */
+#define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)9)
/** There is not enough persistent storage.
*
@@ -156,9 +159,8 @@
* there is insufficient storage space on the host media. In addition,
* 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)9)
+ * the requested action and the log storage space is full. */
+#define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)10)
/** There was a communication failure inside the implementation.
*
@@ -175,7 +177,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)10)
+#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)11)
/** There was a storage failure that may have led to data loss.
*
@@ -199,16 +201,14 @@
* Implementations should only use this error code to report a
* 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)11)
+ * reported using this error code. */
+#define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)12)
/** 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)12)
+ * cause. */
+#define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)13)
/** A tampering attempt was detected.
*
@@ -238,9 +238,8 @@
*
* 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)13)
+ * the application itself. */
+#define PSA_ERROR_TAMPERING_DETECTED ((psa_status_t)14)
/** There is not enough entropy to generate random data needed
* for the requested action.
@@ -258,9 +257,8 @@
* entropy during initialization and subsequently use a cryptographically
* 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)14)
+ * during normal operation. */
+#define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)15)
/** The signature, MAC or hash is incorrect.
*
@@ -269,9 +267,8 @@
* was determined to be incorrect.
*
* 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)15)
+ * either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */
+#define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)16)
/** The decrypted padding is incorrect.
*
@@ -286,17 +283,14 @@
* Implementations should strive to make valid and invalid padding
* 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)16)
+ * depend on the validity of the padding. */
+#define PSA_ERROR_INVALID_PADDING ((psa_status_t)17)
-/** An error occurred that does not correspond to any defined
- * failure cause.
+/** The generator has insufficient capacity left.
*
- * Implementations may use this error code if none of the other standard
- * error codes are applicable.
- */
-#define PSA_ERROR_UNKNOWN_ERROR ((psa_status_t)17)
+ * 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)
/**
* \brief Library initialization.
@@ -307,12 +301,12 @@
* Applications may call this function more than once. Once a call
* succeeds, subsequent calls are guaranteed to succeed.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
- * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
*/
psa_status_t psa_crypto_init(void);
@@ -325,7 +319,8 @@
* @{
*/
-/** \brief Encoding of a key type. */
+/** \brief Encoding of a key type.
+ */
typedef uint32_t psa_key_type_t;
/** An invalid key type value.
@@ -344,12 +339,13 @@
#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x80000000)
#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7e000000)
+
/** Raw data.
*
* A "key" of this type cannot be used for any cryptographic operation.
- * Applications may use this type to store arbitrary data in the keystore.
- */
+ * Applications may use this type to store arbitrary data in the keystore. */
#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x02000000)
+
#define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x04000000)
#define PSA_KEY_TYPE_CATEGORY_ASYMMETRIC ((psa_key_type_t)0x06000000)
#define PSA_KEY_TYPE_PAIR_FLAG ((psa_key_type_t)0x01000000)
@@ -360,16 +356,24 @@
* used for.
*
* HMAC keys should generally have the same size as the underlying hash.
- * This size can be calculated with `PSA_HASH_SIZE(alg)` where
- * `alg` is the HMAC algorithm or the underlying hash algorithm.
- */
+ * This size can be calculated with #PSA_HASH_SIZE(\c alg) where
+ * \c alg is the HMAC algorithm or the underlying hash algorithm. */
#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001)
+
+/** A secret for key derivation.
+ *
+ * The key policy determines which key derivation algorithm the key
+ * can be used for.
+ */
+#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x02000101)
+
/** Key for an cipher, AEAD or MAC algorithm based on the AES block cipher.
*
* The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or
* 32 bytes (AES-256).
*/
#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x04000001)
+
/** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).
*
* The size of the key can be 8 bytes (single DES), 16 bytes (2-key 3DES) or
@@ -380,30 +384,34 @@
* is weak and deprecated and should only be used in legacy protocols.
*/
#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x04000002)
+
/** Key for an cipher, AEAD or MAC algorithm based on the
- * Camellia block cipher.
- */
+ * Camellia block cipher. */
#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x04000003)
+
/** Key for the RC4 stream cipher.
*
* Note that RC4 is weak and deprecated and should only be used in
- * legacy protocols.
- */
+ * legacy protocols. */
#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x04000004)
/** RSA public key. */
#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x06010000)
/** RSA key pair (private and public key). */
#define PSA_KEY_TYPE_RSA_KEYPAIR ((psa_key_type_t)0x07010000)
+
/** DSA public key. */
#define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x06020000)
/** DSA key pair (private and public key). */
#define PSA_KEY_TYPE_DSA_KEYPAIR ((psa_key_type_t)0x07020000)
+
#define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t)0x06030000)
#define PSA_KEY_TYPE_ECC_KEYPAIR_BASE ((psa_key_type_t)0x07030000)
#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff)
+/** Elliptic curve key pair. */
#define PSA_KEY_TYPE_ECC_KEYPAIR(curve) \
(PSA_KEY_TYPE_ECC_KEYPAIR_BASE | (curve))
+/** Elliptic curve public key. */
#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \
(PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve))
@@ -419,26 +427,32 @@
(((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG)) == \
PSA_KEY_TYPE_CATEGORY_ASYMMETRIC)
/** Whether a key type is a key pair containing a private part and a public
- * part.
- */
+ * part. */
#define PSA_KEY_TYPE_IS_KEYPAIR(type) \
(((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG)) == \
(PSA_KEY_TYPE_CATEGORY_ASYMMETRIC | PSA_KEY_TYPE_PAIR_FLAG))
-/** Whether a key type is an RSA key pair or public key. */
/** The key pair type corresponding to a public key type. */
#define PSA_KEY_TYPE_KEYPAIR_OF_PUBLIC_KEY(type) \
((type) | PSA_KEY_TYPE_PAIR_FLAG)
/** The public key type corresponding to a key pair type. */
#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) \
((type) & ~PSA_KEY_TYPE_PAIR_FLAG)
+/** Whether a key type is an RSA key (pair or public-only). */
#define PSA_KEY_TYPE_IS_RSA(type) \
(PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY)
-/** Whether a key type is an elliptic curve key pair or public key. */
+
+/** Whether a key type is an elliptic curve key (pair or public-only). */
#define PSA_KEY_TYPE_IS_ECC(type) \
((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) & \
~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE)
+#define PSA_KEY_TYPE_IS_ECC_KEYPAIR(type) \
+ (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == \
+ PSA_KEY_TYPE_ECC_KEYPAIR_BASE)
+#define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) \
+ (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == \
+ PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE)
-/** \brief The type of PSA elliptic curve identifiers. */
+/** The type of PSA elliptic curve identifiers. */
typedef uint16_t psa_ecc_curve_t;
/** Extract the curve from an elliptic curve key type. */
#define PSA_KEY_TYPE_GET_CURVE(type) \
@@ -449,10 +463,8 @@
/* The encoding of curve identifiers is currently aligned with the
* TLS Supported Groups Registry (formerly known as the
* TLS EC Named Curve Registry)
- * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml
- * #tls-parameters-8
- * The values are defined by RFC 4492, RFC 7027 and RFC 7919.
- */
+ * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
+ * The values are defined by RFC 4492, RFC 7027 and RFC 7919. */
#define PSA_ECC_CURVE_SECT163K1 ((psa_ecc_curve_t) 0x0001)
#define PSA_ECC_CURVE_SECT163R1 ((psa_ecc_curve_t) 0x0002)
#define PSA_ECC_CURVE_SECT163R2 ((psa_ecc_curve_t) 0x0003)
@@ -494,7 +506,7 @@
* \param type A cipher key type (value of type #psa_key_type_t).
*
* \return The block size for a block cipher, or 1 for a stream cipher.
- * The return value is undefined if \c type is not a supported
+ * The return value is undefined if \p type is not a supported
* cipher key type.
*
* \note It is possible to build stream cipher algorithms on top of a block
@@ -538,28 +550,93 @@
#define PSA_ALG_IS_VENDOR_DEFINED(alg) \
(((alg) & PSA_ALG_VENDOR_FLAG) != 0)
+
/** Whether the specified algorithm is a hash algorithm.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
- * \return 1 if \c alg is a hash algorithm, 0 otherwise.
- * This macro may return either 0 or 1 if \c alg is not a valid
+ * \return 1 if \p alg is a hash algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
* algorithm identifier.
*/
#define PSA_ALG_IS_HASH(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH)
+
+/** Whether the specified algorithm is a MAC algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a MAC algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_MAC(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC)
+
+/** Whether the specified algorithm is a symmetric cipher algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a symmetric cipher algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_CIPHER(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER)
+
+/** Whether the specified algorithm is an authenticated encryption
+ * with associated data (AEAD) algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is an AEAD algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_AEAD(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD)
+
+/** Whether the specified algorithm is a public-key signature algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a public-key signature algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_SIGN(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN)
+
+/** Whether the specified algorithm is a public-key encryption algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a public-key encryption algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION)
+
+/** Whether the specified algorithm is a key agreement algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a key agreement algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_KEY_AGREEMENT(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT)
+
+/** Whether the specified algorithm is a key derivation algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a key derivation algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_KEY_DERIVATION(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)
@@ -569,40 +646,73 @@
#define PSA_ALG_MD5 ((psa_algorithm_t)0x01000003)
#define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x01000004)
#define PSA_ALG_SHA_1 ((psa_algorithm_t)0x01000005)
+/** SHA2-224 */
#define PSA_ALG_SHA_224 ((psa_algorithm_t)0x01000008)
+/** SHA2-256 */
#define PSA_ALG_SHA_256 ((psa_algorithm_t)0x01000009)
+/** SHA2-384 */
#define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0100000a)
+/** SHA2-512 */
#define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0100000b)
+/** SHA2-512/224 */
#define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0100000c)
+/** SHA2-512/256 */
#define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0100000d)
+/** SHA3-224 */
#define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x01000010)
+/** SHA3-256 */
#define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x01000011)
+/** SHA3-384 */
#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x01000012)
+/** SHA3-512 */
#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013)
#define PSA_ALG_MAC_SUBCATEGORY_MASK ((psa_algorithm_t)0x00c00000)
#define PSA_ALG_HMAC_BASE ((psa_algorithm_t)0x02800000)
/** Macro to build an HMAC algorithm.
*
- * For example, `PSA_ALG_HMAC(PSA_ALG_SHA256)` is HMAC-SHA-256.
+ * For example, #PSA_ALG_HMAC(#PSA_ALG_SHA_256) is HMAC-SHA-256.
*
- * \param alg A hash algorithm (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_HASH(alg) is true).
+ * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true).
*
- * \return The corresponding HMAC algorithm.
- * \return Unspecified if \p alg is not a hash algorithm.
+ * \return The corresponding HMAC algorithm.
+ * \return Unspecified if \p alg is not a supported
+ * hash algorithm.
*/
#define PSA_ALG_HMAC(hash_alg) \
(PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+
#define PSA_ALG_HMAC_HASH(hmac_alg) \
(PSA_ALG_CATEGORY_HASH | ((hmac_alg) & PSA_ALG_HASH_MASK))
+
+/** Whether the specified algorithm is an HMAC algorithm.
+ *
+ * HMAC is a family of MAC algorithms that are based on a hash function.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is an HMAC algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_HMAC(alg) \
(((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \
PSA_ALG_HMAC_BASE)
+
#define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x02c00000)
#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02c00001)
#define PSA_ALG_CMAC ((psa_algorithm_t)0x02c00002)
#define PSA_ALG_GMAC ((psa_algorithm_t)0x02c00003)
+
+/** Whether the specified algorithm is a MAC algorithm based on a block cipher.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a MAC algorithm based on a block cipher, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier.
+ */
#define PSA_ALG_IS_CIPHER_MAC(alg) \
(((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \
PSA_ALG_CIPHER_MAC_BASE)
@@ -611,43 +721,304 @@
#define PSA_ALG_BLOCK_CIPHER_BASE ((psa_algorithm_t)0x04000000)
#define PSA_ALG_BLOCK_CIPHER_MODE_MASK ((psa_algorithm_t)0x000000ff)
#define PSA_ALG_BLOCK_CIPHER_PADDING_MASK ((psa_algorithm_t)0x003f0000)
+
+/** Use a block cipher mode without padding.
+ *
+ * This padding mode may only be used with messages whose lengths are a
+ * whole number of blocks for the chosen block cipher.
+ */
#define PSA_ALG_BLOCK_CIPHER_PAD_NONE ((psa_algorithm_t)0x00000000)
+
#define PSA_ALG_BLOCK_CIPHER_PAD_PKCS7 ((psa_algorithm_t)0x00010000)
+
+/** Whether the specified algorithm is a block cipher.
+ *
+ * A block cipher is a symmetric cipher that encrypts or decrypts messages
+ * by chopping them into fixed-size blocks. Processing a message requires
+ * applying a _padding mode_ to transform the message into one whose
+ * length is a whole number of blocks. To construct an algorithm
+ * identifier for a block cipher, apply a bitwise-or between the block
+ * cipher mode and the padding mode. For example, CBC with PKCS#7 padding
+ * is `PSA_ALG_CBC_BASE | PSA_ALG_BLOCK_CIPHER_PAD_PKCS7`.
+ *
+ * The transformation applied to each block is determined by the key type.
+ * For example, to use AES-128-CBC-PKCS7, use the algorithm above with
+ * a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes).
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a block cipher algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier or if it is not a symmetric cipher algorithm.
+ */
#define PSA_ALG_IS_BLOCK_CIPHER(alg) \
(((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \
PSA_ALG_BLOCK_CIPHER_BASE)
+/** The CBC block cipher mode.
+ */
#define PSA_ALG_CBC_BASE ((psa_algorithm_t)0x04000001)
#define PSA_ALG_CFB_BASE ((psa_algorithm_t)0x04000002)
#define PSA_ALG_OFB_BASE ((psa_algorithm_t)0x04000003)
#define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000004)
-#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800000)
+
+#define PSA_ALG_STREAM_CIPHER_BASE ((psa_algorithm_t)0x04800000)
+
+/** The CTR stream cipher mode.
+ *
+ * CTR is a stream cipher which is built from a block cipher. The
+ * underlying block cipher is determined by the key type. For example,
+ * to use AES-128-CTR, use this algorithm with
+ * a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes).
+ */
#define PSA_ALG_CTR ((psa_algorithm_t)0x04800001)
+
+/** The ARC4 stream cipher algorithm.
+ */
#define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800002)
+/** Whether the specified algorithm is a stream cipher.
+ *
+ * A stream cipher is a symmetric cipher that encrypts or decrypts messages
+ * by applying a bitwise-xor with a stream of bytes that is generated
+ * from a key.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a stream cipher algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \p alg is not a supported
+ * algorithm identifier or if it is not a symmetric cipher algorithm.
+ */
#define PSA_ALG_IS_STREAM_CIPHER(alg) \
(((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \
- PSA_ALG_STREAM_CIPHER)
+ PSA_ALG_STREAM_CIPHER_BASE)
#define PSA_ALG_CCM ((psa_algorithm_t)0x06000001)
#define PSA_ALG_GCM ((psa_algorithm_t)0x06000002)
-#define PSA_ALG_RSA_PKCS1V15_SIGN_RAW ((psa_algorithm_t)0x10010000)
-#define PSA_ALG_RSA_PSS_MGF1 ((psa_algorithm_t)0x10020000)
-#define PSA_ALG_RSA_PKCS1V15_CRYPT ((psa_algorithm_t)0x12010000)
-#define PSA_ALG_RSA_OAEP_MGF1_BASE ((psa_algorithm_t)0x12020000)
+#define PSA_ALG_RSA_PKCS1V15_SIGN_BASE ((psa_algorithm_t)0x10020000)
+/** RSA PKCS#1 v1.5 signature with hashing.
+ *
+ * This is the signature scheme defined by RFC 8017
+ * (PKCS#1: RSA Cryptography Specifications) under the name
+ * RSASSA-PKCS1-v1_5.
+ *
+ * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *
+ * \return The corresponding RSA PKCS#1 v1.5 signature algorithm.
+ * \return Unspecified if \p alg is not a supported
+ * hash algorithm.
+ */
#define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) \
- (PSA_ALG_RSA_PKCS1V15_SIGN_RAW | ((hash_alg) & PSA_ALG_HASH_MASK))
+ (PSA_ALG_RSA_PKCS1V15_SIGN_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+/** Raw PKCS#1 v1.5 signature.
+ *
+ * The input to this algorithm is the DigestInfo structure used by
+ * RFC 8017 (PKCS#1: RSA Cryptography Specifications), §9.2
+ * steps 3–6.
+ */
+#define PSA_ALG_RSA_PKCS1V15_SIGN_RAW PSA_ALG_RSA_PKCS1V15_SIGN_BASE
#define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) \
- (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PKCS1V15_SIGN_RAW)
-#define PSA_ALG_RSA_OAEP_MGF1(hash_alg) \
- (PSA_ALG_RSA_OAEP_MGF1_RAW | ((hash_alg) & PSA_ALG_HASH_MASK))
-#define PSA_ALG_IS_RSA_OAEP_MGF1(alg) \
- (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_OAEP_MGF1_BASE)
-#define PSA_ALG_RSA_GET_HASH(alg) \
- (((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH)
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PKCS1V15_SIGN_BASE)
-#define PSA_ALG_ECDSA_RAW ((psa_algorithm_t)0x10030000)
+#define PSA_ALG_RSA_PSS_BASE ((psa_algorithm_t)0x10030000)
+/** RSA PSS signature with hashing.
+ *
+ * This is the signature scheme defined by RFC 8017
+ * (PKCS#1: RSA Cryptography Specifications) under the name
+ * RSASSA-PSS, with the message generation function MGF1, and with
+ * a salt length equal to the length of the hash. The specified
+ * hash algorithm is used to hash the input message, to create the
+ * salted hash, and for the mask generation.
+ *
+ * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *
+ * \return The corresponding RSA PSS signature algorithm.
+ * \return Unspecified if \p alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_RSA_PSS(hash_alg) \
+ (PSA_ALG_RSA_PSS_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+#define PSA_ALG_IS_RSA_PSS(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PSS_BASE)
+
+#define PSA_ALG_DSA_BASE ((psa_algorithm_t)0x10040000)
+/** DSA signature with hashing.
+ *
+ * This is the signature scheme defined by FIPS 186-4,
+ * with a random per-message secret number (*k*).
+ *
+ * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *
+ * \return The corresponding DSA signature algorithm.
+ * \return Unspecified if \p alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_DSA(hash_alg) \
+ (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+#define PSA_ALG_DETERMINISTIC_DSA_BASE ((psa_algorithm_t)0x10050000)
+#define PSA_ALG_DSA_DETERMINISTIC_FLAG ((psa_algorithm_t)0x00010000)
+#define PSA_ALG_DETERMINISTIC_DSA(hash_alg) \
+ (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+#define PSA_ALG_IS_DSA(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
+ PSA_ALG_DSA_BASE)
+#define PSA_ALG_DSA_IS_DETERMINISTIC(alg) \
+ (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
+#define PSA_ALG_IS_DETERMINISTIC_DSA(alg) \
+ (PSA_ALG_IS_DSA(alg) && PSA_ALG_DSA_IS_DETERMINISTIC(alg))
+#define PSA_ALG_IS_RANDOMIZED_DSA(alg) \
+ (PSA_ALG_IS_DSA(alg) && !PSA_ALG_DSA_IS_DETERMINISTIC(alg))
+
+#define PSA_ALG_ECDSA_BASE ((psa_algorithm_t)0x10060000)
+/** ECDSA signature with hashing.
+ *
+ * This is the ECDSA signature scheme defined by ANSI X9.62,
+ * with a random per-message secret number (*k*).
+ *
+ * The representation of the signature as a byte string consists of
+ * the concatentation of the signature values *r* and *s*. Each of
+ * *r* and *s* is encoded as an *N*-octet string, where *N* is the length
+ * of the base point of the curve in octets. Each value is represented
+ * in big-endian order (most significant octet first).
+ *
+ * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *
+ * \return The corresponding ECDSA signature algorithm.
+ * \return Unspecified if \p alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_ECDSA(hash_alg) \
+ (PSA_ALG_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+/** ECDSA signature without hashing.
+ *
+ * This is the same signature scheme as #PSA_ALG_ECDSA(), but
+ * without specifying a hash algorithm. This algorithm may only be
+ * used to sign or verify a sequence of bytes that should be an
+ * already-calculated hash. Note that the input is padded with
+ * zeros on the left or truncated on the left as required to fit
+ * the curve size.
+ */
+#define PSA_ALG_ECDSA_ANY PSA_ALG_ECDSA_BASE
+#define PSA_ALG_DETERMINISTIC_ECDSA_BASE ((psa_algorithm_t)0x10070000)
+/** Deterministic ECDSA signature with hashing.
+ *
+ * This is the deterministic ECDSA signature scheme defined by RFC 6979.
+ *
+ * The representation of a signature is the same as with #PSA_ALG_ECDSA().
+ *
+ * Note that when this algorithm is used for verification, signatures
+ * made with randomized ECDSA (#PSA_ALG_ECDSA(\p hash_alg)) with the
+ * same private key are accepted. In other words,
+ * #PSA_ALG_DETERMINISTIC_ECDSA(\p hash_alg) differs from
+ * #PSA_ALG_ECDSA(\p hash_alg) only for signature, not for verification.
+ *
+ * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *
+ * \return The corresponding deterministic ECDSA signature
+ * algorithm.
+ * \return Unspecified if \p alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) \
+ (PSA_ALG_DETERMINISTIC_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+#define PSA_ALG_IS_ECDSA(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \
+ PSA_ALG_ECDSA_BASE)
+#define PSA_ALG_ECDSA_IS_DETERMINISTIC(alg) \
+ (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0)
+#define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) \
+ (PSA_ALG_IS_ECDSA(alg) && PSA_ALG_ECDSA_IS_DETERMINISTIC(alg))
+#define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \
+ (PSA_ALG_IS_ECDSA(alg) && !PSA_ALG_ECDSA_IS_DETERMINISTIC(alg))
+
+/** Get the hash used by a hash-and-sign signature algorithm.
+ *
+ * A hash-and-sign algorithm is a signature algorithm which is
+ * composed of two phases: first a hashing phase which does not use
+ * the key and produces a hash of the input message, then a signing
+ * phase which only uses the hash and the key and not the message
+ * itself.
+ *
+ * \param alg A signature algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_SIGN(\p alg) is true).
+ *
+ * \return The underlying hash algorithm if \p alg is a hash-and-sign
+ * algorithm.
+ * \return 0 if \p alg is a signature algorithm that does not
+ * follow the hash-and-sign structure.
+ * \return Unspecified if \p alg is not a signature algorithm or
+ * if it is not supported by the implementation.
+ */
+#define PSA_ALG_SIGN_GET_HASH(alg) \
+ (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \
+ PSA_ALG_IS_DSA(alg) || PSA_ALG_IS_ECDSA(alg) ? \
+ ((alg) & PSA_ALG_HASH_MASK) == 0 ? /*"raw" algorithm*/ 0 : \
+ ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \
+ 0)
+
+/** RSA PKCS#1 v1.5 encryption.
+ */
+#define PSA_ALG_RSA_PKCS1V15_CRYPT ((psa_algorithm_t)0x12020000)
+
+#define PSA_ALG_RSA_OAEP_BASE ((psa_algorithm_t)0x12030000)
+/** RSA OAEP encryption.
+ *
+ * This is the encryption scheme defined by RFC 8017
+ * (PKCS#1: RSA Cryptography Specifications) under the name
+ * RSAES-OAEP, with the message generation function MGF1.
+ *
+ * \param hash_alg The hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true) to use
+ * for MGF1.
+ *
+ * \return The corresponding RSA OAEP signature algorithm.
+ * \return Unspecified if \p alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_RSA_OAEP(hash_alg) \
+ (PSA_ALG_RSA_OAEP_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+#define PSA_ALG_IS_RSA_OAEP(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_OAEP_BASE)
+#define PSA_ALG_RSA_OAEP_GET_HASH(alg) \
+ (PSA_ALG_IS_RSA_OAEP(alg) ? \
+ ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \
+ 0)
+
+#define PSA_ALG_HKDF_BASE ((psa_algorithm_t)0x30000100)
+/** Macro to build an HKDF algorithm.
+ *
+ * For example, `PSA_ALG_HKDF(PSA_ALG_SHA256)` is HKDF using HMAC-SHA-256.
+ *
+ * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *
+ * \return The corresponding HKDF algorithm.
+ * \return Unspecified if \p alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_HKDF(hash_alg) \
+ (PSA_ALG_HKDF_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+/** Whether the specified algorithm is an HKDF algorithm.
+ *
+ * HKDF is a family of key derivation algorithms that are based on a hash
+ * function and the HMAC construction.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \c alg is an HKDF algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \c alg is not a supported
+ * key derivation algorithm identifier.
+ */
+#define PSA_ALG_IS_HKDF(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_BASE)
+#define PSA_ALG_HKDF_GET_HASH(hkdf_alg) \
+ (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK))
/**@}*/
@@ -665,24 +1036,24 @@
* valid slot for a key of the chosen type. It must
* be unoccupied.
* \param type Key type (a \c PSA_KEY_TYPE_XXX value).
- * \param data Buffer containing the key data.
- * \param data_length Size of the \c data buffer in bytes.
+ * \param[in] data Buffer containing the key data.
+ * \param data_length Size of the \p data buffer in bytes.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_NOT_SUPPORTED
* The key type or key size is not supported, either by the
* implementation in general or in this particular slot.
- * \retval PSA_ERROR_INVALID_ARGUMENT
+ * \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_OCCUPIED_SLOT
* There is already a key in the specified slot.
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_import_key(psa_key_slot_t key,
psa_key_type_t type,
@@ -702,22 +1073,22 @@
*
* \param key The key slot to erase.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The slot's content, if any, has been erased.
- * \retval PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_NOT_PERMITTED
* The slot holds content and cannot be erased because it is
* read-only, either due to a policy or due to physical restrictions.
- * \retval PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
* The specified slot number does not designate a valid slot.
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
* There was an failure in communication with the cryptoprocessor.
* The key material may still be present in the cryptoprocessor.
- * \retval PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
* The storage is corrupted. Implementations shall make a best effort
* to erase key material even in this stage, however applications
* should be aware that it may be impossible to guarantee that the
* key material is not recoverable in such cases.
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
* An unexpected condition which is not a storage corruption or
* a communication failure occurred. The cryptoprocessor may have
* been compromised.
@@ -729,18 +1100,18 @@
*
* \param key Slot whose content is queried. This must
* be an occupied key slot.
- * \param type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
+ * \param[out] type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
* This may be a null pointer, in which case the key type
* is not written.
- * \param bits On success, the key size in bits.
+ * \param[out] bits On success, the key size in bits.
* This may be a null pointer, in which case the key size
* is not written.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_EMPTY_SLOT
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_get_key_information(psa_key_slot_t key,
psa_key_type_t *type,
@@ -766,24 +1137,25 @@
* - 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\#8 (RFC 5208)
- * as PrivateKeyInfo.
+ * 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.
*
- * \param key Slot whose content is to be exported. This must
- * be an occupied key slot.
- * \param data Buffer where the key data is to be written.
- * \param data_size Size of the \c data buffer in bytes.
- * \param data_length On success, the number of bytes
- * that make up the key data.
+ * \param key Slot whose content is to be exported. This must
+ * be an occupied key slot.
+ * \param[out] data Buffer where the key data is to be written.
+ * \param data_size Size of the \p data buffer in bytes.
+ * \param[out] data_length On success, the number of bytes
+ * that make up the key data.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_EMPTY_SLOT
- * \retval PSA_ERROR_NOT_PERMITTED
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \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
*/
psa_status_t psa_export_key(psa_key_slot_t key,
uint8_t *data,
@@ -802,19 +1174,19 @@
* the format is the DER representation of the public key defined by RFC 5280
* as SubjectPublicKeyInfo.
*
- * \param key Slot whose content is to be exported. This must
- * be an occupied key slot.
- * \param data Buffer where the key data is to be written.
- * \param data_size Size of the \c data buffer in bytes.
- * \param data_length On success, the number of bytes
- * that make up the key data.
+ * \param key Slot whose content is to be exported. This must
+ * be an occupied key slot.
+ * \param[out] data Buffer where the key data is to be written.
+ * \param data_size Size of the \p data buffer in bytes.
+ * \param[out] data_length On success, the number of bytes
+ * that make up the key data.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_EMPTY_SLOT
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_export_public_key(psa_key_slot_t key,
uint8_t *data,
@@ -845,38 +1217,61 @@
/** Whether the key may be used to encrypt a message.
*
+ * This flag allows the key to be used for a symmetric encryption operation,
+ * for an AEAD encryption-and-authentication operation,
+ * or for an asymmetric encryption operation,
+ * if otherwise permitted by the key's type and policy.
+ *
* For a key pair, this concerns the public key.
*/
#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100)
/** Whether the key may be used to decrypt a message.
*
+ * This flag allows the key to be used for a symmetric decryption operation,
+ * for an AEAD decryption-and-verification operation,
+ * or for an asymmetric decryption operation,
+ * if otherwise permitted by the key's type and policy.
+ *
* For a key pair, this concerns the private key.
*/
#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200)
/** Whether the key may be used to sign a message.
*
+ * This flag allows the key to be used for a MAC calculation operation
+ * or for an asymmetric signature operation,
+ * if otherwise permitted by the key's type and policy.
+ *
* For a key pair, this concerns the private key.
*/
#define PSA_KEY_USAGE_SIGN ((psa_key_usage_t)0x00000400)
/** Whether the key may be used to verify a message signature.
*
+ * This flag allows the key to be used for a MAC verification operation
+ * or for an asymmetric signature verification operation,
+ * if otherwise permitted by by the key's type and policy.
+ *
* For a key pair, this concerns the public key.
*/
#define PSA_KEY_USAGE_VERIFY ((psa_key_usage_t)0x00000800)
-/** \brief The type of the key policy data structure.
- *
- * This is an implementation-defined type. Applications should not
- * make any assumptions about this type except
- * as directed by the documentation of a specific implementation.
+/** Whether the key may be used to derive other keys.
*/
-typedef uint32_t psa_key_policy_t;
+#define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00001000)
+
+/** The type of the key policy data structure.
+ *
+ * This is an implementation-defined \c struct. Applications should not
+ * make any assumptions about the content of this structure except
+ * as directed by the documentation of a specific implementation. */
+typedef struct psa_key_policy_s psa_key_policy_t;
/** \brief Initialize a key policy structure to a default that forbids all
* usage of the key.
+ *
+ * \param[out] policy The policy object to initialize.
*/
void psa_key_policy_init(psa_key_policy_t *policy);
@@ -885,14 +1280,30 @@
* Note that this function does not make any consistency check of the
* parameters. The values are only checked when applying the policy to
* a key slot with psa_set_key_policy().
+ *
+ * \param[out] policy The policy object to modify.
+ * \param usage The permitted uses for the key.
+ * \param alg The algorithm that the key may be used for.
*/
void psa_key_policy_set_usage(psa_key_policy_t *policy,
psa_key_usage_t usage,
psa_algorithm_t alg);
-psa_key_usage_t psa_key_policy_get_usage(psa_key_policy_t *policy);
+/** \brief Retrieve the usage field of a policy structure.
+ *
+ * \param[in] policy The policy object to query.
+ *
+ * \return The permitted uses for a key with this policy.
+ */
+psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy);
-psa_algorithm_t psa_key_policy_get_algorithm(psa_key_policy_t *policy);
+/** \brief Retrieve the algorithm field of a policy structure.
+ *
+ * \param[in] policy The policy object to query.
+ *
+ * \return The permitted algorithm for a key with this policy.
+ */
+psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
/** \brief Set the usage policy on a key slot.
*
@@ -902,11 +1313,31 @@
*
* Implementations may set restrictions on supported key policies
* depending on the key type and the key slot.
+ *
+ * \param key The key slot whose policy is to be changed.
+ * \param[in] policy The policy object to query.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_set_key_policy(psa_key_slot_t key,
const psa_key_policy_t *policy);
-/** \brief Get the usage policy for a key slot. */
+/** \brief Get the usage policy for a key slot.
+ *
+ * \param key The key slot whose policy is being queried.
+ * \param[out] policy On success, the key's policy.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
psa_status_t psa_get_key_policy(psa_key_slot_t key,
psa_key_policy_t *policy);
@@ -916,7 +1347,8 @@
* @{
*/
-/** \brief Encoding of key lifetimes. */
+/** Encoding of key lifetimes.
+ */
typedef uint32_t psa_key_lifetime_t;
/** A volatile key slot retains its content as long as the application is
@@ -939,15 +1371,15 @@
* The assignment of lifetimes to slots is implementation-dependent.
*
* \param key Slot to query.
- * \param lifetime On success, the lifetime value.
+ * \param[out] lifetime On success, the lifetime value.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
* The key slot is invalid.
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_get_key_lifetime(psa_key_slot_t key,
psa_key_lifetime_t *lifetime);
@@ -961,20 +1393,20 @@
* \param key Slot whose lifetime is to be changed.
* \param lifetime The lifetime value to set for the given key slot.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
* The key slot is invalid,
* or the lifetime value is invalid.
- * \retval PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_NOT_SUPPORTED
* The implementation does not support the specified lifetime value,
* at least for the specified key slot.
- * \retval PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_OCCUPIED_SLOT
* The slot contains a key, and the implementation does not support
* changing the lifetime of an occupied slot.
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_set_key_lifetime(psa_key_slot_t key,
psa_key_lifetime_t lifetime);
@@ -985,21 +1417,20 @@
* @{
*/
-/** \brief The type of the state data structure for multipart hash operations.
+/** The type of the state data structure for multipart hash operations.
*
- * This is an implementation-defined type. Applications should not
- * make any assumptions about this type except
- * as directed by the documentation of a specific implementation.
- */
-typedef uint32_t psa_hash_operation_t;
+ * This is an implementation-defined \c struct. Applications should not
+ * make any assumptions about the content of this structure except
+ * as directed by the documentation of a specific implementation. */
+typedef struct psa_hash_operation_s psa_hash_operation_t;
/** The size of the output of psa_hash_finish(), in bytes.
*
* This is also the hash size that psa_hash_verify() expects.
*
* \param alg A hash algorithm (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_HASH(alg) is true), or an HMAC algorithm
- * (`PSA_ALG_HMAC(hash_alg)` where `hash_alg` is a
+ * #PSA_ALG_IS_HASH(\p alg) is true), or an HMAC algorithm
+ * (#PSA_ALG_HMAC(\c hash_alg) where \c hash_alg is a
* hash algorithm).
*
* \return The hash size for the specified hash algorithm.
@@ -1007,23 +1438,23 @@
* An implementation may return either 0 or the correct size
* for a hash algorithm that it recognizes, but does not support.
*/
-#define PSA_HASH_SIZE(alg) \
- ( \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_MD2 ? 16 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_MD4 ? 16 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_MD5 ? 16 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \
- PSA_ALG_RSA_GET_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \
+#define PSA_HASH_SIZE(alg) \
+ ( \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_MD2 ? 16 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_MD4 ? 16 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_MD5 ? 16 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \
+ PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \
0)
/** Start a multipart hash operation.
@@ -1032,7 +1463,7 @@
* is as follows:
* -# Allocate an operation object which will be passed to all the functions
* listed here.
- * -# Call psa_hash_start() to specify the algorithm.
+ * -# Call psa_hash_setup() to specify the algorithm.
* -# Call psa_hash_update() zero, one or more times, passing a fragment
* of the message each time. The hash that is calculated is the hash
* of the concatenation of these messages in order.
@@ -1040,48 +1471,48 @@
* To compare the hash with an expected value, call psa_hash_verify().
*
* The application may call psa_hash_abort() at any time after the operation
- * has been initialized with psa_hash_start().
+ * has been initialized with psa_hash_setup().
*
- * After a successful call to psa_hash_start(), the application must
+ * After a successful call to psa_hash_setup(), the application must
* eventually terminate the operation. The following events terminate an
* operation:
* - A failed call to psa_hash_update().
* - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
*
- * \param operation The operation object to use.
- * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
- * such that #PSA_ALG_IS_HASH(alg) is true).
+ * \param[out] operation The operation object to use.
+ * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
+ * such that #PSA_ALG_IS_HASH(\p alg) is true).
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \c alg is not supported or is not a hash algorithm.
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \p alg is not supported or is not a hash algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
-psa_status_t psa_hash_start(psa_hash_operation_t *operation,
+psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
psa_algorithm_t alg);
/** Add a message fragment to a multipart hash operation.
*
- * The application must call psa_hash_start() before calling this function.
+ * The application must call psa_hash_setup() before calling this function.
*
* If this function returns an error status, the operation becomes inactive.
*
- * \param operation Active hash operation.
- * \param input Buffer containing the message fragment to hash.
- * \param input_length Size of the \c input buffer in bytes.
+ * \param[in,out] operation Active hash operation.
+ * \param[in] input Buffer containing the message fragment to hash.
+ * \param input_length Size of the \p input buffer in bytes.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_BAD_STATE
+ * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_hash_update(psa_hash_operation_t *operation,
const uint8_t *input,
@@ -1089,7 +1520,7 @@
/** Finish the calculation of the hash of a message.
*
- * The application must call psa_hash_start() before calling this function.
+ * The application must call psa_hash_setup() before calling this function.
* This function calculates the hash of the message formed by concatenating
* the inputs passed to preceding calls to psa_hash_update().
*
@@ -1103,26 +1534,26 @@
* about the hashed data which could allow an attacker to guess
* a valid hash and thereby bypass security controls.
*
- * \param operation Active hash operation.
- * \param hash Buffer where the hash is to be written.
- * \param hash_size Size of the \c hash buffer in bytes.
- * \param hash_length On success, the number of bytes
- * that make up the hash value. This is always
- * #PSA_HASH_SIZE(alg) where \c alg is the
- * hash algorithm that is calculated.
+ * \param[in,out] operation Active hash operation.
+ * \param[out] hash Buffer where the hash is to be written.
+ * \param hash_size Size of the \p hash buffer in bytes.
+ * \param[out] hash_length On success, the number of bytes
+ * that make up the hash value. This is always
+ * #PSA_HASH_SIZE(\c alg) where \c alg is the
+ * hash algorithm that is calculated.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_BAD_STATE
+ * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
- * \retval PSA_ERROR_BUFFER_TOO_SMALL
- * The size of the \c hash buffer is too small. You can determine a
- * sufficient buffer size by calling #PSA_HASH_SIZE(alg)
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p hash buffer is too small. You can determine a
+ * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
* where \c alg is the hash algorithm that is calculated.
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
uint8_t *hash,
@@ -1132,7 +1563,7 @@
/** Finish the calculation of the hash of a message and compare it with
* an expected value.
*
- * The application must call psa_hash_start() before calling this function.
+ * The application must call psa_hash_setup() before calling this function.
* This function calculates the hash of the message formed by concatenating
* the inputs passed to preceding calls to psa_hash_update(). It then
* compares the calculated hash with the expected hash passed as a
@@ -1144,21 +1575,21 @@
* comparison between the actual hash and the expected hash is performed
* in constant time.
*
- * \param operation Active hash operation.
- * \param hash Buffer containing the expected hash value.
- * \param hash_length Size of the \c hash buffer in bytes.
+ * \param[in,out] operation Active hash operation.
+ * \param[in] hash Buffer containing the expected hash value.
+ * \param hash_length Size of the \p hash buffer in bytes.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The expected hash is identical to the actual hash of the message.
- * \retval PSA_ERROR_INVALID_SIGNATURE
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
* The hash of the message was calculated successfully, but it
* differs from the expected hash.
- * \retval PSA_ERROR_BAD_STATE
+ * \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (not started, or already completed).
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
const uint8_t *hash,
@@ -1166,24 +1597,30 @@
/** Abort a hash operation.
*
- * This function may be called at any time after psa_hash_start().
* Aborting an operation frees all associated resources except for the
- * \c operation structure itself.
+ * \p operation structure itself. Once aborted, the operation object
+ * can be reused for another operation by calling
+ * psa_hash_setup() again.
*
- * Implementation should strive to be robust and handle inactive hash
- * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However,
- * application writers should beware that uninitialized memory may happen
- * to be indistinguishable from an active hash operation, and the behavior
- * of psa_hash_abort() is undefined in this case.
+ * You may call this function any time after the operation object has
+ * been initialized by any of the following methods:
+ * - A call to psa_hash_setup(), whether it succeeds or not.
+ * - Initializing the \c struct to all-bits-zero.
+ * - Initializing the \c struct to logical zeros, e.g.
+ * `psa_hash_operation_t operation = {0}`.
*
- * \param operation Active hash operation.
+ * In particular, calling psa_hash_abort() after the operation has been
+ * terminated by a call to psa_hash_abort(), psa_hash_finish() or
+ * psa_hash_verify() is safe and has no effect.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_BAD_STATE
- * \c operation is not an active hash operation.
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \param[in,out] operation Initialized hash operation.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_BAD_STATE
+ * \p operation is not an active hash operation.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
@@ -1193,89 +1630,241 @@
* @{
*/
-/** \brief The type of the state data structure for multipart MAC operations.
+/** The type of the state data structure for multipart MAC operations.
*
- * This is an implementation-defined type. Applications should not
- * make any assumptions about this type except
- * as directed by the documentation of a specific implementation.
- */
-typedef uint32_t psa_mac_operation_t;
+ * This is an implementation-defined \c struct. Applications should not
+ * make any assumptions about the content of this structure except
+ * as directed by the documentation of a specific implementation. */
+typedef struct psa_mac_operation_s psa_mac_operation_t;
-/** The size of the output of psa_mac_finish(), in bytes.
+/** Start a multipart MAC calculation operation.
*
- * This is also the MAC size that psa_mac_verify() expects.
+ * This function sets up the calculation of the MAC
+ * (message authentication code) of a byte string.
+ * To verify the MAC of a message against an
+ * expected value, use psa_mac_verify_setup() instead.
*
- * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_MAC(alg) is true).
- *
- * \return The MAC size for the specified algorithm.
- * If the MAC algorithm is not recognized, return 0.
- * An implementation may return either 0 or the correct size
- * for a MAC algorithm that it recognizes, but does not support.
- */
-#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
- (PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_HASH(alg)) : \
- PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
- 0)
-
-/** Start a multipart MAC operation.
- *
- * The sequence of operations to calculate a MAC (message authentication code)
- * is as follows:
+ * The sequence of operations to calculate a MAC is as follows:
* -# Allocate an operation object which will be passed to all the functions
* listed here.
- * -# Call psa_mac_start() to specify the algorithm and key.
+ * -# Call psa_mac_sign_setup() to specify the algorithm and key.
* The key remains associated with the operation even if the content
* of the key slot changes.
* -# Call psa_mac_update() zero, one or more times, passing a fragment
* of the message each time. The MAC that is calculated is the MAC
* of the concatenation of these messages in order.
- * -# To calculate the MAC, call psa_mac_finish().
- * To compare the MAC with an expected value, call psa_mac_verify().
+ * -# At the end of the message, call psa_mac_sign_finish() to finish
+ * calculating the MAC value and retrieve it.
*
* The application may call psa_mac_abort() at any time after the operation
- * has been initialized with psa_mac_start().
+ * has been initialized with psa_mac_sign_setup().
*
- * After a successful call to psa_mac_start(), the application must
- * eventually terminate the operation. The following events terminate an
- * operation:
+ * After a successful call to psa_mac_sign_setup(), the application must
+ * eventually terminate the operation through one of the following methods:
* - A failed call to psa_mac_update().
- * - A call to psa_mac_finish(), psa_mac_verify() or psa_mac_abort().
+ * - A call to psa_mac_sign_finish() or psa_mac_abort().
*
- * \param operation The operation object to use.
- * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
- * such that #PSA_ALG_IS_MAC(alg) is true).
+ * \param[out] operation The operation object to use.
+ * \param key Slot containing the key to use for the operation.
+ * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
+ * such that #PSA_ALG_IS_MAC(alg) is true).
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_EMPTY_SLOT
- * \retval PSA_ERROR_NOT_PERMITTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \c key is not compatible with \c alg.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \c alg is not supported or is not a MAC algorithm.
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p key is not compatible with \p alg.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \p alg is not supported or is not a MAC algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
-psa_status_t psa_mac_start(psa_mac_operation_t *operation,
- psa_key_slot_t key,
- psa_algorithm_t alg);
+psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
+ psa_key_slot_t key,
+ psa_algorithm_t alg);
+/** Start a multipart MAC verification operation.
+ *
+ * This function sets up the verification of the MAC
+ * (message authentication code) of a byte string against an expected value.
+ *
+ * The sequence of operations to verify a MAC is as follows:
+ * -# Allocate an operation object which will be passed to all the functions
+ * listed here.
+ * -# Call psa_mac_verify_setup() to specify the algorithm and key.
+ * The key remains associated with the operation even if the content
+ * of the key slot changes.
+ * -# Call psa_mac_update() zero, one or more times, passing a fragment
+ * of the message each time. The MAC that is calculated is the MAC
+ * of the concatenation of these messages in order.
+ * -# At the end of the message, call psa_mac_verify_finish() to finish
+ * calculating the actual MAC of the message and verify it against
+ * the expected value.
+ *
+ * The application may call psa_mac_abort() at any time after the operation
+ * has been initialized with psa_mac_verify_setup().
+ *
+ * After a successful call to psa_mac_verify_setup(), the application must
+ * eventually terminate the operation through one of the following methods:
+ * - A failed call to psa_mac_update().
+ * - A call to psa_mac_verify_finish() or psa_mac_abort().
+ *
+ * \param[out] operation The operation object to use.
+ * \param key Slot containing the key to use for the operation.
+ * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
+ * such that #PSA_ALG_IS_MAC(\p alg) is true).
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \c key is not compatible with \c alg.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \c alg is not supported or is not a MAC algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
+ psa_key_slot_t key,
+ psa_algorithm_t alg);
+
+/** Add a message fragment to a multipart MAC operation.
+ *
+ * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
+ * before calling this function.
+ *
+ * If this function returns an error status, the operation becomes inactive.
+ *
+ * \param[in,out] operation Active MAC operation.
+ * \param[in] input Buffer containing the message fragment to add to
+ * the MAC calculation.
+ * \param input_length Size of the \p input buffer in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (not started, or already completed).
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
psa_status_t psa_mac_update(psa_mac_operation_t *operation,
const uint8_t *input,
size_t input_length);
-psa_status_t psa_mac_finish(psa_mac_operation_t *operation,
- uint8_t *mac,
- size_t mac_size,
- size_t *mac_length);
+/** Finish the calculation of the MAC of a message.
+ *
+ * The application must call psa_mac_sign_setup() before calling this function.
+ * This function calculates the MAC of the message formed by concatenating
+ * the inputs passed to preceding calls to psa_mac_update().
+ *
+ * When this function returns, the operation becomes inactive.
+ *
+ * \warning Applications should not call this function if they expect
+ * a specific value for the MAC. Call psa_mac_verify_finish() instead.
+ * Beware that comparing integrity or authenticity data such as
+ * MAC values with a function such as \c memcmp is risky
+ * because the time taken by the comparison may leak information
+ * about the MAC value which could allow an attacker to guess
+ * a valid MAC and thereby bypass security controls.
+ *
+ * \param[in,out] operation Active MAC operation.
+ * \param[out] mac Buffer where the MAC value is to be written.
+ * \param mac_size Size of the \p mac buffer in bytes.
+ * \param[out] mac_length On success, the number of bytes
+ * that make up the MAC value. This is always
+ * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
+ * where \c key_type and \c key_bits are the type and
+ * bit-size respectively of the key and \c alg is the
+ * MAC algorithm that is calculated.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (not started, or already completed).
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p mac buffer is too small. You can determine a
+ * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
+ uint8_t *mac,
+ size_t mac_size,
+ size_t *mac_length);
-psa_status_t psa_mac_verify(psa_mac_operation_t *operation,
- const uint8_t *mac,
- size_t mac_length);
+/** Finish the calculation of the MAC of a message and compare it with
+ * an expected value.
+ *
+ * The application must call psa_mac_verify_setup() before calling this function.
+ * This function calculates the MAC of the message formed by concatenating
+ * the inputs passed to preceding calls to psa_mac_update(). It then
+ * compares the calculated MAC with the expected MAC passed as a
+ * parameter to this function.
+ *
+ * When this function returns, the operation becomes inactive.
+ *
+ * \note Implementations shall make the best effort to ensure that the
+ * comparison between the actual MAC and the expected MAC is performed
+ * in constant time.
+ *
+ * \param[in,out] operation Active MAC operation.
+ * \param[in] mac Buffer containing the expected MAC value.
+ * \param mac_length Size of the \p mac buffer in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * The expected MAC is identical to the actual MAC of the message.
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
+ * The MAC of the message was calculated successfully, but it
+ * differs from the expected MAC.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (not started, or already completed).
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
+ const uint8_t *mac,
+ size_t mac_length);
+/** Abort a MAC operation.
+ *
+ * Aborting an operation frees all associated resources except for the
+ * \p operation structure itself. Once aborted, the operation object
+ * can be reused for another operation by calling
+ * psa_mac_sign_setup() or psa_mac_verify_setup() again.
+ *
+ * You may call this function any time after the operation object has
+ * been initialized by any of the following methods:
+ * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
+ * it succeeds or not.
+ * - Initializing the \c struct to all-bits-zero.
+ * - Initializing the \c struct to logical zeros, e.g.
+ * `psa_mac_operation_t operation = {0}`.
+ *
+ * In particular, calling psa_mac_abort() after the operation has been
+ * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
+ * psa_mac_verify_finish() is safe and has no effect.
+ *
+ * \param[in,out] operation Initialized MAC operation.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_BAD_STATE
+ * \p operation is not an active MAC operation.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
/**@}*/
@@ -1284,13 +1873,12 @@
* @{
*/
-/** \brief The type of the state data structure for multipart cipher operations.
+/** The type of the state data structure for multipart cipher operations.
*
- * This is an implementation-defined type. Applications should not
- * make any assumptions about this type except
- * as directed by the documentation of a specific implementation.
- */
-typedef uint32_t psa_cipher_operation_t;
+ * This is an implementation-defined \c struct. Applications should not
+ * make any assumptions about the content of this structure except
+ * as directed by the documentation of a specific implementation. */
+typedef struct psa_cipher_operation_s psa_cipher_operation_t;
/** Set the key for a multipart symmetric encryption operation.
*
@@ -1298,47 +1886,49 @@
* is as follows:
* -# Allocate an operation object which will be passed to all the functions
* listed here.
- * -# Call psa_encrypt_setup() to specify the algorithm and key.
+ * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
* The key remains associated with the operation even if the content
* of the key slot changes.
- * -# Call either psa_encrypt_generate_iv() or psa_encrypt_set_iv() to
+ * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
* generate or set the IV (initialization vector). You should use
- * psa_encrypt_generate_iv() unless the protocol you are implementing
+ * psa_cipher_generate_iv() unless the protocol you are implementing
* requires a specific IV value.
* -# Call psa_cipher_update() zero, one or more times, passing a fragment
* of the message each time.
* -# Call psa_cipher_finish().
*
* The application may call psa_cipher_abort() at any time after the operation
- * has been initialized with psa_encrypt_setup().
+ * has been initialized with psa_cipher_encrypt_setup().
*
- * After a successful call to psa_encrypt_setup(), the application must
+ * After a successful call to psa_cipher_encrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an
* operation:
- * - A failed call to psa_encrypt_generate_iv(), psa_encrypt_set_iv()
+ * - A failed call to psa_cipher_generate_iv(), psa_cipher_set_iv()
* or psa_cipher_update().
* - A call to psa_cipher_finish() or psa_cipher_abort().
*
- * \param operation The operation object to use.
- * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
- * such that #PSA_ALG_IS_CIPHER(alg) is true).
+ * \param[out] operation The operation object to use.
+ * \param key Slot containing the key to use for the operation.
+ * \param alg The cipher algorithm to compute
+ * (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_CIPHER(\p alg) is true).
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_EMPTY_SLOT
- * \retval PSA_ERROR_NOT_PERMITTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \c key is not compatible with \c alg.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \c alg is not supported or is not a cipher algorithm.
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p key is not compatible with \p alg.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \p alg is not supported or is not a cipher algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
-psa_status_t psa_encrypt_setup(psa_cipher_operation_t *operation,
- psa_key_slot_t key,
- psa_algorithm_t alg);
+psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
+ psa_key_slot_t key,
+ psa_algorithm_t alg);
/** Set the key for a multipart symmetric decryption operation.
*
@@ -1346,7 +1936,7 @@
* is as follows:
* -# Allocate an operation object which will be passed to all the functions
* listed here.
- * -# Call psa_decrypt_setup() to specify the algorithm and key.
+ * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
* The key remains associated with the operation even if the content
* of the key slot changes.
* -# Call psa_cipher_update() with the IV (initialization vector) for the
@@ -1358,44 +1948,136 @@
* -# Call psa_cipher_finish().
*
* The application may call psa_cipher_abort() at any time after the operation
- * has been initialized with psa_encrypt_setup().
+ * has been initialized with psa_cipher_decrypt_setup().
*
- * After a successful call to psa_decrypt_setup(), the application must
+ * After a successful call to psa_cipher_decrypt_setup(), the application must
* eventually terminate the operation. The following events terminate an
* operation:
* - A failed call to psa_cipher_update().
* - A call to psa_cipher_finish() or psa_cipher_abort().
*
- * \param operation The operation object to use.
- * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
- * such that #PSA_ALG_IS_CIPHER(alg) is true).
+ * \param[out] operation The operation object to use.
+ * \param key Slot containing the key to use for the operation.
+ * \param alg The cipher algorithm to compute
+ * (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_CIPHER(\p alg) is true).
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_EMPTY_SLOT
- * \retval PSA_ERROR_NOT_PERMITTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \c key is not compatible with \c alg.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \c alg is not supported or is not a cipher algorithm.
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p key is not compatible with \p alg.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \p alg is not supported or is not a cipher algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
-psa_status_t psa_decrypt_setup(psa_cipher_operation_t *operation,
- psa_key_slot_t key,
- psa_algorithm_t alg);
+psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
+ psa_key_slot_t key,
+ psa_algorithm_t alg);
-psa_status_t psa_encrypt_generate_iv(psa_cipher_operation_t *operation,
- unsigned char *iv,
- size_t iv_size,
- size_t *iv_length);
+/** Generate an IV for a symmetric encryption operation.
+ *
+ * This function generates a random IV (initialization vector), nonce
+ * or initial counter value for the encryption operation as appropriate
+ * for the chosen algorithm, key type and key size.
+ *
+ * The application must call psa_cipher_encrypt_setup() before
+ * calling this function.
+ *
+ * If this function returns an error status, the operation becomes inactive.
+ *
+ * \param[in,out] operation Active cipher operation.
+ * \param[out] iv Buffer where the generated IV is to be written.
+ * \param iv_size Size of the \p iv buffer in bytes.
+ * \param[out] iv_length On success, the number of bytes of the
+ * generated IV.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (not started, or IV already set).
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p iv buffer is too small.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
+ unsigned char *iv,
+ size_t iv_size,
+ size_t *iv_length);
-psa_status_t psa_encrypt_set_iv(psa_cipher_operation_t *operation,
- const unsigned char *iv,
- size_t iv_length);
+/** Set the IV for a symmetric encryption or decryption operation.
+ *
+ * This function sets the random IV (initialization vector), nonce
+ * or initial counter value for the encryption or decryption operation.
+ *
+ * The application must call psa_cipher_encrypt_setup() before
+ * calling this function.
+ *
+ * If this function returns an error status, the operation becomes inactive.
+ *
+ * \note When encrypting, applications should use psa_cipher_generate_iv()
+ * instead of this function, unless implementing a protocol that requires
+ * a non-random IV.
+ *
+ * \param[in,out] operation Active cipher operation.
+ * \param[in] iv Buffer containing the IV to use.
+ * \param iv_length Size of the IV in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (not started, or IV already set).
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * The size of \p iv is not acceptable for the chosen algorithm,
+ * or the chosen algorithm does not use an IV.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
+ const unsigned char *iv,
+ size_t iv_length);
+/** Encrypt or decrypt a message fragment in an active cipher operation.
+ *
+ * Before calling this function, you must:
+ * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
+ * The choice of setup function determines whether this function
+ * encrypts or decrypts its input.
+ * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
+ * (recommended when encrypting) or psa_cipher_set_iv().
+ *
+ * If this function returns an error status, the operation becomes inactive.
+ *
+ * \param[in,out] operation Active cipher operation.
+ * \param[in] input Buffer containing the message fragment to
+ * encrypt or decrypt.
+ * \param input_length Size of the \p input buffer in bytes.
+ * \param[out] output Buffer where the output is to be written.
+ * \param output_size Size of the \p output buffer in bytes.
+ * \param[out] output_length On success, the number of bytes
+ * that make up the returned output.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (not started, IV required but
+ * not set, or already completed).
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p output buffer is too small.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
const uint8_t *input,
size_t input_length,
@@ -1403,11 +2085,70 @@
size_t output_size,
size_t *output_length);
+/** Finish encrypting or decrypting a message in a cipher operation.
+ *
+ * The application must call psa_cipher_encrypt_setup() or
+ * psa_cipher_decrypt_setup() before calling this function. The choice
+ * of setup function determines whether this function encrypts or
+ * decrypts its input.
+ *
+ * This function finishes the encryption or decryption of the message
+ * formed by concatenating the inputs passed to preceding calls to
+ * psa_cipher_update().
+ *
+ * When this function returns, the operation becomes inactive.
+ *
+ * \param[in,out] operation Active cipher operation.
+ * \param[out] output Buffer where the output is to be written.
+ * \param output_size Size of the \p output buffer in bytes.
+ * \param[out] output_length On success, the number of bytes
+ * that make up the returned output.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (not started, IV required but
+ * not set, or already completed).
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p output buffer is too small.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
uint8_t *output,
size_t output_size,
size_t *output_length);
+/** Abort a cipher operation.
+ *
+ * Aborting an operation frees all associated resources except for the
+ * \p operation structure itself. Once aborted, the operation object
+ * can be reused for another operation by calling
+ * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
+ *
+ * You may call this function any time after the operation object has
+ * been initialized by any of the following methods:
+ * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
+ * whether it succeeds or not.
+ * - Initializing the \c struct to all-bits-zero.
+ * - Initializing the \c struct to logical zeros, e.g.
+ * `psa_cipher_operation_t operation = {0}`.
+ *
+ * In particular, calling psa_cipher_abort() after the operation has been
+ * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
+ * is safe and has no effect.
+ *
+ * \param[in,out] operation Initialized cipher operation.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_BAD_STATE
+ * \p operation is not an active cipher operation.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
/**@}*/
@@ -1420,7 +2161,7 @@
*
* \param alg An AEAD algorithm
* (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(alg) is true).
+ * #PSA_ALG_IS_AEAD(\p alg) is true).
*
* \return The tag size for the specified algorithm.
* If the AEAD algorithm does not have an identified
@@ -1436,45 +2177,21 @@
(alg) == PSA_ALG_CCM ? 16 : \
0)
-/** The maximum size of the output of psa_aead_encrypt(), in bytes.
- *
- * If the size of the ciphertext buffer is at least this large, it is
- * guaranteed that psa_aead_encrypt() will not fail due to an
- * insufficient buffer size. Depending on the algorithm, the actual size of
- * the ciphertext may be smaller.
- *
- * \param alg An AEAD algorithm
- * (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(alg) is true).
- * \param plaintext_length Size of the plaintext in bytes.
- *
- * \return The AEAD ciphertext size for the specified
- * algorithm.
- * If the AEAD algorithm is not recognized, return 0.
- * An implementation may return either 0 or a
- * correct size for an AEAD algorithm that it
- * recognizes, but does not support.
- */
-#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
- (PSA_AEAD_TAG_SIZE(alg) != 0 ? \
- (plaintext_length) + PSA_AEAD_TAG_SIZE(alg) : \
- 0)
-
/** Process an authenticated encryption operation.
*
* \param key Slot containing the key to use.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(alg) is true).
- * \param nonce Nonce or IV to use.
+ * #PSA_ALG_IS_AEAD(\p alg) is true).
+ * \param[in] nonce Nonce or IV to use.
* \param nonce_length Size of the \p nonce buffer in bytes.
- * \param additional_data Additional data that will be authenticated
+ * \param[in] additional_data Additional data that will be authenticated
* but not encrypted.
* \param additional_data_length Size of \p additional_data in bytes.
- * \param plaintext Data that will be authenticated and
+ * \param[in] plaintext Data that will be authenticated and
* encrypted.
* \param plaintext_length Size of \p plaintext in bytes.
- * \param ciphertext Output buffer for the authenticated and
+ * \param[out] ciphertext Output buffer for the authenticated and
* encrypted data. The additional data is not
* part of this output. For algorithms where the
* encrypted data and the authentication tag
@@ -1485,110 +2202,86 @@
* This must be at least
* #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
* \p plaintext_length).
- * \param ciphertext_length On success, the size of the output
+ * \param[out] ciphertext_length On success, the size of the output
* in the \b ciphertext buffer.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_EMPTY_SLOT
- * \retval PSA_ERROR_NOT_PERMITTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \c key is not compatible with \c alg.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \c alg is not supported or is not an AEAD algorithm.
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p key is not compatible with \p alg.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \p alg is not supported or is not an AEAD algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
-psa_status_t psa_aead_encrypt( psa_key_slot_t key,
- 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 );
-
-/** The maximum size of the output of psa_aead_decrypt(), in bytes.
- *
- * If the size of the plaintext buffer is at least this large, it is
- * guaranteed that psa_aead_decrypt() will not fail due to an
- * insufficient buffer size. Depending on the algorithm, the actual size of
- * the plaintext may be smaller.
- *
- * \param alg An AEAD algorithm
- * (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(alg) is true).
- * \param ciphertext_length Size of the plaintext in bytes.
- *
- * \return The AEAD ciphertext size for the specified
- * algorithm.
- * If the AEAD algorithm is not recognized, return 0.
- * An implementation may return either 0 or a
- * correct size for an AEAD algorithm that it
- * recognizes, but does not support.
- */
-#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
- (PSA_AEAD_TAG_SIZE(alg) != 0 ? \
- (plaintext_length) - PSA_AEAD_TAG_SIZE(alg) : \
- 0)
+psa_status_t psa_aead_encrypt(psa_key_slot_t key,
+ 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.
*
* \param key Slot containing the key to use.
* \param alg The AEAD algorithm to compute
* (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(alg) is true).
- * \param nonce Nonce or IV to use.
+ * #PSA_ALG_IS_AEAD(\p alg) is true).
+ * \param[in] nonce Nonce or IV to use.
* \param nonce_length Size of the \p nonce buffer in bytes.
- * \param additional_data Additional data that has been authenticated
+ * \param[in] additional_data Additional data that has been authenticated
* but not encrypted.
* \param additional_data_length Size of \p additional_data in bytes.
- * \param ciphertext Data that has been authenticated and
+ * \param[in] ciphertext Data that has been authenticated and
* encrypted. For algorithms where the
* encrypted data and the authentication tag
* are defined as separate inputs, the buffer
* must contain the encrypted data followed
* by the authentication tag.
* \param ciphertext_length Size of \p ciphertext in bytes.
- * \param plaintext Output buffer for the decrypted data.
+ * \param[out] plaintext Output buffer for the decrypted data.
* \param plaintext_size Size of the \p plaintext buffer in bytes.
* This must be at least
* #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
* \p ciphertext_length).
- * \param plaintext_length On success, the size of the output
+ * \param[out] plaintext_length On success, the size of the output
* in the \b plaintext buffer.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* Success.
- * \retval PSA_ERROR_EMPTY_SLOT
- * \retval PSA_ERROR_INVALID_SIGNATURE
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
* The ciphertext is not authentic.
- * \retval PSA_ERROR_NOT_PERMITTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \c key is not compatible with \c alg.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \c alg is not supported or is not an AEAD algorithm.
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \p key is not compatible with \p alg.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \p alg is not supported or is not an AEAD algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
-psa_status_t psa_aead_decrypt( psa_key_slot_t key,
- 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 );
+psa_status_t psa_aead_decrypt(psa_key_slot_t key,
+ 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);
/**@}*/
@@ -1597,110 +2290,54 @@
*/
/**
- * \brief Maximum ECDSA signature size for a given curve bit size
+ * \brief ECDSA signature size for a given curve bit size
*
- * \param curve_bits Curve size in bits
- * \return Maximum signature size in bytes
+ * \param curve_bits Curve size in bits.
+ * \return Signature size in bytes.
*
* \note This macro returns a compile-time constant if its argument is one.
- *
- * \warning This macro may evaluate its argument multiple times.
*/
-/*
- * RFC 4492 page 20:
- *
- * Ecdsa-Sig-Value ::= SEQUENCE {
- * r INTEGER,
- * s INTEGER
- * }
- *
- * Size is at most
- * 1 (tag) + 1 (len) + 1 (initial 0) + curve_bytes for each of r and s,
- * twice that + 1 (tag) + 2 (len) for the sequence
- * (assuming curve_bytes is less than 126 for r and s,
- * and less than 124 (total len <= 255) for the sequence)
- */
-#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
- ( /*T,L of SEQUENCE*/ ((curve_bits) >= 61 * 8 ? 3 : 2) + \
- /*T,L of r,s*/ 2 * (((curve_bits) >= 127 * 8 ? 3 : 2) + \
- /*V of r,s*/ ((curve_bits) + 8) / 8))
-
-
-/** Safe signature buffer size for psa_asymmetric_sign().
- *
- * This macro returns a safe buffer size for a signature using a key
- * of the specified type and size, with the specified algorithm.
- * Note that the actual size of the signature may be smaller
- * (some algorithms produce a variable-size signature).
- *
- * \warning This function may call its arguments multiple times or
- * zero times, so you should not pass arguments that contain
- * side effects.
- *
- * \param key_type An asymmetric key type (this may indifferently be a
- * key pair type or a public key type).
- * \param key_bits The size of the key in bits.
- * \param alg The signature algorithm.
- *
- * \return If the parameters are valid and supported, return
- * a buffer size in bytes that guarantees that
- * psa_asymmetric_sign() will not fail with
- * #PSA_ERROR_BUFFER_TOO_SMALL.
- * If the parameters are a valid combination that is not supported
- * by the implementation, this macro either shall return either a
- * sensible size or 0.
- * If the parameters are not valid, the
- * return value is unspecified.
- *
- */
-#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
- (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
- PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
- ((void)alg, 0))
+#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
+ (PSA_BITS_TO_BYTES(curve_bits) * 2)
/**
* \brief Sign a hash or short message with a private key.
*
- * \param key Key slot containing an asymmetric key pair.
- * \param alg A signature algorithm that is compatible with
- * the type of \c key.
- * \param hash The message to sign.
- * \param hash_length Size of the \c hash buffer in bytes.
- * \param salt A salt or label, if supported by the signature
- * algorithm.
- * If the signature algorithm does not support a
- * salt, pass \c NULL.
- * If the signature algorithm supports an optional
- * salt and you do not want to pass a salt,
- * pass \c NULL.
- * \param salt_length Size of the \c salt buffer in bytes.
- * If \c salt is \c NULL, pass 0.
- * \param signature Buffer where the signature is to be written.
- * \param signature_size Size of the \c signature buffer in bytes.
- * \param signature_length On success, the number of bytes
- * that make up the returned signature value.
+ * Note that to perform a hash-and-sign signature algorithm, you must
+ * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
+ * and psa_hash_finish(). Then pass the resulting hash as the \p hash
+ * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
+ * to determine the hash algorithm to use.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_BUFFER_TOO_SMALL
- * The size of the \c signature buffer is too small. You can
+ * \param key Key slot containing an asymmetric key pair.
+ * \param alg A signature algorithm that is compatible with
+ * the type of \p key.
+ * \param[in] hash The hash or message to sign.
+ * \param hash_length Size of the \p hash buffer in bytes.
+ * \param[out] signature Buffer where the signature is to be written.
+ * \param signature_size Size of the \p signature buffer in bytes.
+ * \param[out] signature_length On success, the number of bytes
+ * that make up the returned signature value.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p signature buffer is too small. You can
* determine a sufficient buffer size by calling
- * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)
+ * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
- * respectively of \c key.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
- * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
+ * respectively of \p key.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
*/
psa_status_t psa_asymmetric_sign(psa_key_slot_t key,
psa_algorithm_t alg,
const uint8_t *hash,
size_t hash_length,
- const uint8_t *salt,
- size_t salt_length,
uint8_t *signature,
size_t signature_size,
size_t *signature_length);
@@ -1708,98 +2345,87 @@
/**
* \brief Verify the signature a hash or short message using a public key.
*
+ * Note that to perform a hash-and-sign signature algorithm, you must
+ * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
+ * and psa_hash_finish(). Then pass the resulting hash as the \p hash
+ * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
+ * to determine the hash algorithm to use.
+ *
* \param key Key slot containing a public key or an
* asymmetric key pair.
* \param alg A signature algorithm that is compatible with
- * the type of \c key.
- * \param hash The message whose signature is to be verified.
- * \param hash_length Size of the \c hash buffer in bytes.
- * \param salt A salt or label, if supported by the signature
- * algorithm.
- * If the signature algorithm does not support a
- * salt, pass \c NULL.
- * If the signature algorithm supports an optional
- * salt and you do not want to pass a salt,
- * pass \c NULL.
- * \param salt_length Size of the \c salt buffer in bytes.
- * If \c salt is \c NULL, pass 0.
- * \param signature Buffer containing the signature to verify.
- * \param signature_size Size of the \c signature buffer in bytes.
+ * the type of \p key.
+ * \param[in] hash The hash or message whose signature is to be
+ * verified.
+ * \param hash_length Size of the \p hash buffer in bytes.
+ * \param[in] signature Buffer containing the signature to verify.
+ * \param signature_length Size of the \p signature buffer in bytes.
*
- * \retval PSA_SUCCESS
+ * \retval #PSA_SUCCESS
* The signature is valid.
- * \retval PSA_ERROR_INVALID_SIGNATURE
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
* The calculation was perfomed successfully, but the passed
* signature is not a valid signature.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_asymmetric_verify(psa_key_slot_t key,
psa_algorithm_t alg,
const uint8_t *hash,
size_t hash_length,
- const uint8_t *salt,
- size_t salt_length,
- uint8_t *signature,
- size_t signature_size);
+ const uint8_t *signature,
+ size_t signature_length);
-#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
- (PSA_KEY_TYPE_IS_RSA(key_type) ? \
- ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
- 0)
#define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
- (PSA_ALG_IS_RSA_OAEP_MGF1(alg) ? \
- 2 * PSA_HASH_FINAL_SIZE(PSA_ALG_RSA_GET_HASH(alg)) + 1 : \
+ (PSA_ALG_IS_RSA_OAEP(alg) ? \
+ 2 * PSA_HASH_FINAL_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
11 /*PKCS#1v1.5*/)
-#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
- (PSA_KEY_TYPE_IS_RSA(key_type) ? \
- PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
- 0)
/**
* \brief Encrypt a short message with a public key.
*
- * \param key Key slot containing a public key or an asymmetric
- * key pair.
- * \param alg An asymmetric encryption algorithm that is
- * compatible with the type of \c key.
- * \param input The message to encrypt.
- * \param input_length Size of the \c input buffer in bytes.
- * \param salt A salt or label, if supported by the encryption
- * algorithm.
- * If the algorithm does not support a
- * salt, pass \c NULL.
- * If the algorithm supports an optional
- * salt and you do not want to pass a salt,
- * pass \c NULL.
+ * \param key Key slot containing a public key or an
+ * asymmetric key pair.
+ * \param alg An asymmetric encryption algorithm that is
+ * compatible with the type of \p key.
+ * \param[in] input The message to encrypt.
+ * \param input_length Size of the \p input buffer in bytes.
+ * \param[in] salt A salt or label, if supported by the
+ * encryption algorithm.
+ * If the algorithm does not support a
+ * salt, pass \c NULL.
+ * If the algorithm supports an optional
+ * salt and you do not want to pass a salt,
+ * pass \c NULL.
*
- * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
- * supported.
- * \param salt_length Size of the \c salt buffer in bytes.
- * If \c salt is \c NULL, pass 0.
- * \param output Buffer where the encrypted message is to be written.
- * \param output_size Size of the \c output buffer in bytes.
- * \param output_length On success, the number of bytes
- * that make up the returned output.
+ * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
+ * supported.
+ * \param salt_length Size of the \p salt buffer in bytes.
+ * If \p salt is \c NULL, pass 0.
+ * \param[out] output Buffer where the encrypted message is to
+ * be written.
+ * \param output_size Size of the \p output buffer in bytes.
+ * \param[out] output_length On success, the number of bytes
+ * that make up the returned output.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_BUFFER_TOO_SMALL
- * The size of the \c output buffer is too small. You can
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p output buffer is too small. You can
* determine a sufficient buffer size by calling
- * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg)
+ * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
- * respectively of \c key.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
- * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
+ * respectively of \p key.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
*/
psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key,
psa_algorithm_t alg,
@@ -1814,43 +2440,44 @@
/**
* \brief Decrypt a short message with a private key.
*
- * \param key Key slot containing an asymmetric key pair.
- * \param alg An asymmetric encryption algorithm that is
- * compatible with the type of \c key.
- * \param input The message to decrypt.
- * \param input_length Size of the \c input buffer in bytes.
- * \param salt A salt or label, if supported by the encryption
- * algorithm.
- * If the algorithm does not support a
- * salt, pass \c NULL.
- * If the algorithm supports an optional
- * salt and you do not want to pass a salt,
- * pass \c NULL.
+ * \param key Key slot containing an asymmetric key pair.
+ * \param alg An asymmetric encryption algorithm that is
+ * compatible with the type of \p key.
+ * \param[in] input The message to decrypt.
+ * \param input_length Size of the \p input buffer in bytes.
+ * \param[in] salt A salt or label, if supported by the
+ * encryption algorithm.
+ * If the algorithm does not support a
+ * salt, pass \c NULL.
+ * If the algorithm supports an optional
+ * salt and you do not want to pass a salt,
+ * pass \c NULL.
*
- * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
- * supported.
- * \param salt_length Size of the \c salt buffer in bytes.
- * If \c salt is \c NULL, pass 0.
- * \param output Buffer where the decrypted message is to be written.
- * \param output_size Size of the \c output buffer in bytes.
- * \param output_length On success, the number of bytes
- * that make up the returned output.
+ * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
+ * supported.
+ * \param salt_length Size of the \p salt buffer in bytes.
+ * If \p salt is \c NULL, pass 0.
+ * \param[out] output Buffer where the decrypted message is to
+ * be written.
+ * \param output_size Size of the \c output buffer in bytes.
+ * \param[out] output_length On success, the number of bytes
+ * that make up the returned output.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_BUFFER_TOO_SMALL
- * The size of the \c output buffer is too small. You can
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p output buffer is too small. You can
* determine a sufficient buffer size by calling
- * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg)
+ * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
* where \c key_type and \c key_bits are the type and bit-size
- * respectively of \c key.
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
- * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
- * \retval PSA_ERROR_INVALID_PADDING
+ * respectively of \p key.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval #PSA_ERROR_INVALID_PADDING
*/
psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key,
psa_algorithm_t alg,
@@ -1864,7 +2491,229 @@
/**@}*/
-/** \defgroup generation Key generation
+/** \defgroup generators Generators
+ * @{
+ */
+
+/** The type of the state data structure for generators.
+ *
+ * Before calling any function on a generator, the application must
+ * initialize it by any of the following means:
+ * - Set the structure to all-bits-zero, for example:
+ * \code
+ * psa_crypto_generator_t generator;
+ * memset(&generator, 0, sizeof(generator));
+ * \endcode
+ * - Initialize the structure to logical zero values, for example:
+ * \code
+ * psa_crypto_generator_t generator = {0};
+ * \endcode
+ * - Initialize the structure to the initializer #PSA_CRYPTO_GENERATOR_INIT,
+ * for example:
+ * \code
+ * psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
+ * \endcode
+ * - Assign the result of the function psa_crypto_generator_init()
+ * to the structure, for example:
+ * \code
+ * psa_crypto_generator_t generator;
+ * generator = psa_crypto_generator_init();
+ * \endcode
+ *
+ * This is an implementation-defined \c struct. Applications should not
+ * make any assumptions about the content of this structure except
+ * as directed by the documentation of a specific implementation.
+ */
+typedef struct psa_crypto_generator_s psa_crypto_generator_t;
+
+/** \def PSA_CRYPTO_GENERATOR_INIT
+ *
+ * This macro returns a suitable initializer for a generator object
+ * of type #psa_crypto_generator_t.
+ */
+#ifdef __DOXYGEN_ONLY__
+/* This is an example definition for documentation purposes.
+ * Implementations should define a suitable value in `crypto_struct.h`.
+ */
+#define PSA_CRYPTO_GENERATOR_INIT {0}
+#endif
+
+/** Return an initial value for a generator object.
+ */
+psa_crypto_generator_t psa_crypto_generator_init(void);
+
+/** Retrieve the current capacity of a generator.
+ *
+ * The capacity of a generator is the maximum number of bytes that it can
+ * return. Reading *N* bytes from a generator reduces its capacity by *N*.
+ *
+ * \param[in] generator The generator to query.
+ * \param[out] capacity On success, the capacity of the generator.
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_BAD_STATE
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ */
+psa_status_t psa_get_generator_capacity(const psa_crypto_generator_t *generator,
+ size_t *capacity);
+
+/** Read some data from a generator.
+ *
+ * This function reads and returns a sequence of bytes from a generator.
+ * The data that is read is discarded from the generator. The generator's
+ * capacity is decreased by the number of bytes read.
+ *
+ * \param[in,out] generator The generator object to read from.
+ * \param[out] output Buffer where the generator output will be
+ * written.
+ * \param output_length Number of bytes to output.
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_INSUFFICIENT_CAPACITY
+ * There were fewer than \p output_length bytes
+ * in the generator. 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 this function will not
+ * succeed, even with a smaller output buffer.
+ * \retval PSA_ERROR_BAD_STATE
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_generator_read(psa_crypto_generator_t *generator,
+ uint8_t *output,
+ size_t output_length);
+
+/** Create a symmetric key from data read from a generator.
+ *
+ * This function reads a sequence of bytes from a generator and imports
+ * these bytes as a key.
+ * The data that is read is discarded from the generator. The generator's
+ * capacity is decreased by the number of bytes read.
+ *
+ * This function is equivalent to calling #psa_generator_read and
+ * passing the resulting output to #psa_import_key, but
+ * if the implementation provides an isolation boundary then
+ * the key material is not exposed outside the isolation boundary.
+ *
+ * \param key 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 type Key type (a \c PSA_KEY_TYPE_XXX value).
+ * This must be a symmetric key type.
+ * \param bits Key size in bits.
+ * \param[in,out] generator The generator object to read from.
+ *
+ * \retval PSA_SUCCESS
+ * Success.
+ * \retval PSA_ERROR_INSUFFICIENT_CAPACITY
+ * There were fewer than \p output_length bytes
+ * in the generator. 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 this function will not
+ * succeed, even with a smaller output buffer.
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ * The key type or key size is not supported, either by the
+ * implementation in general or in this particular slot.
+ * \retval PSA_ERROR_BAD_STATE
+ * \retval PSA_ERROR_INVALID_ARGUMENT
+ * The key slot is invalid.
+ * \retval PSA_ERROR_OCCUPIED_SLOT
+ * There is already a key in the specified slot.
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_generator_import_key(psa_key_slot_t key,
+ psa_key_type_t type,
+ size_t bits,
+ psa_crypto_generator_t *generator);
+
+/** Abort a generator.
+ *
+ * Once a generator has been aborted, its capacity is zero.
+ * Aborting a generator frees all associated resources except for the
+ * \c generator structure itself.
+ *
+ * This function may be called at any time as long as the generator
+ * object has been initialized to #PSA_CRYPTO_GENERATOR_INIT, to
+ * psa_crypto_generator_init() or a zero value. In particular, it is valid
+ * to call psa_generator_abort() twice, or to call psa_generator_abort()
+ * on a generator that has not been set up.
+ *
+ * Once aborted, the generator object may be called.
+ *
+ * \param[in,out] generator The generator to abort.
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_BAD_STATE
+ * \retval PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_HARDWARE_FAILURE
+ * \retval PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_generator_abort(psa_crypto_generator_t *generator);
+
+/**@}*/
+
+/** \defgroup derivation Key derivation
+ * @{
+ */
+
+/** Set up a key derivation operation.
+ *
+ * A key derivation algorithm takes three inputs: a secret input \p key and
+ * two non-secret inputs \p label and p salt.
+ * The result of this function is a byte generator which can
+ * be used to produce keys and other cryptographic material.
+ *
+ * The role of \p label and \p salt is as follows:
+ * - For HKDF (#PSA_ALG_HKDF), \p salt is the salt used in the "extract" step
+ * and \p label is the info string used in the "expand" step.
+ *
+ * \param[in,out] generator The generator object to set up. It must
+ * have been initialized to .
+ * \param key Slot containing the secret key to use.
+ * \param alg The key derivation algorithm to compute
+ * (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
+ * \param[in] salt Salt to use.
+ * \param salt_length Size of the \p salt buffer in bytes.
+ * \param[in] label Label to use.
+ * \param label_length Size of the \p label buffer in bytes.
+ * \param capacity The maximum number of bytes that the
+ * generator will be able to provide.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \c key is not compatible with \c alg,
+ * or \p capacity is too large for the specified algorithm and key.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \c alg is not supported or is not a key derivation algorithm.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
+ */
+psa_status_t psa_key_derivation(psa_crypto_generator_t *generator,
+ psa_key_slot_t key,
+ psa_algorithm_t alg,
+ const uint8_t *salt,
+ size_t salt_length,
+ const uint8_t *label,
+ size_t label_length,
+ size_t capacity);
+
+/**@}*/
+
+/** \defgroup random Random generation
* @{
*/
@@ -1877,19 +2726,28 @@
*
* \note To generate a key, use psa_generate_key() instead.
*
- * \param output Output buffer for the generated data.
+ * \param[out] output Output buffer for the generated data.
* \param output_size Number of bytes to generate and output.
*
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_generate_random(uint8_t *output,
size_t output_size);
+/** Extra parameters for RSA key generation.
+ *
+ * You may pass a pointer to a structure of this type as the \c extra
+ * parameter to psa_generate_key().
+ */
+typedef struct {
+ uint32_t e; /**< Public exponent value. Default: 65537. */
+} psa_generate_key_extra_rsa;
+
/**
* \brief Generate a key or key pair.
*
@@ -1898,38 +2756,45 @@
* be unoccupied.
* \param type Key type (a \c PSA_KEY_TYPE_XXX value).
* \param bits Key size in bits.
- * \param parameters Extra parameters for key generation. The
+ * \param[in] extra Extra parameters for key generation. The
* interpretation of this parameter depends on
- * \c type. All types support \c NULL to use
- * the default parameters specified below.
- * \param parameters_size Size of the buffer that \p parameters
- * points to, in bytes.
+ * \p type. All types support \c NULL to use
+ * default parameters. Implementation that support
+ * the generation of vendor-specific key types
+ * that allow extra parameters shall document
+ * the format of these extra parameters and
+ * the default values. For standard parameters,
+ * the meaning of \p extra is as follows:
+ * - For a symmetric key type (a type such
+ * that #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is
+ * false), \p extra must be \c NULL.
+ * - For an elliptic curve key type (a type
+ * such that #PSA_KEY_TYPE_IS_ECC(\p type) is
+ * false), \p extra must be \c NULL.
+ * - For an RSA key (\p type is
+ * #PSA_KEY_TYPE_RSA_KEYPAIR), \p extra is an
+ * optional #psa_generate_key_extra_rsa structure
+ * specifying the public exponent. The
+ * default public exponent used when \p extra
+ * is \c NULL is 65537.
+ * \param extra_size Size of the buffer that \p extra
+ * points to, in bytes. Note that if \p extra is
+ * \c NULL then \p extra_size must be zero.
*
- * For any symmetric key type (type such that
- * `PSA_KEY_TYPE_IS_ASYMMETRIC(type)` is false), \c parameters must be
- * \c NULL. For asymmetric key types defined by this specification,
- * the parameter type and the default parameters are defined by the
- * table below. For vendor-defined key types, the vendor documentation
- * shall define the parameter type and the default parameters.
- *
- * Type | Parameter type | Meaning | Parameters used if `parameters == NULL`
- * ---- | -------------- | ------- | ---------------------------------------
- * `PSA_KEY_TYPE_RSA_KEYPAIR` | `unsigned int` | Public exponent | 65537
- *
- * \retval PSA_SUCCESS
- * \retval PSA_ERROR_NOT_SUPPORTED
- * \retval PSA_ERROR_INVALID_ARGUMENT
- * \retval PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
- * \retval PSA_ERROR_COMMUNICATION_FAILURE
- * \retval PSA_ERROR_HARDWARE_FAILURE
- * \retval PSA_ERROR_TAMPERING_DETECTED
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_TAMPERING_DETECTED
*/
psa_status_t psa_generate_key(psa_key_slot_t key,
psa_key_type_t type,
size_t bits,
- const void *parameters,
- size_t parameters_size);
+ const void *extra,
+ size_t extra_size);
/**@}*/
@@ -1937,9 +2802,16 @@
}
#endif
-/* The file "psa_crypto_extra.h" contains vendor-specific definitions. This
- * can include vendor-defined algorithms, extra functions, etc.
- */
+/* The file "crypto_sizes.h" contains definitions for size calculation
+ * macros whose definitions are implementation-specific. */
+#include "psa_crypto_sizes.h"
+
+/* The file "crypto_struct.h" contains definitions for
+ * implementation-specific structs that are declared above. */
+#include "psa_crypto_struct.h"
+
+/* The file "crypto_extra.h" contains vendor-specific definitions. This
+ * can include vendor-defined algorithms, extra functions, etc. */
#include "psa_crypto_extra.h"
#endif /* PSA_CRYPTO_H */
diff --git a/interface/include/psa_crypto_extra.h b/interface/include/psa_crypto_extra.h
index d8fabf7..1608410 100644
--- a/interface/include/psa_crypto_extra.h
+++ b/interface/include/psa_crypto_extra.h
@@ -1,40 +1,35 @@
/*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
-
/**
* \file psa_crypto_extra.h
*
* \brief PSA cryptography module: vendor extensions
+ *
+ * \note This file may not be included directly. Applications must
+ * include psa_crypto.h.
+ *
+ * This file is reserved for vendor-specific definitions.
*/
-#ifndef __PSA_CRYPTO_EXTRA_H__
-#define __PSA_CRYPTO_EXTRA_H__
+/**
+ *\note This implementation currently doesn't provide support to any
+ * vendor-specific extension or definition, so this header file
+ * is empty.
+ */
+
+#ifndef PSA_CRYPTO_EXTRA_H
+#define PSA_CRYPTO_EXTRA_H
#ifdef __cplusplus
extern "C" {
#endif
-/**
- * \note This file is meant to be included by psa_crypto.h only
- *
- */
-
-/**
- * \brief Library deinitialization.
- *
- * This function clears all data associated with the PSA layer,
- * including the whole key store.
- *
- * This is an Mbed TLS extension.
- */
-void mbedtls_psa_crypto_free(void);
-
#ifdef __cplusplus
}
#endif
-#endif /* __PSA_CRYPTO_EXTRA_H__ */
+#endif /* PSA_CRYPTO_EXTRA_H */
diff --git a/interface/include/psa_crypto_platform.h b/interface/include/psa_crypto_platform.h
index 118897b..6d35c68 100644
--- a/interface/include/psa_crypto_platform.h
+++ b/interface/include/psa_crypto_platform.h
@@ -1,31 +1,32 @@
/*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
*/
-
/**
* \file psa_crypto_platform.h
*
* \brief PSA cryptography module: platform definitions
- */
-
-#ifndef __PSA_CRYPTO_PLATFORM_H__
-#define __PSA_CRYPTO_PLATFORM_H__
-
-/**
- * \note This file is meant to be included by psa_crypto.h only
*
+ * \note This file may not be included directly. Applications must
+ * include psa/crypto.h.
+ *
+ * This file contains platform-dependent type definitions.
+ *
+ * In implementations with isolation between the application and the
+ * cryptography module, implementers should take care to ensure that
+ * the definitions that are exposed to applications match what the
+ * module implements.
*/
+#ifndef PSA_CRYPTO_PLATFORM_H
+#define PSA_CRYPTO_PLATFORM_H
+
/* PSA requires several types which C99 provides in stdint.h. */
#include <stdint.h>
-/* The following header is needed for platform specific constants */
-#include <limits.h>
-
/* Integral type representing a key slot number. */
typedef uint16_t psa_key_slot_t;
-#endif /* __PSA_CRYPTO_PLATFORM_H__ */
+#endif /* PSA_CRYPTO_PLATFORM_H */
diff --git a/interface/include/psa_crypto_sizes.h b/interface/include/psa_crypto_sizes.h
new file mode 100644
index 0000000..07b52e4
--- /dev/null
+++ b/interface/include/psa_crypto_sizes.h
@@ -0,0 +1,255 @@
+/*
+ * Copyright (c) 2019, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+/**
+ * \file psa_crypto_sizes.h
+ *
+ * \brief PSA cryptography module: buffer size macros
+ *
+ * \note This file may not be included directly. Applications must
+ * include psa_crypto.h.
+ *
+ * This file contains the definitions of macros that are useful to
+ * compute buffer sizes. The signatures and semantics of these macros
+ * are standardized, but the definitions are not, because they depend on
+ * the available algorithms and, in some cases, on permitted tolerances
+ * on buffer sizes.
+ *
+ * In implementations with isolation between the application and the
+ * cryptography module, implementers should take care to ensure that
+ * the definitions that are exposed to applications match what the
+ * module implements.
+ *
+ * Macros that compute sizes whose values do not depend on the
+ * implementation are in psa_crypto.h.
+ */
+
+#ifndef PSA_CRYPTO_SIZES_H
+#define PSA_CRYPTO_SIZES_H
+
+/** \def PSA_HASH_MAX_SIZE
+ *
+ * Maximum size of a hash.
+ *
+ * This macro must expand to a compile-time constant integer. This value
+ * should be the maximum size of a hash supported by the implementation,
+ * in bytes, and must be no smaller than this maximum.
+ */
+#define PSA_HASH_MAX_SIZE 64
+#define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128
+
+/** \def PSA_MAC_MAX_SIZE
+ *
+ * Maximum size of a MAC.
+ *
+ * This macro must expand to a compile-time constant integer. This value
+ * should be the maximum size of a MAC supported by the implementation,
+ * in bytes, and must be no smaller than this maximum.
+ */
+/* All non-HMAC MACs have a maximum size that's smaller than the
+ * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */
+#define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE
+
+/* The maximum size of an RSA key on this implementation, in bits.
+ * This is a vendor-specific macro.
+ *
+ * Mbed Crypto does not set a hard limit on the size of RSA keys: any key
+ * whose parameters fit in a bignum is accepted. However large keys can
+ * induce a large memory usage and long computation times. Unlike other
+ * auxiliary macros in this file and in crypto.h, which reflect how the
+ * library is configured, this macro defines how the library is
+ * configured. This implementation refuses to import or generate an
+ * RSA key whose size is larger than the value defined here.
+ *
+ * Note that an implementation may set different size limits for different
+ * operations, and does not need to accept all key sizes up to the limit. */
+#define PSA_VENDOR_RSA_MAX_KEY_BITS 4096
+
+/* The maximum size of an ECC key on this implementation, in bits.
+ * This is a vendor-specific macro. */
+#define PSA_VENDOR_ECC_MAX_CURVE_BITS 0
+
+/** \def PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
+ *
+ * Maximum size of an asymmetric signature.
+ *
+ * This macro must expand to a compile-time constant integer. This value
+ * should be the maximum size of a MAC supported by the implementation,
+ * in bytes, and must be no smaller than this maximum.
+ */
+#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \
+ PSA_BITS_TO_BYTES( \
+ PSA_VENDOR_RSA_MAX_KEY_BITS > PSA_VENDOR_ECC_MAX_CURVE_BITS ? \
+ PSA_VENDOR_RSA_MAX_KEY_BITS : \
+ PSA_VENDOR_ECC_MAX_CURVE_BITS \
+ )
+
+
+
+/** The size of the output of psa_mac_sign_finish(), in bytes.
+ *
+ * This is also the MAC size that psa_mac_verify_finish() expects.
+ *
+ * \param key_type The type of the MAC key.
+ * \param key_bits The size of the MAC key in bits.
+ * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_MAC(alg) is true).
+ *
+ * \return The MAC size for the specified algorithm with
+ * the specified key parameters.
+ * \return 0 if the MAC algorithm is not recognized.
+ * \return Either 0 or the correct size for a MAC algorithm that
+ * the implementation recognizes, but does not support.
+ * \return Unspecified if the key parameters are not consistent
+ * with the algorithm.
+ */
+#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
+ (PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_HASH(alg)) : \
+ PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
+ 0)
+
+/** The maximum size of the output of psa_aead_encrypt(), in bytes.
+ *
+ * If the size of the ciphertext buffer is at least this large, it is
+ * guaranteed that psa_aead_encrypt() will not fail due to an
+ * insufficient buffer size. Depending on the algorithm, the actual size of
+ * the ciphertext may be smaller.
+ *
+ * \param alg An AEAD algorithm
+ * (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_AEAD(alg) is true).
+ * \param plaintext_length Size of the plaintext in bytes.
+ *
+ * \return The AEAD ciphertext size for the specified
+ * algorithm.
+ * If the AEAD algorithm is not recognized, return 0.
+ * An implementation may return either 0 or a
+ * correct size for an AEAD algorithm that it
+ * recognizes, but does not support.
+ */
+#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
+ (PSA_AEAD_TAG_SIZE(alg) != 0 ? \
+ (plaintext_length) + PSA_AEAD_TAG_SIZE(alg) : \
+ 0)
+
+/** The maximum size of the output of psa_aead_decrypt(), in bytes.
+ *
+ * If the size of the plaintext buffer is at least this large, it is
+ * guaranteed that psa_aead_decrypt() will not fail due to an
+ * insufficient buffer size. Depending on the algorithm, the actual size of
+ * the plaintext may be smaller.
+ *
+ * \param alg An AEAD algorithm
+ * (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_AEAD(alg) is true).
+ * \param ciphertext_length Size of the plaintext in bytes.
+ *
+ * \return The AEAD ciphertext size for the specified
+ * algorithm.
+ * If the AEAD algorithm is not recognized, return 0.
+ * An implementation may return either 0 or a
+ * correct size for an AEAD algorithm that it
+ * recognizes, but does not support.
+ */
+#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
+ (PSA_AEAD_TAG_SIZE(alg) != 0 ? \
+ (plaintext_length) - PSA_AEAD_TAG_SIZE(alg) : \
+ 0)
+
+/** Safe signature buffer size for psa_asymmetric_sign().
+ *
+ * This macro returns a safe buffer size for a signature using a key
+ * of the specified type and size, with the specified algorithm.
+ * Note that the actual size of the signature may be smaller
+ * (some algorithms produce a variable-size signature).
+ *
+ * \warning This function may call its arguments multiple times or
+ * zero times, so you should not pass arguments that contain
+ * side effects.
+ *
+ * \param key_type An asymmetric key type (this may indifferently be a
+ * key pair type or a public key type).
+ * \param key_bits The size of the key in bits.
+ * \param alg The signature algorithm.
+ *
+ * \return If the parameters are valid and supported, return
+ * a buffer size in bytes that guarantees that
+ * psa_asymmetric_sign() will not fail with
+ * #PSA_ERROR_BUFFER_TOO_SMALL.
+ * If the parameters are a valid combination that is not supported
+ * by the implementation, this macro either shall return either a
+ * sensible size or 0.
+ * If the parameters are not valid, the
+ * return value is unspecified.
+ */
+#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
+ (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
+ PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
+ ((void)alg, 0))
+
+/** Safe output buffer size for psa_asymmetric_encrypt().
+ *
+ * This macro returns a safe buffer size for a ciphertext produced using
+ * a key of the specified type and size, with the specified algorithm.
+ * Note that the actual size of the ciphertext may be smaller, depending
+ * on the algorithm.
+ *
+ * \warning This function may call its arguments multiple times or
+ * zero times, so you should not pass arguments that contain
+ * side effects.
+ *
+ * \param key_type An asymmetric key type (this may indifferently be a
+ * key pair type or a public key type).
+ * \param key_bits The size of the key in bits.
+ * \param alg The signature algorithm.
+ *
+ * \return If the parameters are valid and supported, return
+ * a buffer size in bytes that guarantees that
+ * psa_asymmetric_encrypt() will not fail with
+ * #PSA_ERROR_BUFFER_TOO_SMALL.
+ * If the parameters are a valid combination that is not supported
+ * by the implementation, this macro either shall return either a
+ * sensible size or 0.
+ * If the parameters are not valid, the
+ * return value is unspecified.
+ */
+#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
+ (PSA_KEY_TYPE_IS_RSA(key_type) ? \
+ ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
+ 0)
+
+/** Safe output buffer size for psa_asymmetric_decrypt().
+ *
+ * This macro returns a safe buffer size for a ciphertext produced using
+ * a key of the specified type and size, with the specified algorithm.
+ * Note that the actual size of the ciphertext may be smaller, depending
+ * on the algorithm.
+ *
+ * \warning This function may call its arguments multiple times or
+ * zero times, so you should not pass arguments that contain
+ * side effects.
+ *
+ * \param key_type An asymmetric key type (this may indifferently be a
+ * key pair type or a public key type).
+ * \param key_bits The size of the key in bits.
+ * \param alg The signature algorithm.
+ *
+ * \return If the parameters are valid and supported, return
+ * a buffer size in bytes that guarantees that
+ * psa_asymmetric_decrypt() will not fail with
+ * #PSA_ERROR_BUFFER_TOO_SMALL.
+ * If the parameters are a valid combination that is not supported
+ * by the implementation, this macro either shall return either a
+ * sensible size or 0.
+ * If the parameters are not valid, the
+ * return value is unspecified.
+ */
+#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
+ (PSA_KEY_TYPE_IS_RSA(key_type) ? \
+ PSA_BITS_TO_BYTES(key_bits) - PSA_RSA_MINIMUM_PADDING_SIZE(alg) : \
+ 0)
+
+#endif /* PSA_CRYPTO_SIZES_H */
diff --git a/interface/include/psa_crypto_struct.h b/interface/include/psa_crypto_struct.h
new file mode 100644
index 0000000..1882b64
--- /dev/null
+++ b/interface/include/psa_crypto_struct.h
@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2019, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+/**
+ * \file psa_crypto_struct.h
+ *
+ * \brief PSA cryptography module: structured type implementations
+ *
+ * \note This file may not be included directly. Applications must
+ * include psa_crypto.h.
+ *
+ * This file contains the definitions of some data structures with
+ * implementation-specific definitions.
+ *
+ * In implementations with isolation between the application and the
+ * cryptography module, it is expected that the front-end and the back-end
+ * would have different versions of this file.
+ */
+
+#ifndef PSA_CRYPTO_STRUCT_H
+#define PSA_CRYPTO_STRUCT_H
+
+struct psa_hash_operation_s
+{
+ uint32_t handle;
+};
+
+struct psa_mac_operation_s
+{
+ uint32_t handle;
+};
+
+struct psa_cipher_operation_s
+{
+ uint32_t handle;
+};
+
+struct psa_key_policy_s
+{
+ psa_key_usage_t usage;
+ psa_algorithm_t alg;
+};
+
+#endif /* PSA_CRYPTO_STRUCT_H */
diff --git a/interface/include/tfm_crypto_defs.h b/interface/include/tfm_crypto_defs.h
index 1332a00..e9bb955 100644
--- a/interface/include/tfm_crypto_defs.h
+++ b/interface/include/tfm_crypto_defs.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
@@ -28,17 +28,23 @@
#define TFM_CRYPTO_MAX_KEY_LENGTH (16)
/**
- * \brief Define miscellaneous literal constants that are used in the module
- *
- */
+ * \brief Define miscellaneous literal constants that are used in the module
+ *
+ */
enum {
TFM_CRYPTO_NOT_IN_USE = 0,
TFM_CRYPTO_IN_USE = 1
};
+/**
+ * \brief Possible return values from the TFM Crypto service. They must
+ * provide corresponding return values for psa_status_t possible
+ * values as specified in psa_crypto.h
+ */
enum tfm_crypto_err_t {
TFM_CRYPTO_ERR_PSA_SUCCESS = 0,
- TFM_CRYPTO_ERR_PSA_ERROR_NOT_SUPPORTED = TFM_CRYPTO_ERR_PSA_ERROR_OFFSET,
+ TFM_CRYPTO_ERR_PSA_ERROR_UNKNOWN_ERROR = TFM_CRYPTO_ERR_PSA_ERROR_OFFSET,
+ TFM_CRYPTO_ERR_PSA_ERROR_NOT_SUPPORTED,
TFM_CRYPTO_ERR_PSA_ERROR_NOT_PERMITTED,
TFM_CRYPTO_ERR_PSA_ERROR_BUFFER_TOO_SMALL,
TFM_CRYPTO_ERR_PSA_ERROR_OCCUPIED_SLOT,
@@ -54,21 +60,23 @@
TFM_CRYPTO_ERR_PSA_ERROR_INSUFFICIENT_ENTROPY,
TFM_CRYPTO_ERR_PSA_ERROR_INVALID_SIGNATURE,
TFM_CRYPTO_ERR_PSA_ERROR_INVALID_PADDING,
- TFM_CRYPTO_ERR_PSA_ERROR_UNKNOWN_ERROR,
/* Add an invalid return code which forces the size of the type as well */
TFM_CRYPTO_ERR_INVALID = INT_MAX
};
/**
- * \brief A macro to translate PSA API return values including the offset
- * needed by TFM, to the corresponding PSA value
+ * \brief A macro to translate TFM Crypto service return values to the
+ * corresponding PSA return value. The user of this macro needs
+ * to cast the produced value to psa_status_t explicitly if needed
+ *
+ * \return Values specified by \ref psa_status_t
*/
#define TFM_CRYPTO_PSA_RETURN(val) \
- ( (val == TFM_CRYPTO_ERR_PSA_SUCCESS) ? val : \
- ((val >= TFM_CRYPTO_ERR_PSA_ERROR_NOT_SUPPORTED) ? \
- (val - (TFM_CRYPTO_ERR_PSA_ERROR_NOT_SUPPORTED-1)) : \
- TFM_CRYPTO_ERR_INVALID) )
+ ( (val == TFM_CRYPTO_ERR_PSA_SUCCESS) ? val : \
+ ((val >= (enum tfm_crypto_err_t)TFM_CRYPTO_ERR_PSA_ERROR_OFFSET) ? \
+ (val - ((enum tfm_crypto_err_t)TFM_CRYPTO_ERR_PSA_ERROR_OFFSET-1)) : \
+ TFM_CRYPTO_ERR_INVALID) )
#ifdef __cplusplus
}
diff --git a/interface/include/tfm_crypto_veneers.h b/interface/include/tfm_crypto_veneers.h
index cce9432..bb2c6d4 100644
--- a/interface/include/tfm_crypto_veneers.h
+++ b/interface/include/tfm_crypto_veneers.h
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
@@ -78,7 +78,7 @@
*
* \return Return values as described in \ref tfm_crypto_err_t
*/
-enum tfm_crypto_err_t tfm_crypto_veneer_encrypt_set_iv(
+enum tfm_crypto_err_t tfm_crypto_veneer_cipher_set_iv(
psa_cipher_operation_t *operation,
const unsigned char *iv,
size_t iv_length);
@@ -92,7 +92,7 @@
*
* \return Return values as described in \ref tfm_crypto_err_t
*/
-enum tfm_crypto_err_t tfm_crypto_veneer_encrypt_setup(
+enum tfm_crypto_err_t tfm_crypto_veneer_cipher_encrypt_setup(
psa_cipher_operation_t *operation,
psa_key_slot_t key,
psa_algorithm_t alg);
@@ -106,7 +106,7 @@
*
* \return Return values as described in \ref tfm_crypto_err_t
*/
-enum tfm_crypto_err_t tfm_crypto_veneer_decrypt_setup(
+enum tfm_crypto_err_t tfm_crypto_veneer_cipher_decrypt_setup(
psa_cipher_operation_t *operation,
psa_key_slot_t key,
psa_algorithm_t alg);
@@ -154,14 +154,14 @@
size_t output_size,
size_t *output_length);
/**
- * \brief Starts a hash operation with the provided algorithm (veneer function)
+ * \brief Setup a hash operation with the provided algorithm (veneer function)
*
* \param[in] operation Hash operation context
* \param[in] alg Algorithm chosen as hash
*
* \return Returns values as described in \ref tfm_crypto_err_t
*/
-enum tfm_crypto_err_t tfm_crypto_veneer_hash_start(
+enum tfm_crypto_err_t tfm_crypto_veneer_hash_setup(
psa_hash_operation_t *operation,
psa_algorithm_t alg);
/**
diff --git a/interface/include/tfm_veneers.h b/interface/include/tfm_veneers.h
index d857675..4d4a38d 100644
--- a/interface/include/tfm_veneers.h
+++ b/interface/include/tfm_veneers.h
@@ -37,13 +37,13 @@
psa_status_t tfm_tfm_crypto_destroy_key_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
psa_status_t tfm_tfm_crypto_get_key_information_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
psa_status_t tfm_tfm_crypto_export_key_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
-psa_status_t tfm_tfm_crypto_encrypt_set_iv_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
-psa_status_t tfm_tfm_crypto_encrypt_setup_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
-psa_status_t tfm_tfm_crypto_decrypt_setup_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
+psa_status_t tfm_tfm_crypto_cipher_set_iv_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
+psa_status_t tfm_tfm_crypto_cipher_encrypt_setup_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
+psa_status_t tfm_tfm_crypto_cipher_decrypt_setup_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
psa_status_t tfm_tfm_crypto_cipher_update_wrapper_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
psa_status_t tfm_tfm_crypto_cipher_abort_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
psa_status_t tfm_tfm_crypto_cipher_finish_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
-psa_status_t tfm_tfm_crypto_hash_start_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
+psa_status_t tfm_tfm_crypto_hash_setup_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
psa_status_t tfm_tfm_crypto_hash_update_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
psa_status_t tfm_tfm_crypto_hash_finish_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
psa_status_t tfm_tfm_crypto_hash_verify_veneer(struct psa_invec *in_vec, size_t in_len, struct psa_outvec *out_vec, size_t out_len);
diff --git a/interface/src/tfm_crypto_api.c b/interface/src/tfm_crypto_api.c
index dbeb6a8..a51ac1f 100644
--- a/interface/src/tfm_crypto_api.c
+++ b/interface/src/tfm_crypto_api.c
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
@@ -87,13 +87,13 @@
return PSA_ERROR_NOT_SUPPORTED;
}
-psa_status_t psa_encrypt_set_iv(psa_cipher_operation_t *operation,
- const unsigned char *iv,
- size_t iv_length)
+psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
+ const unsigned char *iv,
+ size_t iv_length)
{
enum tfm_crypto_err_t err;
- err = tfm_ns_lock_dispatch((veneer_fn)tfm_crypto_veneer_encrypt_set_iv,
+ err = tfm_ns_lock_dispatch((veneer_fn)tfm_crypto_veneer_cipher_set_iv,
(uint32_t)operation,
(uint32_t)iv,
(uint32_t)iv_length,
@@ -102,32 +102,34 @@
return TFM_CRYPTO_PSA_RETURN(err);
}
-psa_status_t psa_encrypt_setup(psa_cipher_operation_t *operation,
- psa_key_slot_t key,
- psa_algorithm_t alg)
+psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
+ psa_key_slot_t key,
+ psa_algorithm_t alg)
{
enum tfm_crypto_err_t err;
- err = tfm_ns_lock_dispatch((veneer_fn)tfm_crypto_veneer_encrypt_setup,
- (uint32_t)operation,
- (uint32_t)key,
- (uint32_t)alg,
- 0);
+ err = tfm_ns_lock_dispatch(
+ (veneer_fn)tfm_crypto_veneer_cipher_encrypt_setup,
+ (uint32_t)operation,
+ (uint32_t)key,
+ (uint32_t)alg,
+ 0);
return TFM_CRYPTO_PSA_RETURN(err);
}
-psa_status_t psa_decrypt_setup(psa_cipher_operation_t *operation,
- psa_key_slot_t key,
- psa_algorithm_t alg)
+psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
+ psa_key_slot_t key,
+ psa_algorithm_t alg)
{
enum tfm_crypto_err_t err;
- err = tfm_ns_lock_dispatch((veneer_fn)tfm_crypto_veneer_decrypt_setup,
- (uint32_t)operation,
- (uint32_t)key,
- (uint32_t)alg,
- 0);
+ err = tfm_ns_lock_dispatch(
+ (veneer_fn)tfm_crypto_veneer_cipher_decrypt_setup,
+ (uint32_t)operation,
+ (uint32_t)key,
+ (uint32_t)alg,
+ 0);
return TFM_CRYPTO_PSA_RETURN(err);
}
@@ -189,12 +191,12 @@
return TFM_CRYPTO_PSA_RETURN(err);
}
-psa_status_t psa_hash_start(psa_hash_operation_t *operation,
+psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
psa_algorithm_t alg)
{
enum tfm_crypto_err_t err;
- err = tfm_ns_lock_dispatch((veneer_fn)tfm_crypto_veneer_hash_start,
+ err = tfm_ns_lock_dispatch((veneer_fn)tfm_crypto_veneer_hash_setup,
(uint32_t)operation,
(uint32_t)alg,
0,