Define some structure for lifetime values

include/psa/crypto_types.h

@@ -108,18 +108,117 @@ typedef uint32_t psa_algorithm_t;
  * The lifetime of a key indicates where it is stored and what system actions
  * may create and destroy it.
  *
- * Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are automatically
- * destroyed when the application terminates or on a power reset.
+ * Lifetime values have the following structure:
+ * - Bits 0-7 (#PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)):
+ *   persistence level. This value indicates what device management
+ *   actions can cause it to be destroyed. In particular, it indicates
+ *   whether the key is _volatile_ or _persistent_.
+ *   See ::psa_key_lifetime_persistence_t for more information.
+ * - Bits 8-31 (#PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)):
+ *   location indicator. This value indicates where the key is stored
+ *   and where operations on the key are performed.
+ *   See ::psa_key_lifetime_location_t for more information.
+ *
+ * Volatile keys are automatically destroyed when the application instance
+ * terminates or on a power reset of the device. Persistent keys are
+ * preserved until the application explicitly destroys them or until an
+ * implementation-specific device management event occurs (for example,
+ * a factory reset).
  *
- * Keys with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE are said
- * to be _persistent_.
- * Persistent keys are preserved if the application or the system restarts.
  * Persistent keys have a key identifier of type #psa_key_id_t.
+ * This identifier remains valid throughout the lifetime of the key,
+ * even if the application instance that created the key terminates.
  * The application can call psa_open_key() to open a persistent key that
  * it created previously.
+ *
+ * This specification defines two basic lifetime values:
+ * - Keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE are volatile.
+ *   All implementations should support this lifetime.
+ * - Keys with the lifetime #PSA_KEY_LIFETIME_PERSISTENT are persistent.
+ *   All implementations that have access to persistent storage with
+ *   appropriate security guarantees should support this lifetime.
  */
 typedef uint32_t psa_key_lifetime_t;
 
+/** Encoding of key persistence levels.
+ *
+ * What distinguishes different persistence levels is what device management
+ * events may cause keys to be destroyed. _Volatile_ keys are destroyed
+ * by a power reset. Persistent keys may be destroyed by events such as
+ * a transfer of ownership or a factory reset. What management events
+ * actually affect persistent keys at different levels is outside the
+ * scope of the PSA Cryptography specification.
+ *
+ * This specification defines the following values of persistence levels:
+ * - \c 0 = #PSA_KEY_LIFETIME_PERSISTENCE_VOLATILE: volatile key.
+ *   A volatile key is automatically destroyed by the implementation when
+ *   the application instance terminates. In particular, a volatile key
+ *   is automatically destroyed on a power reset of the device.
+ * - \c 1 = #PSA_KEY_LIFETIME_PERSISTENCE_PRIMARY:
+ *   persistent key with a default lifetime.
+ *   Implementations should support this value if they support persistent
+ *   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_LIFETIME_PERSISTENCE_READ_ONLY:
+ *   read-only or write-once key.
+ *   A key with this persistence level cannot be destroyed.
+ *   Implementations that support such keys may either allow their creation
+ *   through the PSA Cryptography API, preferably only to applications with
+ *   the appropriate privilege, or only expose keys created through
+ *   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
+ *       interfaces operate on lifetimes (type ::psa_key_lifetime_t) which
+ *       encode the persistence as the lower 8 bits of a 32-bit value.
+ */
+typedef uint8_t psa_key_lifetime_persistence_t;
+
+/** Encoding of key location indicators.
+ *
+ * If an implementation of this API can make calls to external
+ * cryptoprocessors such as secure elements, the location of a key
+ * indicates which secure element performs the operations on the key.
+ * If an implementation offers multiple physical locations for persistent
+ * storage, the location indicator reflects at which physical location
+ * the key is stored.
+ *
+ * This specification defines the following values of location indicators:
+ * - \c 0: default location.
+ *   All implementations should support this value.
+ *   The default location typically indicates that the key material is
+ *   used and stored within the same security boundary as the key metadata.
+ * - \c 1: primary secure element.
+ *   Implementations should support this value if there is a secure element
+ *   attached to the operating environment.
+ *   As a guideline, secure elements may provide higher resistance against
+ *   side channel and physical attacks than the default location, but may
+ *   have restrictions on supported key types, sizes, policies and operations
+ *   and may have different performance characteristics.
+ * - \c 2-0x7fffff: other locations defined by a PSA specification.
+ *   The PSA Cryptography does not currently assign any meaning to these
+ *   locations, but future versions of this specification or other PSA
+ *   specifications may do so.
+ * - \c 0x800000-0xffffff: vendor-defined locations.
+ *   No PSA specification will assign a meaning to locations in this range.
+ *
+ * \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.
+ */
+typedef uint32_t psa_key_lifetime_location_t;
+
 /** Encoding of identifiers of persistent keys.
  *
  * - Applications may freely choose key identifiers in the range

include/psa/crypto_values.h

@@ -1539,8 +1539,16 @@
  * @{
  */
 
-/** A volatile key only exists as long as the handle to it is not closed.
+/** The default lifetime for volatile keys.
+ *
+ * A volatile key only exists as long as the handle to it is not closed.
  * The key material is guaranteed to be erased on a power reset.
+ *
+ * A key with this lifetime is typically stored in the RAM area of the
+ * PSA Crypto subsystem. However this is an implementation choice.
+ * If an implementation stores data about the key in a non-volatile memory,
+ * it must release all the resources associated with the key and erase the
+ * key material if the calling application terminates.
  */
 #define PSA_KEY_LIFETIME_VOLATILE               ((psa_key_lifetime_t)0x00000000)
 
@@ -1555,9 +1563,43 @@
  * This lifetime value is the default storage area for the calling
  * application. Implementations may offer other storage areas designated
  * by other lifetime values as implementation-specific extensions.
+ * See ::psa_key_lifetime_location_t for more information.
  */
 #define PSA_KEY_LIFETIME_PERSISTENT             ((psa_key_lifetime_t)0x00000001)
 
+#define PSA_KEY_LIFETIME_PERSISTENCE_VOLATILE ((psa_key_lifetime_persistence_t)0x00)
+#define PSA_KEY_LIFETIME_PERSISTENCE_PRIMARY ((psa_key_lifetime_persistence_t)0x01)
+#define PSA_KEY_LIFETIME_PERSISTENCE_READ_ONLY ((psa_key_lifetime_persistence_t)0xff)
+
+#define PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime)      \
+    ((psa_key_lifetime_persistence_t)((lifetime) & 0x000000ff)
+
+#define PSA_KEY_LIFETIME_GET_LOCATION(lifetime)      \
+    ((psa_key_lifetime_location_t)((lifetime) >> 8)
+
+/** Whether a key lifetime indicates that the key is volatile.
+ *
+ * A volatile key is automatically destroyed by the implementation when
+ * the application instance terminates. In particular, a volatile key
+ * is automatically destroyed on a power reset of the device.
+ *
+ * A key that is not volatile is persistent. Persistent keys are
+ * preserved until the application explicitly destroys them or until an
+ * implementation-specific device management event occurs (for example,
+ * a factory reset).
+ *
+ * \param lifetime      The lifetime value to query (value of type
+ *                      ::psa_key_lifetime_t).
+ *
+ * \return \c 1 if the key is volatile, otherwise \c 0.
+ */
+#define PSA_KEY_LIFETIME_IS_VOLATILE(lifetime)  \
+    (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \
+     PSA_KEY_LIFETIME_PERSISTENCE_VOLATILE)
+
+#define PSA_KEY_LIFETIME_LOCATION_BUILT_IN       ((psa_key_lifetime_location_t)0x000000)
+#define PSA_KEY_LIFETIME_LOCATION_VENDOR_FLAG    ((psa_key_lifetime_location_t)0x800000)
+
 /** The minimum value for a key identifier chosen by the application.
  */
 #define PSA_KEY_ID_USER_MIN                     ((psa_app_key_id_t)0x00000001)