diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index ec6890ad01..e619cf537e 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -73,6 +73,11 @@ typedef int32_t psa_status_t; * * Values of this type are generally constructed by macros called * `PSA_KEY_TYPE_xxx`. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. */ typedef uint16_t psa_key_type_t; @@ -87,6 +92,11 @@ typedef uint16_t psa_key_type_t; * * Values defined by this standard will never be in the range 0x80-0xff. * Vendors who define additional families must use an encoding in this range. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. */ typedef uint8_t psa_ecc_family_t; @@ -101,6 +111,11 @@ typedef uint8_t psa_ecc_family_t; * * Values defined by this standard will never be in the range 0x80-0xff. * Vendors who define additional families must use an encoding in this range. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. */ typedef uint8_t psa_dh_family_t; @@ -114,6 +129,11 @@ typedef uint8_t psa_dh_family_t; * 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. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. */ typedef uint32_t psa_algorithm_t; @@ -158,6 +178,11 @@ typedef uint32_t psa_algorithm_t; * * Values of this type are generally constructed by macros called * `PSA_KEY_LIFETIME_xxx`. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. */ typedef uint32_t psa_key_lifetime_t; @@ -189,6 +214,11 @@ typedef uint32_t psa_key_lifetime_t; * \note Key persistence levels are 8-bit values. Key management * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which * encode the persistence as the lower 8 bits of a 32-bit value. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. */ typedef uint8_t psa_key_persistence_t; @@ -225,6 +255,11 @@ typedef uint8_t psa_key_persistence_t; * \note Key location indicators are 24-bit values. Key management * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which * encode the location as the upper 24 bits of a 32-bit value. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. */ typedef uint32_t psa_key_location_t; @@ -236,9 +271,27 @@ typedef uint32_t psa_key_location_t; * #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX. * - 0 is reserved as an invalid key identifier. * - Key identifiers outside these ranges are reserved for future use. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to how values are allocated must require careful + * consideration to allow backward compatibility. */ typedef uint32_t psa_key_id_t; +/** Encoding of key identifiers as seen inside the PSA Crypto implementation. + * + * When PSA Crypto is built as a library inside an application, this type + * is identical to #psa_key_id_t. When PSA Crypto is built as a service + * that can store keys on behalf of multiple clients, this type + * encodes the #psa_key_id_t value seen by each client application as + * well as extra information that identifies the client that owns + * the key. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. +*/ #if !defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) typedef psa_key_id_t mbedtls_svc_key_id_t; @@ -266,6 +319,11 @@ typedef struct * * Values of this type are generally constructed as bitwise-ors of macros * called `PSA_KEY_USAGE_xxx`. + * + * \note Values of this type are encoded in the persistent key store. + * Any changes to existing values will require bumping the storage + * format version and providing a translation when reading the old + * format. */ typedef uint32_t psa_key_usage_t; diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index 17d7a9bcd5..99be43395d 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -12,6 +12,11 @@ * designations of cryptographic algorithms, and error codes returned by * the library. * + * Note that many of the constants defined in this file are embedded in + * the persistent key store, as part of key metadata (including usage + * policies). As a consequence, they must not be changed (unless the storage + * format version changes). + * * This header file only defines preprocessor macros. */ /* @@ -41,6 +46,11 @@ /* PSA error codes */ +/* Error codes are standardized across PSA domains (framework, crypto, storage, + * etc.). Do not change the values in this section. If you must add a new + * value, check with the Arm PSA framework group to pick one that other + * domains aren't already using. */ + /** The action was completed successfully. */ #define PSA_SUCCESS ((psa_status_t)0) @@ -317,6 +327,12 @@ * @{ */ +/* Note that key type values, including ECC family and DH group values, are + * embedded in the persistent key store, as part of key metadata. As a + * consequence, they must not be changed (unless the storage format version + * changes). + */ + /** An invalid key type value. * * Zero is not the encoding of any key type. @@ -719,6 +735,11 @@ 1u << PSA_GET_KEY_TYPE_BLOCK_SIZE_EXPONENT(type) : \ 0u) +/* Note that algorithm values are embedded in the persistent key store, + * as part of key metadata. As a consequence, they must not be changed + * (unless the storage format version changes). + */ + /** Vendor-defined algorithm flag. * * Algorithms defined by this standard will never have the #PSA_ALG_VENDOR_FLAG @@ -2095,6 +2116,11 @@ * @{ */ +/* Note that location and persistence level values are embedded in the + * persistent key store, as part of key metadata. As a consequence, they + * must not be changed (unless the storage format version changes). + */ + /** The default lifetime for volatile keys. * * A volatile key only exists as long as the identifier to it is not destroyed. @@ -2210,6 +2236,11 @@ #define PSA_KEY_LOCATION_VENDOR_FLAG ((psa_key_location_t)0x800000) +/* Note that key identifier values are embedded in the + * persistent key store, as part of key metadata. As a consequence, they + * must not be changed (unless the storage format version changes). + */ + /** The null key identifier. */ #define PSA_KEY_ID_NULL ((psa_key_id_t)0) @@ -2321,6 +2352,11 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key ) * @{ */ +/* Note that key usage flags are embedded in the + * persistent key store, as part of key metadata. As a consequence, they + * must not be changed (unless the storage format version changes). + */ + /** Whether the key may be exported. * * A public key or the public part of a key pair may always be exported @@ -2447,6 +2483,9 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key ) * @{ */ +/* Key input steps are not embedded in the persistent storage, so you can + * change them if needed: it's only an ABI change. */ + /** A secret input for key derivation. * * This should be a key of type #PSA_KEY_TYPE_DERIVE