lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-08-01 10:06:53 +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

8
include/mbedtls/check_config.h
View File

@ -581,6 +581,14 @@
#error "MBEDTLS_PSA_CRYPTO_SE_C defined, but not all prerequisites"
#endif
#if defined(MBEDTLS_PSA_CRYPTO_SE_C)
#if defined(MBEDTLS_DEPRECATED_REMOVED)
#error "MBEDTLS_PSA_CRYPTO_SE_C is deprecated and will be removed in a future version of Mbed TLS"
#elif defined(MBEDTLS_DEPRECATED_WARNING)
#warning "MBEDTLS_PSA_CRYPTO_SE_C is deprecated and will be removed in a future version of Mbed TLS"
#endif
#endif /* MBEDTLS_PSA_CRYPTO_SE_C */
#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) && \
! defined(MBEDTLS_PSA_CRYPTO_C)
#error "MBEDTLS_PSA_CRYPTO_STORAGE_C defined, but not all prerequisites"

11
include/mbedtls/mbedtls_config.h
View File

@ -1184,8 +1184,9 @@
*
* Requires: MBEDTLS_PSA_CRYPTO_C
*
* \warning This interface is experimental and may change or be removed
* without notice.
* \warning This interface is experimental. We intend to maintain backward
* compatibility with application code that relies on drivers,
* but the driver interfaces may change without notice.
*/
//#define MBEDTLS_PSA_CRYPTO_DRIVERS
@ -2690,11 +2691,11 @@
/**
* \def MBEDTLS_PSA_CRYPTO_SE_C
*
* Enable secure element support in the Platform Security Architecture
* Enable dynamic secure element support in the Platform Security Architecture
* cryptography API.
*
* \warning This feature is not yet suitable for production. It is provided
* for API evaluation and testing purposes only.
* \deprecated This feature is deprecated. Please switch to the driver
* interface enabled by #MBEDTLS_PSA_CRYPTO_DRIVERS.
*
* Module: library/psa_crypto_se.c
*

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