Merge pull request #119 from gilles-peskine-arm/psa-api-1.0-beta-beta3_minor_fixes

PSA 1.0 beta3 minor fixes
This commit is contained in:
Jaeden Amero 2019-05-21 17:52:57 +01:00 committed by GitHub
commit 5b93990fc1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 73 additions and 32 deletions

View file

@ -204,6 +204,22 @@ psa_status_t psa_crypto_init(void);
*/ */
typedef struct psa_key_attributes_s psa_key_attributes_t; typedef struct psa_key_attributes_s psa_key_attributes_t;
/** \def PSA_KEY_ATTRIBUTES_INIT
*
* This macro returns a suitable initializer for a key attribute structure
* of type #psa_key_attributes_t.
*/
#ifdef __DOXYGEN_ONLY__
/* This is an example definition for documentation purposes.
* Implementations should define a suitable value in `crypto_struct.h`.
*/
#define PSA_KEY_ATTRIBUTES_INIT {0}
#endif
/** Return an initial value for a key attributes structure.
*/
static psa_key_attributes_t psa_key_attributes_init(void);
/** Declare a key as persistent and set its key identifier. /** Declare a key as persistent and set its key identifier.
* *
* If the attribute structure currently declares the key as volatile (which * If the attribute structure currently declares the key as volatile (which
@ -445,10 +461,17 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
/** Open a handle to an existing persistent key. /** Open a handle to an existing persistent key.
* *
* Open a handle to a key which was previously created with * Open a handle to a persistent key. A key is persistent if it was created
* psa_make_key_persistent() when setting its attributes. * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
* The handle should eventually be closed with psa_close_key() * always has a nonzero key identifier, set with psa_set_key_id() when
* to release associated resources. * creating the key. Implementations may provide additional pre-provisioned
* keys with identifiers in the range
* #PSA_KEY_ID_VENDOR_MIN–#PSA_KEY_ID_VENDOR_MAX.
*
* The application must eventually close the handle with psa_close_key()
* to release associated resources. If the application dies without calling
* psa_close_key(), the implementation should perform the equivalent of a
* call to psa_close_key().
* *
* Implementations may provide additional keys that can be opened with * Implementations may provide additional keys that can be opened with
* psa_open_key(). Such keys have a key identifier in the vendor range, * psa_open_key(). Such keys have a key identifier in the vendor range,

View file

@ -426,9 +426,9 @@
#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \ #define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
(PSA_BITS_TO_BYTES(curve_bits) * 2) (PSA_BITS_TO_BYTES(curve_bits) * 2)
/** Safe signature buffer size for psa_asymmetric_sign(). /** Sufficient signature buffer size for psa_asymmetric_sign().
* *
* This macro returns a safe buffer size for a signature using a key * This macro returns a sufficient buffer size for a signature using a key
* of the specified type and size, with the specified algorithm. * of the specified type and size, with the specified algorithm.
* Note that the actual size of the signature may be smaller * Note that the actual size of the signature may be smaller
* (some algorithms produce a variable-size signature). * (some algorithms produce a variable-size signature).
@ -457,9 +457,9 @@
PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \ PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
((void)alg, 0)) ((void)alg, 0))
/** Safe output buffer size for psa_asymmetric_encrypt(). /** Sufficient output buffer size for psa_asymmetric_encrypt().
* *
* This macro returns a safe buffer size for a ciphertext produced using * This macro returns a sufficient buffer size for a ciphertext produced using
* a key of the specified type and size, with the specified algorithm. * a key of the specified type and size, with the specified algorithm.
* Note that the actual size of the ciphertext may be smaller, depending * Note that the actual size of the ciphertext may be smaller, depending
* on the algorithm. * on the algorithm.
@ -488,9 +488,9 @@
((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \ ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
0) 0)
/** Safe output buffer size for psa_asymmetric_decrypt(). /** Sufficient output buffer size for psa_asymmetric_decrypt().
* *
* This macro returns a safe buffer size for a ciphertext produced using * This macro returns a sufficient buffer size for a ciphertext produced using
* a key of the specified type and size, with the specified algorithm. * a key of the specified type and size, with the specified algorithm.
* Note that the actual size of the ciphertext may be smaller, depending * Note that the actual size of the ciphertext may be smaller, depending
* on the algorithm. * on the algorithm.
@ -629,7 +629,7 @@
#define PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) \ #define PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) \
(PSA_BITS_TO_BYTES(key_bits)) (PSA_BITS_TO_BYTES(key_bits))
/** Safe output buffer size for psa_export_key() or psa_export_public_key(). /** Sufficient output buffer size for psa_export_key() or psa_export_public_key().
* *
* This macro returns a compile-time constant if its arguments are * This macro returns a compile-time constant if its arguments are
* compile-time constants. * compile-time constants.
@ -641,14 +641,16 @@
* The following code illustrates how to allocate enough memory to export * The following code illustrates how to allocate enough memory to export
* a key by querying the key type and size at runtime. * a key by querying the key type and size at runtime.
* \code{c} * \code{c}
* psa_key_type_t key_type; * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
* size_t key_bits;
* psa_status_t status; * psa_status_t status;
* status = psa_get_key_information(key, &key_type, &key_bits); * status = psa_get_key_attributes(key, &attributes);
* if (status != PSA_SUCCESS) handle_error(...); * if (status != PSA_SUCCESS) handle_error(...);
* psa_key_type_t key_type = psa_get_key_type(&attributes);
* size_t key_bits = psa_get_key_bits(&attributes);
* size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits); * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits);
* psa_reset_key_attributes(&attributes);
* unsigned char *buffer = malloc(buffer_size); * unsigned char *buffer = malloc(buffer_size);
* if (buffer != NULL) handle_error(...); * if (buffer == NULL) handle_error(...);
* size_t buffer_length; * size_t buffer_length;
* status = psa_export_key(key, buffer, buffer_size, &buffer_length); * status = psa_export_key(key, buffer, buffer_size, &buffer_length);
* if (status != PSA_SUCCESS) handle_error(...); * if (status != PSA_SUCCESS) handle_error(...);
@ -658,15 +660,17 @@
* public key type. You can use the macro #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR * public key type. You can use the macro #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR
* to convert a key pair type to the corresponding public key type. * to convert a key pair type to the corresponding public key type.
* \code{c} * \code{c}
* psa_key_type_t key_type; * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
* size_t key_bits;
* psa_status_t status; * psa_status_t status;
* status = psa_get_key_information(key, &key_type, &key_bits); * status = psa_get_key_attributes(key, &attributes);
* if (status != PSA_SUCCESS) handle_error(...); * if (status != PSA_SUCCESS) handle_error(...);
* psa_key_type_t key_type = psa_get_key_type(&attributes);
* psa_key_type_t public_key_type = PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(key_type); * psa_key_type_t public_key_type = PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(key_type);
* size_t key_bits = psa_get_key_bits(&attributes);
* size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(public_key_type, key_bits); * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(public_key_type, key_bits);
* psa_reset_key_attributes(&attributes);
* unsigned char *buffer = malloc(buffer_size); * unsigned char *buffer = malloc(buffer_size);
* if (buffer != NULL) handle_error(...); * if (buffer == NULL) handle_error(...);
* size_t buffer_length; * size_t buffer_length;
* status = psa_export_public_key(key, buffer, buffer_size, &buffer_length); * status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
* if (status != PSA_SUCCESS) handle_error(...); * if (status != PSA_SUCCESS) handle_error(...);

View file

@ -45,9 +45,9 @@
* \brief Function return status. * \brief Function return status.
* *
* This is either #PSA_SUCCESS (which is zero), indicating success, * This is either #PSA_SUCCESS (which is zero), indicating success,
* or a nonzero value indicating that an error occurred. Errors are * or a small negative value indicating that an error occurred. Errors are
* encoded as one of the \c PSA_ERROR_xxx values defined here. * encoded as one of the \c PSA_ERROR_xxx values defined here. */
* If #PSA_SUCCESS is already defined, it means that #psa_status_t /* If #PSA_SUCCESS is already defined, it means that #psa_status_t
* is also defined in an external header, so prevent its multiple * is also defined in an external header, so prevent its multiple
* definition. * definition.
*/ */

View file

@ -373,7 +373,7 @@
*/ */
#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x52000000) #define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x52000000)
/** Key for an cipher, AEAD or MAC algorithm based on the AES block cipher. /** Key for a 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 * The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or
* 32 bytes (AES-256). * 32 bytes (AES-256).
@ -391,7 +391,7 @@
*/ */
#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x40000002) #define PSA_KEY_TYPE_DES ((psa_key_type_t)0x40000002)
/** Key for an cipher, AEAD or MAC algorithm based on the /** Key for a cipher, AEAD or MAC algorithm based on the
* Camellia block cipher. */ * Camellia block cipher. */
#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x40000003) #define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x40000003)
@ -1232,11 +1232,14 @@
* specified in Section 5 of RFC 5246. It is based on HMAC and can be * specified in Section 5 of RFC 5246. It is based on HMAC and can be
* used with either SHA-256 or SHA-384. * used with either SHA-256 or SHA-384.
* *
* For the application to TLS-1.2, the salt and label arguments passed * This key derivation algorithm uses the following inputs:
* to psa_key_derivation() are what's called 'seed' and 'label' in RFC 5246, * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key.
* respectively. For example, for TLS key expansion, the salt is the * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label.
* - #PSA_KEY_DERIVATION_INPUT_SEED is the seed.
*
* For the application to TLS-1.2 key expansion, the seed is the
* concatenation of ServerHello.Random + ClientHello.Random, * concatenation of ServerHello.Random + ClientHello.Random,
* while the label is "key expansion". * and the label is "key expansion".
* *
* For example, `PSA_ALG_TLS12_PRF(PSA_ALG_SHA256)` represents the * For example, `PSA_ALG_TLS12_PRF(PSA_ALG_SHA256)` represents the
* TLS 1.2 PRF using HMAC-SHA-256. * TLS 1.2 PRF using HMAC-SHA-256.
@ -1273,10 +1276,15 @@
* The latter is based on HMAC and can be used with either SHA-256 * The latter is based on HMAC and can be used with either SHA-256
* or SHA-384. * or SHA-384.
* *
* For the application to TLS-1.2, the salt passed to psa_key_derivation() * This key derivation algorithm uses the following inputs:
* (and forwarded to the TLS-1.2 PRF) is the concatenation of the * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key.
* ClientHello.Random + ServerHello.Random, while the label is "master secret" * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label.
* or "extended master secret". * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed.
*
* For the application to TLS-1.2, the seed (which is
* forwarded to the TLS-1.2 PRF) is the concatenation of the
* ClientHello.Random + ServerHello.Random,
* and the label is "master secret" or "extended master secret".
* *
* For example, `PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA256)` represents the * For example, `PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA256)` represents the
* TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256. * TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256.
@ -1586,6 +1594,12 @@
*/ */
#define PSA_KEY_DERIVATION_INPUT_INFO ((psa_key_derivation_step_t)0x0203) #define PSA_KEY_DERIVATION_INPUT_INFO ((psa_key_derivation_step_t)0x0203)
/** A seed for key derivation.
*
* This must be a direct input.
*/
#define PSA_KEY_DERIVATION_INPUT_SEED ((psa_key_derivation_step_t)0x0204)
/**@}*/ /**@}*/
#endif /* PSA_CRYPTO_VALUES_H */ #endif /* PSA_CRYPTO_VALUES_H */