Wrote documentation for several functions, macros and types
Document key import/export functions, hash functions, and asymmetric
sign/verify, as well as some related macros and types.
Nicer formatting for return values: use \retval.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 90140d7..060c007 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -18,7 +18,7 @@
/** \brief Key slot number.
*
* This type represents key slots. It must be an unsigned integral
- * type.* The choice of type is implementation-dependent.
+ * type. The choice of type is implementation-dependent.
* 0 is not a valid key slot number. The meaning of other values is
* implementation dependent.
*
@@ -98,12 +98,12 @@
* Applications may call this function more than once. Once a call
* succeeds, subsequent calls are guaranteed to succeed.
*
- * \return * \c PSA_SUCCESS: success.
- * * \c PSA_ERROR_INSUFFICIENT_MEMORY
- * * \c PSA_ERROR_COMMUNICATION_FAILURE
- * * \c PSA_ERROR_HARDWARE_FAILURE
- * * \c PSA_ERROR_TAMPERING_DETECTED
- * * \c 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);
@@ -116,6 +116,8 @@
* @{
*/
+/** \brief Encoding of a key type.
+ */
typedef uint32_t psa_key_type_t;
#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x00000000)
@@ -133,7 +135,9 @@
#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x04000003)
#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)
#define PSA_KEY_TYPE_ECC_BASE ((psa_key_type_t)0x06030000)
#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff)
@@ -153,6 +157,14 @@
#define PSA_KEY_TYPE_IS_ECC(type) \
(((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_BASE)
+/** \brief Encoding of a cryptographic algorithm.
+ *
+ * For algorithms that can be applied to multiple key types, this type
+ * does not encode the key type. For example, for symmetric ciphers
+ * based on a block cipher, #psa_algorithm_t encodes the block cipher
+ * mode and the padding mode while the block cipher itself is encoded
+ * via #psa_key_type_t.
+ */
typedef uint32_t psa_algorithm_t;
#define PSA_ALG_VENDOR_FLAG ((psa_algorithm_t)0x80000000)
@@ -168,6 +180,13 @@
#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 (\c PSA_ALG_XXX value)
+ *
+ * \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
+ * algorithm identifier. */
#define PSA_ALG_IS_HASH(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH)
#define PSA_ALG_IS_MAC(alg) \
@@ -245,13 +264,26 @@
*
* This function supports any output from psa_export_key().
*
- * \return * \c PSA_SUCCESS: success.
- * * \c PSA_ERROR_NOT_SUPPORTED
- * * \c PSA_ERROR_INVALID_ARGUMENT
- * * \c PSA_ERROR_INSUFFICIENT_MEMORY
- * * \c PSA_ERROR_COMMUNICATION_FAILURE
- * * \c PSA_ERROR_HARDWARE_FAILURE
- * * \c PSA_ERROR_TAMPERING_DETECTED
+ * \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).
+ * \param data Buffer containing the key data.
+ * \param data_length Size of the \c data buffer in bytes.
+ *
+ * \retval PSA_SUCCESS
+ * Success.
+ * \retval PSA_ERROR_NOT_SUPPORTED
+ * The key type or key size is not supported.
+ * \retval PSA_ERROR_INVALID_ARGUMENT
+ * The key slot is invalid,
+ * or the key data is not correctly formatted.
+ * \retval PSA_ERROR_OCCUPIED_SLOT
+ There is already a key in the specified slot.
+ * \retval PSA_ERROR_INSUFFICIENT_MEMORY
+ * \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,
@@ -261,22 +293,31 @@
/**
* \brief Destroy a key.
*
- * \return * \c PSA_SUCCESS: success.
- * * \c PSA_ERROR_EMPTY_SLOT
- * * \c PSA_ERROR_COMMUNICATION_FAILURE
- * * \c PSA_ERROR_HARDWARE_FAILURE
- * * \c 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_destroy_key(psa_key_slot_t key);
/**
* \brief Get basic metadata about a key.
*
- * \return * \c PSA_SUCCESS: success.
- * * \c PSA_ERROR_EMPTY_SLOT
- * * \c PSA_ERROR_COMMUNICATION_FAILURE
- * * \c PSA_ERROR_HARDWARE_FAILURE
- * * \c PSA_ERROR_TAMPERING_DETECTED
+ * \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).
+ * This may be a null pointer, in which case the key type
+ * is not written.
+ * \param bits On success, the key size in bits.
+ * This may be a null pointer, in which case the key type
+ * 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
*/
psa_status_t psa_get_key_information(psa_key_slot_t key,
psa_key_type_t *type,
@@ -293,11 +334,32 @@
* identical: the implementation may choose a different representation
* of the same key.
*
- * \return * \c PSA_SUCCESS: success.
- * * \c PSA_ERROR_EMPTY_SLOT
- * * \c PSA_ERROR_COMMUNICATION_FAILURE
- * * \c PSA_ERROR_HARDWARE_FAILURE
- * * \c PSA_ERROR_TAMPERING_DETECTED
+ * For standard key types, the output format is as follows:
+ *
+ * - For symmetric keys (including MAC keys), the format is the
+ * raw bytes of the key.
+ * - For DES, the key data consists of 8 bytes. The parity bits must be
+ * correct.
+ * - For Triple-DES, the format is the concatenation of the
+ * two or three DES keys.
+ * - For RSA key pairs keys (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
+ * is the non-encrypted DER representation defined by PKCS\#8 (RFC 5208)
+ * as PrivateKeyInfo.
+ * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
+ * is the DER representation defined by X.509.
+ *
+ * \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.
+ *
+ * \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_export_key(psa_key_slot_t key,
uint8_t *data,
@@ -311,8 +373,25 @@
* @{
*/
+/** The type of the state data structure for multipart hash operations.
+ *
+ * This is an implementation-define \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).
+ *
+ * \return The hash size for the specified hash algorithm.
+ * If the hash algorithm is not recognized, return 0.
+ * An implementation may return either 0 or the correct size
+ * for a hash algorithm that it recognizes, but does not support.
+ */
#define PSA_HASH_FINAL_SIZE(alg) \
( \
(alg) == PSA_ALG_MD2 ? 16 : \
@@ -334,27 +413,168 @@
(alg) == PSA_ALG_SHA3_512 ? 64 : \
0)
+/** Start a multipart hash operation.
+ *
+ * The sequence of operations to calculate a hash (message digest)
+ * 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_update() zero, one or more time, passing a fragment
+ * of the message each time. The hash that is calculated is the hash
+ * of the concatenation of these messages in order.
+ * -# To calculate the hash, call psa_hash_finish().
+ * 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().
+ *
+ * After a successful call to psa_hash_start(), the application must
+ * eventually destroy the operation through one of the following means:
+ * - A failed call to psa_hash_update().
+ * - A call to psa_hash_final(), psa_hash_verify() or psa_hash_abort().
+ *
+ * \param operation
+ * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
+ * such that #PSA_ALG_IS_HASH(alg) is true).
+ *
+ * \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
+ */
psa_status_t psa_hash_start(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.
+ *
+ * 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.
+ *
+ * \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_hash_update(psa_hash_operation_t *operation,
const uint8_t *input,
size_t input_length);
+/** Finish the calculation of the hash of a message.
+ *
+ * The application must call psa_hash_start() 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().
+ *
+ * When this function returns, the operation becomes inactive.
+ *
+ * \warning Applications should not call this function if they expect
+ * a specific value for the hash. Call psa_hash_verify() instead.
+ * Beware that comparing integrity or authenticity data such as
+ * hash values with a function such as \c memcmp is risky
+ * because the time taken by the comparison may leak information
+ * 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_FINAL_SIZE(alg) where \c alg is the
+ * hash 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 \c hash buffer is too small. You can determine a
+ * sufficient buffer size by calling #PSA_HASH_FINAL_SIZE(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
+ */
psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
uint8_t *hash,
size_t hash_size,
size_t *hash_length);
+/** 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.
+ * 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
+ * parameter to this function.
+ *
+ * When this function returns, the operation becomes inactive.
+ *
+ * \note Applications shall make the best effort to ensure that the
+ * 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.
+ *
+ * \retval PSA_SUCCESS
+ * The expected hash is identical to the actual hash of the message.
+ * \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
+ * 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_hash_verify(psa_hash_operation_t *operation,
const uint8_t *hash,
size_t hash_length);
-psa_status_t ps_hash_abort(psa_hash_operation_t *operation);
+/** 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.
+ *
+ * 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.
+ *
+ * \param operation Active hash operation.
+ *
+ * \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
+ */
+psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
/**@}*/
-/** \defgroup MAC Message authentication codes
/** \defgroup asymmetric Asymmetric cryptography
* @{
*/
@@ -389,6 +609,33 @@
/*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, BITS_TO_BYTES(key_bits)) : \
PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
@@ -397,6 +644,41 @@
/**
* \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.
+ * This is at most #PSA_HASH_FINAL_SIZE(alg)
+ * (note that it may be less).
+ *
+ * \retval PSA_SUCCESS
+ * \retval PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \c signature buffer is too small. You can
+ * determine a sufficient buffer size by calling
+ * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, 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
*/
psa_status_t psa_asymmetric_sign(psa_key_slot_t key,
psa_algorithm_t alg,
@@ -411,6 +693,35 @@
/**
* \brief Verify the signature a hash or short message using a public key.
*
+ * \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.
+ *
+ * \retval PSA_SUCCESS
+ * The signature is valid.
+ * \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
*/
psa_status_t psa_asymmetric_verify(psa_key_slot_t key,
psa_algorithm_t alg,