lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-07-29 11:41:15 +03:00
Code Activity

Merge pull request #5962 from gilles-peskine-arm/storage-format-doc-202206

Browse Source 
Documentation about storage format compatibility
This commit is contained in:
Manuel Pégourié-Gonnard
2022-07-01 12:21:17 +02:00
committed by GitHub
parent 11ccb35987 955993c4b5
commit 790ab52ee0
12 changed files with 269 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
include/psa/crypto_types.h
View File

@ -70,10 +70,21 @@ typedef int32_t psa_status_t;
*/
/** \brief Encoding of a key type.
*
* 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;
/** The type of PSA elliptic curve family identifiers.
*
* Values of this type are generally constructed by macros called
* `PSA_ECC_FAMILY_xxx`.
*
* The curve identifier is required to create an ECC key using the
* PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY()
@ -81,10 +92,18 @@ 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;
/** The type of PSA Diffie-Hellman group family identifiers.
*
* Values of this type are generally constructed by macros called
* `PSA_DH_FAMILY_xxx`.
*
* The group identifier is required to create an Diffie-Hellman key using the
* PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY()
@ -92,16 +111,29 @@ 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;
/** \brief Encoding of a cryptographic algorithm.
*
* Values of this type are generally constructed by macros called
* `PSA_ALG_xxx`.
*
* 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.
*
* \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;
@ -143,6 +175,14 @@ typedef uint32_t psa_algorithm_t;
* #PSA_KEY_LIFETIME_PERSISTENT is supported if persistent storage is
* available. Other lifetime values may be supported depending on the
* library configuration.
*
* 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;
@ -174,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;
@ -210,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;
@ -221,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;
@ -247,7 +315,16 @@ typedef struct
* @{
*/
/** \brief Encoding of permitted usage on a key. */
/** \brief Encoding of permitted usage on a key.
*
* 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;
/**@}*/
@ -376,7 +453,11 @@ typedef uint64_t psa_key_slot_number_t;
* @{
*/
/** \brief Encoding of the step of a key derivation. */
/** \brief Encoding of the step of a key derivation.
*
* Values of this type are generally constructed by macros called
* `PSA_KEY_DERIVATION_INPUT_xxx`.
*/
typedef uint16_t psa_key_derivation_step_t;
/**@}*/

46
include/psa/crypto_values.h
View File

@ -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,18 @@
/* PSA error codes */
/* Error codes are standardized across PSA domains (framework, crypto, storage,
* etc.). Do not change the values in this section or even the expansions
* of each macro: it must be possible to `#include` both this header
* and some other PSA component's headers in the same C source,
* which will lead to duplicate definitions of the `PSA_SUCCESS` and
* `PSA_ERROR_xxx` macros, which is ok if and only if the macros expand
* to the same sequence of tokens.
*
* 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 +334,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 +742,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
@ -2207,6 +2235,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.
@ -2322,6 +2355,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)
@ -2433,6 +2471,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
@ -2559,6 +2602,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