Merge pull request #59 from gilles-peskine-arm/psa-its-64_bit_internal_key_id

Support key file IDs encoding the key owner

include/mbedtls/config.h

@@ -1156,6 +1156,21 @@
  */
 //#define MBEDTLS_PSA_HAS_ITS_IO
 
+/* MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
+ *
+ * In PSA key storage, encode the owner of the key.
+ *
+ * This is only meaningful when building the library as part of a
+ * multi-client service. When you activate this option, you must provide
+ * an implementation of the type psa_key_owner_id_t and a translation
+ * from psa_key_file_id_t to file name in all the storage backends that
+ * you wish to support.
+ *
+ * Note that this option is meant for internal use only and may be removed
+ * without notice.
+ */
+//#define MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
+
 /**
  * \def MBEDTLS_MEMORY_DEBUG
  *

include/psa/crypto_platform.h

@@ -49,4 +49,53 @@
 /* Integral type representing a key handle. */
 typedef uint16_t psa_key_handle_t;
 
+/* This implementation distinguishes *application key identifiers*, which
+ * are the key identifiers specified by the application, from
+ * *key file identifiers*, which are the key identifiers that the library
+ * sees internally. The two types can be different if there is a remote
+ * call layer between the application and the library which supports
+ * multiple client applications that do not have access to each others'
+ * keys. The point of having different types is that the key file
+ * identifier may encode not only the key identifier specified by the
+ * application, but also the the identity of the application.
+ *
+ * Note that this is an internal concept of the library and the remote
+ * call layer. The application itself never sees anything other than
+ * #psa_app_key_id_t with its standard definition.
+ */
+
+/* The application key identifier is always what the application sees as
+ * #psa_key_id_t. */
+typedef uint32_t psa_app_key_id_t;
+
+#if defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
+
+#if defined(PSA_CRYPTO_SECURE)
+/* Building for the PSA Crypto service on a PSA platform. */
+/* A key owner is a PSA partition identifier. */
+typedef int32_t psa_key_owner_id_t;
+#endif
+
+typedef struct
+{
+    uint32_t key_id;
+    psa_key_owner_id_t owner;
+} psa_key_file_id_t;
+#define PSA_KEY_FILE_GET_KEY_ID( file_id ) ( ( file_id ).key_id )
+
+/* Since crypto.h is used as part of the PSA Cryptography API specification,
+ * it must use standard types for things like the argument of psa_open_key().
+ * If it wasn't for that constraint, psa_open_key() would take a
+ * `psa_key_file_id_t` argument. As a workaround, make `psa_key_id_t` an
+ * alias for `psa_key_file_id_t` when building for a multi-client service. */
+typedef psa_key_file_id_t psa_key_id_t;
+
+#else /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
+
+/* By default, a key file identifier is just the application key identifier. */
+typedef psa_app_key_id_t psa_key_file_id_t;
+#define PSA_KEY_FILE_GET_KEY_ID( id ) ( id )
+
+#endif /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
+
 #endif /* PSA_CRYPTO_PLATFORM_H */

include/psa/crypto_types.h

@@ -90,7 +90,14 @@ typedef uint32_t psa_key_lifetime_t;
 
 /** Encoding of identifiers of persistent keys.
  */
+/* 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
+ * client and encodes the client identity in the key id argument of functions
+ * such as psa_open_key(). In this build configuration, we define
+ * psa_key_id_t in crypto_platform.h instead of here. */
+#if !defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
 typedef uint32_t psa_key_id_t;
+#endif
 
 /**@}*/
 

library/psa_crypto_core.h

@@ -41,7 +41,7 @@ typedef struct
     psa_key_type_t type;
     psa_key_policy_t policy;
     psa_key_lifetime_t lifetime;
-    psa_key_id_t persistent_storage_id;
+    psa_key_file_id_t persistent_storage_id;
     unsigned allocated : 1;
     union
     {

library/psa_crypto_slot_management.c

@@ -168,6 +168,30 @@ exit:
     psa_free_persistent_key_data( key_data, key_data_length );
     return( status );
 }
+
+/** Check whether a key identifier is acceptable.
+ *
+ * For backward compatibility, key identifiers that were valid in a
+ * past released version must remain valid, unless a migration path
+ * is provided.
+ *
+ * \param file_id       The key identifier to check.
+ *
+ * \return              1 if \p file_id is acceptable, otherwise 0.
+ */
+static int psa_is_key_id_valid( psa_key_file_id_t file_id )
+{
+    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 )
+        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 );
+}
 #endif /* defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) */
 
 /** Declare a slot as persistent and load it from storage.
@@ -189,19 +213,13 @@ exit:
  * \retval #PSA_ERROR_STORAGE_FAILURE
  */
 static psa_status_t psa_internal_make_key_persistent( psa_key_handle_t handle,
-                                                      psa_key_id_t id )
+                                                      psa_key_file_id_t id )
 {
 #if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C)
     psa_key_slot_t *slot;
     psa_status_t status;
 
-    /* Reject id=0 because by general library conventions, 0 is an invalid
-     * value wherever possible. */
-    if( id == 0 )
-        return( PSA_ERROR_INVALID_ARGUMENT );
-    /* Reject high values because the file names are reserved for the
-     * library's internal use. */
-    if( id >= PSA_MAX_PERSISTENT_KEY_IDENTIFIER )
+    if( ! psa_is_key_id_valid( id ) )
         return( PSA_ERROR_INVALID_ARGUMENT );
 
     status = psa_get_key_slot( handle, &slot );
@@ -222,7 +240,7 @@ static psa_status_t psa_internal_make_key_persistent( psa_key_handle_t handle,
 }
 
 static psa_status_t persistent_key_setup( psa_key_lifetime_t lifetime,
-                                          psa_key_id_t id,
+                                          psa_key_file_id_t id,
                                           psa_key_handle_t *handle,
                                           psa_status_t wanted_load_status )
 {
@@ -247,14 +265,14 @@ static psa_status_t persistent_key_setup( psa_key_lifetime_t lifetime,
 }
 
 psa_status_t psa_open_key( psa_key_lifetime_t lifetime,
-                           psa_key_id_t id,
+                           psa_key_file_id_t id,
                            psa_key_handle_t *handle )
 {
     return( persistent_key_setup( lifetime, id, handle, PSA_SUCCESS ) );
 }
 
 psa_status_t psa_create_key( psa_key_lifetime_t lifetime,
-                             psa_key_id_t id,
+                             psa_key_file_id_t id,
                              psa_key_handle_t *handle )
 {
     psa_status_t status;

library/psa_crypto_storage.c

@@ -149,7 +149,7 @@ psa_status_t psa_parse_key_data_from_storage( const uint8_t *storage_data,
     return( PSA_SUCCESS );
 }
 
-psa_status_t psa_save_persistent_key( const psa_key_id_t key,
+psa_status_t psa_save_persistent_key( const psa_key_file_id_t key,
                                       const psa_key_type_t type,
                                       const psa_key_policy_t *policy,
                                       const uint8_t *data,
@@ -187,7 +187,7 @@ void psa_free_persistent_key_data( uint8_t *key_data, size_t key_data_length )
     mbedtls_free( key_data );
 }
 
-psa_status_t psa_load_persistent_key( psa_key_id_t key,
+psa_status_t psa_load_persistent_key( psa_key_file_id_t key,
                                       psa_key_type_t *type,
                                       psa_key_policy_t *policy,
                                       uint8_t **data,

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 0xffff0000
+#define PSA_MAX_PERSISTENT_KEY_IDENTIFIER 0xfffeffff
 
 /**
  * \brief Format key data and metadata and save to a location for given key
@@ -86,7 +86,7 @@ extern "C" {
  * \retval PSA_ERROR_STORAGE_FAILURE
  * \retval PSA_ERROR_ALREADY_EXISTS
  */
-psa_status_t psa_save_persistent_key( const psa_key_id_t key,
+psa_status_t psa_save_persistent_key( const psa_key_file_id_t key,
                                       const psa_key_type_t type,
                                       const psa_key_policy_t *policy,
                                       const uint8_t *data,
@@ -117,7 +117,7 @@ psa_status_t psa_save_persistent_key( const psa_key_id_t key,
  * \retval PSA_ERROR_STORAGE_FAILURE
  * \retval PSA_ERROR_DOES_NOT_EXIST
  */
-psa_status_t psa_load_persistent_key( psa_key_id_t key,
+psa_status_t psa_load_persistent_key( psa_key_file_id_t key,
                                       psa_key_type_t *type,
                                       psa_key_policy_t *policy,
                                       uint8_t **data,
@@ -134,7 +134,7 @@ psa_status_t psa_load_persistent_key( psa_key_id_t key,
  *         or the key did not exist.
  * \retval PSA_ERROR_STORAGE_FAILURE
  */
-psa_status_t psa_destroy_persistent_key( const psa_key_id_t key );
+psa_status_t psa_destroy_persistent_key( const psa_key_file_id_t key );
 
 /**
  * \brief Free the temporary buffer allocated by psa_load_persistent_key().

library/psa_crypto_storage_backend.h

@@ -56,7 +56,7 @@ extern "C" {
  * \retval PSA_ERROR_STORAGE_FAILURE
  * \retval PSA_ERROR_DOES_NOT_EXIST
  */
-psa_status_t psa_crypto_storage_load( const psa_key_id_t key, uint8_t *data,
+psa_status_t psa_crypto_storage_load( const psa_key_file_id_t key, uint8_t *data,
                                       size_t data_size );
 
 /**
@@ -75,7 +75,7 @@ psa_status_t psa_crypto_storage_load( const psa_key_id_t key, uint8_t *data,
  * \retval PSA_ERROR_STORAGE_FAILURE
  * \retval PSA_ERROR_ALREADY_EXISTS
  */
-psa_status_t psa_crypto_storage_store( const psa_key_id_t key,
+psa_status_t psa_crypto_storage_store( const psa_key_file_id_t key,
                                        const uint8_t *data,
                                        size_t data_length );
 
@@ -92,7 +92,7 @@ psa_status_t psa_crypto_storage_store( const psa_key_id_t key,
  * \retval 1
  *         Persistent data present for slot number
  */
-int psa_is_key_present_in_storage( const psa_key_id_t key );
+int psa_is_key_present_in_storage( const psa_key_file_id_t key );
 
 /**
  * \brief Get data length for given key slot number.
@@ -104,7 +104,7 @@ int psa_is_key_present_in_storage( const psa_key_id_t key );
  * \retval PSA_SUCCESS
  * \retval PSA_ERROR_STORAGE_FAILURE
  */
-psa_status_t psa_crypto_storage_get_data_length( const psa_key_id_t key,
+psa_status_t psa_crypto_storage_get_data_length( const psa_key_file_id_t key,
                                                  size_t *data_length );
 
 

library/psa_crypto_storage_file.c

@@ -49,7 +49,7 @@
 
 enum { MAX_LOCATION_LEN = sizeof(CRYPTO_STORAGE_FILE_LOCATION) + 40 };
 
-static void key_id_to_location( const psa_key_id_t key,
+static void key_id_to_location( const psa_key_file_id_t key,
                                 char *location,
                                 size_t location_size )
 {
@@ -58,7 +58,7 @@ static void key_id_to_location( const psa_key_id_t key,
                       (unsigned long) key );
 }
 
-psa_status_t psa_crypto_storage_load( const psa_key_id_t key, uint8_t *data,
+psa_status_t psa_crypto_storage_load( const psa_key_file_id_t key, uint8_t *data,
                                       size_t data_size )
 {
     psa_status_t status = PSA_SUCCESS;
@@ -83,7 +83,7 @@ exit:
     return( status );
 }
 
-int psa_is_key_present_in_storage( const psa_key_id_t key )
+int psa_is_key_present_in_storage( const psa_key_file_id_t key )
 {
     char slot_location[MAX_LOCATION_LEN];
     FILE *file;
@@ -101,7 +101,7 @@ int psa_is_key_present_in_storage( const psa_key_id_t key )
     return( 1 );
 }
 
-psa_status_t psa_crypto_storage_store( const psa_key_id_t key,
+psa_status_t psa_crypto_storage_store( const psa_key_file_id_t key,
                                        const uint8_t *data,
                                        size_t data_length )
 {
@@ -156,7 +156,7 @@ exit:
     return( status );
 }
 
-psa_status_t psa_destroy_persistent_key( const psa_key_id_t key )
+psa_status_t psa_destroy_persistent_key( const psa_key_file_id_t key )
 {
     FILE *file;
     char slot_location[MAX_LOCATION_LEN];
@@ -175,7 +175,7 @@ psa_status_t psa_destroy_persistent_key( const psa_key_id_t key )
     return( PSA_SUCCESS );
 }
 
-psa_status_t psa_crypto_storage_get_data_length( const psa_key_id_t key,
+psa_status_t psa_crypto_storage_get_data_length( const psa_key_file_id_t key,
                                                  size_t *data_length )
 {
     psa_status_t status = PSA_SUCCESS;

library/psa_crypto_storage_its.c

@@ -37,12 +37,31 @@
 #include "mbedtls/platform.h"
 #endif
 
-static psa_storage_uid_t psa_its_identifier_of_slot( psa_key_id_t key )
+/* Determine a file name (ITS file identifier) for the given key file
+ * identifier. The file name must be distinct from any file that is used
+ * for a purpose other than storing a key. Currently, the only such file
+ * is the random seed file whose name is PSA_CRYPTO_ITS_RANDOM_SEED_UID
+ * and whose value is 0xFFFFFF52. */
+static psa_storage_uid_t psa_its_identifier_of_slot( psa_key_file_id_t file_id )
 {
-    return( key );
+#if defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER) && \
+    defined(PSA_CRYPTO_SECURE)
+    /* Encode the owner in the upper 32 bits. This means that if
+     * owner values are nonzero (as they are on a PSA platform),
+     * no key file will ever have a value less than 0x100000000, so
+     * the whole range 0..0xffffffff is available for non-key files. */
+    uint32_t unsigned_owner = (uint32_t) file_id.owner;
+    return( (uint64_t) unsigned_owner << 32 | file_id.key_id );
+#else
+    /* Use the key id directly as a file name.
+     * psa_is_key_file_id_valid() in psa_crypto_slot_management.c
+     * is responsible for ensuring that key identifiers do not have a
+     * value that is reserved for non-key files. */
+    return( file_id );
+#endif
 }
 
-psa_status_t psa_crypto_storage_load( const psa_key_id_t key, uint8_t *data,
+psa_status_t psa_crypto_storage_load( const psa_key_file_id_t key, uint8_t *data,
                                       size_t data_size )
 {
     psa_status_t status;
@@ -58,7 +77,7 @@ psa_status_t psa_crypto_storage_load( const psa_key_id_t key, uint8_t *data,
     return( status );
 }
 
-int psa_is_key_present_in_storage( const psa_key_id_t key )
+int psa_is_key_present_in_storage( const psa_key_file_id_t key )
 {
     psa_status_t ret;
     psa_storage_uid_t data_identifier = psa_its_identifier_of_slot( key );
@@ -71,7 +90,7 @@ int psa_is_key_present_in_storage( const psa_key_id_t key )
     return( 1 );
 }
 
-psa_status_t psa_crypto_storage_store( const psa_key_id_t key,
+psa_status_t psa_crypto_storage_store( const psa_key_file_id_t key,
                                        const uint8_t *data,
                                        size_t data_length )
 {
@@ -106,7 +125,7 @@ exit:
     return( status );
 }
 
-psa_status_t psa_destroy_persistent_key( const psa_key_id_t key )
+psa_status_t psa_destroy_persistent_key( const psa_key_file_id_t key )
 {
     psa_status_t ret;
     psa_storage_uid_t data_identifier = psa_its_identifier_of_slot( key );
@@ -126,7 +145,7 @@ psa_status_t psa_destroy_persistent_key( const psa_key_id_t key )
     return( PSA_SUCCESS );
 }
 
-psa_status_t psa_crypto_storage_get_data_length( const psa_key_id_t key,
+psa_status_t psa_crypto_storage_get_data_length( const psa_key_file_id_t key,
                                                  size_t *data_length )
 {
     psa_status_t status;

library/version_features.c

@@ -411,6 +411,9 @@ static const char *features[] = {
 #if defined(MBEDTLS_PSA_HAS_ITS_IO)
     "MBEDTLS_PSA_HAS_ITS_IO",
 #endif /* MBEDTLS_PSA_HAS_ITS_IO */
+#if defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
+    "MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER",
+#endif /* MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
 #if defined(MBEDTLS_MEMORY_DEBUG)
     "MBEDTLS_MEMORY_DEBUG",
 #endif /* MBEDTLS_MEMORY_DEBUG */

scripts/config.pl

@@ -100,6 +100,7 @@ MBEDTLS_NO_UDBL_DIVISION
 MBEDTLS_NO_64BIT_MULTIPLICATION
 MBEDTLS_PSA_CRYPTO_SPM
 MBEDTLS_PSA_HAS_ITS_IO
+MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
 MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C
 MBEDTLS_USE_PSA_CRYPTO
 _ALT\s*$