Merge pull request #104 from gilles-peskine-arm/psa-global_key_id

Make key ids global and define their range

include/psa/crypto.h

@@ -512,9 +512,10 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
  *
  * Open a handle to a key which was previously created with psa_create_key().
  *
- * \param lifetime      The lifetime of the key. This designates a storage
- *                      area where the key material is stored. This must not
- *                      be #PSA_KEY_LIFETIME_VOLATILE.
+ * Implementations may provide additional keys that can be opened with
+ * psa_open_key(). Such keys have a key identifier in the vendor range,
+ * as documented in the description of #psa_key_id_t.
+ *
  * \param id            The persistent identifier of the key.
  * \param[out] handle   On success, a handle to a key slot which contains
  *                      the data and metadata loaded from the specified
@@ -526,19 +527,16 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
- * \retval #PSA_ERROR_INVALID_ARGUMENT
- *         \p id is invalid for the specified lifetime.
- * \retval #PSA_ERROR_NOT_SUPPORTED
- *         \p lifetime is not supported.
+ *         \p id is invalid.
  * \retval #PSA_ERROR_NOT_PERMITTED
  *         The specified key exists, but the application does not have the
  *         permission to access it. Note that this specification does not
  *         define any way to create such a key, but it may be possible
  *         through implementation-specific means.
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  */
-psa_status_t psa_open_key(psa_key_lifetime_t lifetime,
-                          psa_key_id_t id,
+psa_status_t psa_open_key(psa_key_id_t id,
                           psa_key_handle_t *handle);
 
 /** Close a key handle.

include/psa/crypto_types.h

@@ -85,10 +85,30 @@ typedef uint32_t psa_algorithm_t;
  */
 
 /** Encoding of key lifetimes.
+ *
+ * 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.
+ *
+ * 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.
+ * The application can call psa_open_key() to open a persistent key that
+ * it created previously.
  */
 typedef uint32_t psa_key_lifetime_t;
 
 /** Encoding of identifiers of persistent keys.
+ *
+ * - Applications may freely choose key identifiers in the range
+ *   #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX.
+ * - Implementations may define additional key identifiers in the range
+ *   #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.
  */
 /* Implementation-specific quirk: The Mbed Crypto library can be built as
  * part of a multi-client service that exposes the PSA Crypto API in each

include/psa/crypto_values.h

@@ -1488,6 +1488,19 @@
  */
 #define PSA_KEY_LIFETIME_PERSISTENT             ((psa_key_lifetime_t)0x00000001)
 
+/** The minimum value for a key identifier chosen by the application.
+ */
+#define PSA_KEY_ID_USER_MIN                     ((psa_key_id_t)0x00000001)
+/** The maximum value for a key identifier chosen by the application.
+ */
+#define PSA_KEY_ID_USER_MAX                     ((psa_key_id_t)0x3fffffff)
+/** The minimum value for a key identifier chosen by the implementation.
+ */
+#define PSA_KEY_ID_VENDOR_MIN                   ((psa_key_id_t)0x40000000)
+/** The maximum value for a key identifier chosen by the implementation.
+ */
+#define PSA_KEY_ID_VENDOR_MAX                   ((psa_key_id_t)0x7fffffff)
+
 /**@}*/
 
 /** \defgroup policy Key policies