yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-12-23 08:55:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Replace spec language by Mbed TLS documentation: lifetimes

Browse source 
In the documentation of lifetimes, replace language meant for the PSA
specification by language that is specifically about Mbed TLS. Reduce
the discussion of what could happen in other implementation, and
discuss what can and cannot happen in integrations of Mbed TLS.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
This commit is contained in:
Gilles Peskine 2020-08-18 23:05:06 +02:00
parent 08bde36e73
commit d0107b96af
2 changed files with 18 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
include/psa/crypto_types.h
View file

@ -123,7 +123,7 @@ typedef uint32_t psa_algorithm_t;
* Volatile keys are automatically destroyed when the application instance * Volatile keys are automatically destroyed when the application instance
* terminates or on a power reset of the device. Persistent keys are * terminates or on a power reset of the device. Persistent keys are
* preserved until the application explicitly destroys them or until an * preserved until the application explicitly destroys them or until an
* implementation-specific device management event occurs (for example, * integration-specific device management event occurs (for example,
* a factory reset). * a factory reset).
* *
* Persistent keys have a key identifier of type #psa_key_id_t. * Persistent keys have a key identifier of type #psa_key_id_t.
@ -134,10 +134,9 @@ typedef uint32_t psa_algorithm_t;
* *
* This specification defines two basic lifetime values: * This specification defines two basic lifetime values:
* - Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are volatile. * - Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are volatile.
* All implementations should support this lifetime. * This lifetime is always supported.
* - Keys with the lifetime #PSA_KEY_LIFETIME_PERSISTENT are persistent. * - Keys with the lifetime #PSA_KEY_LIFETIME_PERSISTENT are persistent.
* All implementations that have access to persistent storage with * This lifetime is always supported if persistent storage is available.
* appropriate security guarantees should support this lifetime.
*/ */
typedef uint32_t psa_key_lifetime_t; typedef uint32_t psa_key_lifetime_t;
@ -150,35 +149,21 @@ typedef uint32_t psa_key_lifetime_t;
* actually affect persistent keys at different levels is outside the * actually affect persistent keys at different levels is outside the
* scope of the PSA Cryptography specification. * scope of the PSA Cryptography specification.
* *
* This specification defines the following values of persistence levels: * The PSA Cryptography specification defines the following values of
* persistence levels:
* - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key. * - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key.
* A volatile key is automatically destroyed by the implementation when * A volatile key is automatically destroyed by the implementation when
* the application instance terminates. In particular, a volatile key * the application instance terminates. In particular, a volatile key
* is automatically destroyed on a power reset of the device. * is automatically destroyed on a power reset of the device.
* - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT: * - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT:
* persistent key with a default lifetime. * persistent key with a default lifetime.
* Implementations should support this value if they support persistent * - \c 2-254: currently not supported by Mbed TLS.
* keys at all.
* Applications should use this value if they have no specific needs that
* are only met by implementation-specific features.
* - \c 2-127: persistent key with a PSA-specified lifetime.
* The PSA Cryptography specification does not define the meaning of these
* values, but other PSA specifications may do so.
* - \c 128-254: persistent key with a vendor-specified lifetime.
* No PSA specification will define the meaning of these values, so
* implementations may choose the meaning freely.
* As a guideline, higher persistence levels should cause a key to survive
* more management events than lower levels.
* - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY: * - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY:
* read-only or write-once key. * read-only or write-once key.
* A key with this persistence level cannot be destroyed. * A key with this persistence level cannot be destroyed.
* Implementations that support such keys may either allow their creation * Mbed TLS does not currently offer a way to create such keys, but
* through the PSA Cryptography API, preferably only to applications with * integrations of Mbed TLS can use it for built-in keys that the
* the appropriate privilege, or only expose keys created through * application cannot modify (for example, a hardware unique key (HUK)).
* implementation-specific means such as a factory ROM engraving process.
* Note that keys that are read-only due to policy restrictions
* rather than due to physical limitations should not have this
* persistence levels.
* *
* \note Key persistence levels are 8-bit values. Key management * \note Key persistence levels are 8-bit values. Key management
* interfaces operate on lifetimes (type ::psa_key_lifetime_t) which * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which
@ -188,12 +173,12 @@ typedef uint8_t psa_key_persistence_t;
/** Encoding of key location indicators. /** Encoding of key location indicators.
* *
* If an implementation of this API can make calls to external * If an integration of Mbed TLS can make calls to external
* cryptoprocessors such as secure elements, the location of a key * cryptoprocessors such as secure elements, the location of a key
* indicates which secure element performs the operations on the key. * indicates which secure element performs the operations on the key.
* If an implementation offers multiple physical locations for persistent * Depending on the design of the driver for the secure element, the key
* storage, the location indicator reflects at which physical location * material may either be stored either in the secure element, or
* the key is stored. * in wrapped form alongside the key metadata in the primary local storage.
* *
* This specification defines the following values of location indicators: * This specification defines the following values of location indicators:
* - \c 0: primary local storage. * - \c 0: primary local storage.
@ -201,15 +186,15 @@ typedef uint8_t psa_key_persistence_t;
* The primary local storage is typically the same storage area that * The primary local storage is typically the same storage area that
* contains the key metadata. * contains the key metadata.
* - \c 1: primary secure element. * - \c 1: primary secure element.
* Implementations should support this value if there is a secure element * Integrations of Mbed TLS should support this value if there is a secure
* attached to the operating environment. * element attached to the operating environment.
* As a guideline, secure elements may provide higher resistance against * As a guideline, secure elements may provide higher resistance against
* side channel and physical attacks than the primary local storage, but may * side channel and physical attacks than the primary local storage, but may
* have restrictions on supported key types, sizes, policies and operations * have restrictions on supported key types, sizes, policies and operations
* and may have different performance characteristics. * and may have different performance characteristics.
* - \c 2-0x7fffff: other locations defined by a PSA specification. * - \c 2-0x7fffff: other locations defined by a PSA specification.
* The PSA Cryptography API does not currently assign any meaning to these * The PSA Cryptography API does not currently assign any meaning to these
* locations, but future versions of this specification or other PSA * locations, but future versions of that specification or other PSA
* specifications may do so. * specifications may do so.
* - \c 0x800000-0xffffff: vendor-defined locations. * - \c 0x800000-0xffffff: vendor-defined locations.
* No PSA specification will assign a meaning to locations in this range. * No PSA specification will assign a meaning to locations in this range.

5
include/psa/crypto_values.h
View file

@ -1558,13 +1558,12 @@
* *
* A persistent key remains in storage until it is explicitly destroyed or * A persistent key remains in storage until it is explicitly destroyed or
* until the corresponding storage area is wiped. This specification does * until the corresponding storage area is wiped. This specification does
* not define any mechanism to wipe a storage area, but implementations may * not define any mechanism to wipe a storage area, but integrations may
* provide their own mechanism (for example to perform a factory reset, * provide their own mechanism (for example to perform a factory reset,
* to prepare for device refurbishment, or to uninstall an application). * to prepare for device refurbishment, or to uninstall an application).
* *
* This lifetime value is the default storage area for the calling * This lifetime value is the default storage area for the calling
* application. Implementations may offer other storage areas designated * application. Integrations of Mbed TLS may support other persistent lifetimes.
* by other lifetime values as implementation-specific extensions.
* See ::psa_key_lifetime_t for more information. * See ::psa_key_lifetime_t for more information.
*/ */
#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001) #define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001)