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

Make key ids global and define their range

Author: Patater

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

library/psa_crypto.c

@@ -1425,7 +1425,7 @@ static psa_status_t psa_start_key_creation(
     if( attributes->lifetime != PSA_KEY_LIFETIME_VOLATILE )
     {
         status = psa_validate_persistent_key_parameters( attributes->lifetime,
-                                                         attributes->id );
+                                                         attributes->id, 1 );
         if( status != PSA_SUCCESS )
             return( status );
         slot->persistent_storage_id = attributes->id;

library/psa_crypto_slot_management.c

@@ -176,21 +176,23 @@ static psa_status_t psa_load_persistent_key_into_slot( psa_key_slot_t *p_slot )
  * is provided.
  *
  * \param file_id       The key identifier to check.
+ * \param vendor_ok     Nonzero to allow key ids in the vendor range.
+ *                      0 to allow only key ids in the application range.
  *
  * \return              1 if \p file_id is acceptable, otherwise 0.
  */
-static int psa_is_key_id_valid( psa_key_file_id_t file_id )
+static int psa_is_key_id_valid( psa_key_file_id_t file_id,
+                                int vendor_ok )
 {
     psa_app_key_id_t key_id = PSA_KEY_FILE_GET_KEY_ID( file_id );
-    /* Reject id=0 because by general library conventions, 0 is an invalid
-     * value wherever possible. */
-    if( key_id == 0 )
+    if( PSA_KEY_ID_USER_MIN <= key_id && key_id <= PSA_KEY_ID_USER_MAX )
+        return( 1 );
+    else if( vendor_ok &&
+             PSA_KEY_ID_VENDOR_MIN <= key_id &&
+             key_id <= PSA_KEY_ID_VENDOR_MAX )
+        return( 1 );
+    else
         return( 0 );
-    /* Reject high values because the file names are reserved for the
-     * library's internal use. */
-    if( key_id > PSA_MAX_PERSISTENT_KEY_IDENTIFIER )
-        return( 0 );
-    return( 1 );
 }
 
 /** Declare a slot as persistent and load it from storage.
@@ -231,32 +233,36 @@ static psa_status_t psa_internal_make_key_persistent( psa_key_handle_t handle,
 
 psa_status_t psa_validate_persistent_key_parameters(
     psa_key_lifetime_t lifetime,
-    psa_key_file_id_t id )
+    psa_key_file_id_t id,
+    int creating )
 {
     if( lifetime != PSA_KEY_LIFETIME_PERSISTENT )
         return( PSA_ERROR_INVALID_ARGUMENT );
 
 #if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C)
-    if( ! psa_is_key_id_valid( id ) )
+    if( ! psa_is_key_id_valid( id, ! creating ) )
         return( PSA_ERROR_INVALID_ARGUMENT );
     return( PSA_SUCCESS );
 
 #else /* MBEDTLS_PSA_CRYPTO_STORAGE_C */
     (void) id;
+    (void) creating;
     return( PSA_ERROR_NOT_SUPPORTED );
 #endif /* !MBEDTLS_PSA_CRYPTO_STORAGE_C */
 }
 
 static psa_status_t persistent_key_setup( psa_key_lifetime_t lifetime,
                                           psa_key_file_id_t id,
                                           psa_key_handle_t *handle,
-                                          psa_status_t wanted_load_status )
+                                          int creating )
 {
     psa_status_t status;
+    psa_status_t wanted_load_status =
+        ( creating ? PSA_ERROR_DOES_NOT_EXIST : PSA_SUCCESS );
 
     *handle = 0;
 
-    status = psa_validate_persistent_key_parameters( lifetime, id );
+    status = psa_validate_persistent_key_parameters( lifetime, id, creating );
     if( status != PSA_SUCCESS )
         return( status );
 
@@ -278,11 +284,10 @@ static psa_status_t persistent_key_setup( psa_key_lifetime_t lifetime,
 #endif /* !defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) */
 }
 
-psa_status_t psa_open_key( psa_key_lifetime_t lifetime,
-                           psa_key_file_id_t id,
-                           psa_key_handle_t *handle )
+psa_status_t psa_open_key( psa_key_file_id_t id, psa_key_handle_t *handle )
 {
-    return( persistent_key_setup( lifetime, id, handle, PSA_SUCCESS ) );
+    return( persistent_key_setup( PSA_KEY_LIFETIME_PERSISTENT,
+                                  id, handle, 0 ) );
 }
 
 psa_status_t psa_create_key( psa_key_lifetime_t lifetime,
@@ -291,8 +296,7 @@ psa_status_t psa_create_key( psa_key_lifetime_t lifetime,
 {
     psa_status_t status;
 
-    status = persistent_key_setup( lifetime, id, handle,
-                                   PSA_ERROR_DOES_NOT_EXIST );
+    status = persistent_key_setup( lifetime, id, handle, 1 );
     switch( status )
     {
         case PSA_SUCCESS: return( PSA_ERROR_ALREADY_EXISTS );

library/psa_crypto_slot_management.h

@@ -64,6 +64,8 @@ void psa_wipe_all_key_slots( void );
  *
  * \param lifetime      The lifetime to test.
  * \param id            The key id to test.
+ * \param creating      0 if attempting to open an existing key.
+ *                      Nonzero if attempting to create a key.
  *
  * \retval PSA_SUCCESS
  *         The given parameters are valid.
@@ -74,7 +76,8 @@ void psa_wipe_all_key_slots( void );
  */
 psa_status_t psa_validate_persistent_key_parameters(
     psa_key_lifetime_t lifetime,
-    psa_key_file_id_t id );
+    psa_key_file_id_t id,
+    int creating );
 
 
 #endif /* PSA_CRYPTO_SLOT_MANAGEMENT_H */

library/psa_crypto_storage.h

@@ -59,7 +59,7 @@ extern "C" {
  * This limitation will probably become moot when we implement client
  * separation for key storage.
  */
-#define PSA_MAX_PERSISTENT_KEY_IDENTIFIER 0xfffeffff
+#define PSA_MAX_PERSISTENT_KEY_IDENTIFIER PSA_KEY_ID_VENDOR_MAX
 
 /**
  * \brief Checks if persistent data is stored for the given key slot number

tests/suites/test_suite_psa_crypto.function

@@ -4942,8 +4942,7 @@ void persistent_key_load_key_from_storage( data_t *data,
     PSA_ASSERT( psa_crypto_init() );
 
     /* Check key slot still contains key data */
-    PSA_ASSERT( psa_open_key( PSA_KEY_LIFETIME_PERSISTENT, key_id,
-                              &handle ) );
+    PSA_ASSERT( psa_open_key( key_id, &handle ) );
     PSA_ASSERT( psa_get_key_attributes( handle, &attributes ) );
     TEST_EQUAL( psa_get_key_id( &attributes ), key_id );
     TEST_EQUAL( psa_get_key_lifetime( &attributes ),
@@ -4978,7 +4977,7 @@ exit:
         /* In case there was a test failure after creating the persistent key
          * but while it was not open, try to re-open the persistent key
          * to delete it. */
-        psa_open_key( PSA_KEY_LIFETIME_PERSISTENT, key_id, &handle );
+        psa_open_key( key_id, &handle );
     }
     psa_destroy_key( handle );
     mbedtls_psa_crypto_free();

tests/suites/test_suite_psa_crypto_persistent_key.function

@@ -133,8 +133,7 @@ void persistent_key_destroy( int key_id_arg, int restart,
         psa_close_key( handle );
         mbedtls_psa_crypto_free();
         PSA_ASSERT( psa_crypto_init() );
-        PSA_ASSERT( psa_open_key( PSA_KEY_LIFETIME_PERSISTENT, key_id,
-                                  &handle ) );
+        PSA_ASSERT( psa_open_key( key_id, &handle ) );
     }
     TEST_EQUAL( psa_is_key_present_in_storage( key_id ), 1 );
 
@@ -143,8 +142,7 @@ void persistent_key_destroy( int key_id_arg, int restart,
 
     /* Check key slot storage is removed */
     TEST_EQUAL( psa_is_key_present_in_storage( key_id ), 0 );
-    TEST_EQUAL( psa_open_key( PSA_KEY_LIFETIME_PERSISTENT, key_id, &handle ),
-                PSA_ERROR_DOES_NOT_EXIST );
+    TEST_EQUAL( psa_open_key( key_id, &handle ), PSA_ERROR_DOES_NOT_EXIST );
     TEST_EQUAL( handle, 0 );
 
     /* Shutdown and restart */
@@ -190,8 +188,7 @@ void persistent_key_import( int key_id_arg, int type_arg, data_t *data,
         psa_close_key( handle );
         mbedtls_psa_crypto_free();
         PSA_ASSERT( psa_crypto_init() );
-        PSA_ASSERT( psa_open_key( PSA_KEY_LIFETIME_PERSISTENT, key_id,
-                                  &handle ) );
+        PSA_ASSERT( psa_open_key( key_id, &handle ) );
     }
 
     psa_reset_key_attributes( &attributes );
@@ -240,8 +237,7 @@ void import_export_persistent_key( data_t *data, int type_arg,
         psa_close_key( handle );
         mbedtls_psa_crypto_free();
         PSA_ASSERT( psa_crypto_init() );
-        PSA_ASSERT( psa_open_key( PSA_KEY_LIFETIME_PERSISTENT, key_id,
-                                  &handle ) );
+        PSA_ASSERT( psa_open_key( key_id, &handle ) );
     }
 
     /* Test the key information */

tests/suites/test_suite_psa_crypto_slot_management.data

@@ -7,14 +7,23 @@ transient_slot_lifecycle:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789ab
 Transient slot, check after restart
 transient_slot_lifecycle:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_SHUTDOWN
 
-Persistent slot, check after closing
-persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:1:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_CLOSE
+Persistent slot, check after closing, id=min
+persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_ID_USER_MIN:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_CLOSE
 
-Persistent slot, check after destroying
-persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:1:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_DESTROY
+Persistent slot, check after destroying, id=min
+persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_ID_USER_MIN:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_DESTROY
 
-Persistent slot, check after restart
-persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:1:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_SHUTDOWN
+Persistent slot, check after restart, id=min
+persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_ID_USER_MIN:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_SHUTDOWN
+
+Persistent slot, check after closing, id=max
+persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_ID_USER_MAX:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_CLOSE
+
+Persistent slot, check after destroying, id=max
+persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_ID_USER_MAX:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_DESTROY
+
+Persistent slot, check after restart, id=max
+persistent_slot_lifecycle:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_ID_USER_MAX:0:0:PSA_KEY_TYPE_RAW_DATA:"0123456789abcdef0123456789abcdef":CLOSE_BY_SHUTDOWN
 
 Attempt to overwrite: close before
 create_existent:PSA_KEY_LIFETIME_PERSISTENT:1:CLOSE_BEFORE
@@ -27,21 +36,23 @@ create_existent:PSA_KEY_LIFETIME_PERSISTENT:1:KEEP_OPEN
 
 Open failure: invalid identifier (0)
 depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C
-open_fail:PSA_KEY_LIFETIME_PERSISTENT:0:PSA_ERROR_INVALID_ARGUMENT
+open_fail:0:PSA_ERROR_INVALID_ARGUMENT
 
 Open failure: invalid identifier (random seed UID)
 depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C
-open_fail:PSA_KEY_LIFETIME_PERSISTENT:PSA_CRYPTO_ITS_RANDOM_SEED_UID:PSA_ERROR_INVALID_ARGUMENT
+open_fail:PSA_CRYPTO_ITS_RANDOM_SEED_UID:PSA_ERROR_INVALID_ARGUMENT
 
-Open failure: non-existent identifier
+Open failure: invalid identifier (reserved range)
 depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C
-open_fail:PSA_KEY_LIFETIME_PERSISTENT:1:PSA_ERROR_DOES_NOT_EXIST
+open_fail:PSA_KEY_ID_VENDOR_MAX + 1:PSA_ERROR_INVALID_ARGUMENT
 
-Open failure: volatile lifetime
-open_fail:PSA_KEY_LIFETIME_VOLATILE:1:PSA_ERROR_INVALID_ARGUMENT
+Open failure: invalid identifier (implementation range)
+depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C
+open_fail:PSA_KEY_ID_USER_MAX + 1:PSA_ERROR_DOES_NOT_EXIST
 
-Open failure: invalid lifetime
-open_fail:0x7fffffff:0:PSA_ERROR_INVALID_ARGUMENT
+Open failure: non-existent identifier
+depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C
+open_fail:1:PSA_ERROR_DOES_NOT_EXIST
 
 Create failure: invalid lifetime
 create_fail:0x7fffffff:0:PSA_ERROR_INVALID_ARGUMENT
@@ -54,9 +65,17 @@ Create failure: invalid key id (random seed UID)
 depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C
 create_fail:PSA_KEY_LIFETIME_PERSISTENT:PSA_CRYPTO_ITS_RANDOM_SEED_UID:PSA_ERROR_INVALID_ARGUMENT
 
+Create failure: invalid key id (reserved range)
+depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C
+create_fail:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_ID_VENDOR_MAX + 1:PSA_ERROR_INVALID_ARGUMENT
+
+Create failure: invalid key id (implementation range)
+depends_on:MBEDTLS_PSA_CRYPTO_STORAGE_C
+create_fail:PSA_KEY_LIFETIME_PERSISTENT:PSA_KEY_ID_USER_MAX + 1:PSA_ERROR_INVALID_ARGUMENT
+
 Open not supported
 depends_on:!MBEDTLS_PSA_CRYPTO_STORAGE_C
-open_fail:PSA_KEY_LIFETIME_PERSISTENT:1:PSA_ERROR_NOT_SUPPORTED
+open_fail:1:PSA_ERROR_NOT_SUPPORTED
 
 Create not supported
 depends_on:!MBEDTLS_PSA_CRYPTO_STORAGE_C