Merge pull request #264 from adrianlshaw/adrianlshaw/116

Rename psa_generator_import_key

Author: gilles-peskine-arm

docs/getting_started.md

@@ -335,7 +335,7 @@ Deriving a new AES-CTR 128-bit encryption key into a given key slot using HKDF w
 1. Set up the generator using the `psa_key_derivation` function providing a key slot containing a key that can be used for key derivation and a salt and label (Note: salt and label are optional).
 1. Initiate a key policy to for the derived key by calling `psa_key_policy_set_usage()` with `PSA_KEY_USAGE_ENCRYPT` parameter and the algorithm `PSA_ALG_CTR`.
 1. Set the key policy to the derived key slot.
-1. Import a key from generator into the desired key slot using (`psa_generator_import_key`).
+1. Import a key from generator into the desired key slot using (`psa_generate_derived_key`).
 1. Clean up generator.
 
 At this point the derived key slot holds a new 128-bit AES-CTR encryption key derived from the key, salt and label provided:
@@ -378,7 +378,7 @@ At this point the derived key slot holds a new 128-bit AES-CTR encryption key de
 
     psa_set_key_policy(derived_key, &policy);
 
-    psa_generator_import_key(derived_key, PSA_KEY_TYPE_AES, derived_bits, &generator);
+    psa_generate_derived_key(derived_key, PSA_KEY_TYPE_AES, derived_bits, &generator);
 
     /* Clean up generator and key */
     psa_generator_abort(&generator);
@@ -494,7 +494,7 @@ Prerequisites to using key generation and export APIs:
 
 Generate a piece of random 128-bit AES data:
 1. Set the key policy for key generation by calling `psa_key_policy_set_usage()` with the `PSA_KEY_USAGE_EXPORT` parameter and the algorithm `PSA_ALG_GCM`.
-1. Generate a random AES key by calling `psa_generate_key()`.
+1. Generate a random AES key by calling `psa_generate_random_key()`.
 1. Export the generated key by calling `psa_export_key()`:
 ```C
     int slot = 1;
@@ -510,7 +510,7 @@ Generate a piece of random 128-bit AES data:
     psa_set_key_policy(slot, &policy);
 
     /* Generate a key */
-    psa_generate_key(slot, PSA_KEY_TYPE_AES, bits);
+    psa_generate_random_key(slot, PSA_KEY_TYPE_AES, bits);
 
     psa_export_key(slot, exported, exported_size, &exported_length)
 

include/psa/crypto.h

@@ -179,11 +179,11 @@ psa_status_t psa_crypto_init(void);
  * -# Set the key type with psa_set_key_type(). If the key type requires
  *    domain parameters, call psa_set_key_domain_parameters() instead.
  *    Skip this step if copying an existing key with psa_copy_key().
- * -# When generating a random key with psa_generate_key() or deriving a key
- *    with psa_generator_import_key(), set the desired key size with
+ * -# When generating a random key with psa_generate_random_key() or deriving a key
+ *    with psa_generate_derived_key(), set the desired key size with
  *    psa_set_key_bits().
- * -# Call a key creation function: psa_import_key(), psa_generate_key(),
- *    psa_generator_import_key() or psa_copy_key(). This function reads
+ * -# Call a key creation function: psa_import_key(), psa_generate_random_key(),
+ *    psa_generate_derived_key() or psa_copy_key(). This function reads
  *    the attribute structure, creates a key with these attributes, and
  *    outputs a handle to the newly created key.
  * -# The attribute structure is now no longer necessary. If you called
@@ -208,8 +208,8 @@ typedef struct psa_key_attributes_s psa_key_attributes_t;
  * This function does not access storage, it merely fills the attribute
  * structure with given values. The persistent key will be written to
  * storage when the attribute structure is passed to a key creation
- * function such as psa_import_key(), psa_generate_key(),
- * psa_generator_import_key() or psa_copy_key().
+ * function such as psa_import_key(), psa_generate_random_key(),
+ * psa_generate_derived_key() or psa_copy_key().
  *
  * This function overwrites any identifier and lifetime values
  * previously set in \p attributes.
@@ -3087,7 +3087,7 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_generator_import_key(const psa_key_attributes_t *attributes,
+psa_status_t psa_generate_derived_key(const psa_key_attributes_t *attributes,
                                       psa_key_handle_t *handle,
                                       psa_crypto_generator_t *generator);
 
@@ -3148,7 +3148,7 @@ psa_status_t psa_generator_abort(psa_crypto_generator_t *generator);
  *   or after providing inputs. For some algorithms, this step is mandatory
  *   because the output depends on the maximum capacity.
  * - Generate output with psa_generator_read() or
- *   psa_generator_import_key(). Successive calls to these functions
+ *   psa_generate_derived_key(). Successive calls to these functions
  *   use successive output bytes from the generator.
  * - Clean up the generator object with psa_generator_abort().
  *
@@ -3385,7 +3385,7 @@ psa_status_t psa_key_agreement_raw_shared_secret(psa_algorithm_t alg,
  *          and MUST NOT use the content of the output buffer if the return
  *          status is not #PSA_SUCCESS.
  *
- * \note    To generate a key, use psa_generate_key() instead.
+ * \note    To generate a key, use psa_generate_random_key() instead.
  *
  * \param[out] output       Output buffer for the generated data.
  * \param output_size       Number of bytes to generate and output.
@@ -3447,7 +3447,7 @@ psa_status_t psa_generate_random(uint8_t *output,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
+psa_status_t psa_generate_random_key(const psa_key_attributes_t *attributes,
                               psa_key_handle_t *handle);
 
 /**@}*/

include/psa/crypto_extra.h

@@ -430,12 +430,12 @@ psa_status_t psa_copy_key_to_handle(psa_key_handle_t source_handle,
                           psa_key_handle_t target_handle,
                           const psa_key_policy_t *constraint);
 
-psa_status_t psa_generator_import_key_to_handle(psa_key_handle_t handle,
+psa_status_t psa_generate_derived_key_to_handle(psa_key_handle_t handle,
                                       psa_key_type_t type,
                                       size_t bits,
                                       psa_crypto_generator_t *generator);
 
-psa_status_t psa_generate_key_to_handle(psa_key_handle_t handle,
+psa_status_t psa_generate_random_key_to_handle(psa_key_handle_t handle,
                               psa_key_type_t type,
                               size_t bits,
                               const void *extra,

include/psa/crypto_se_driver.h

@@ -783,7 +783,7 @@ typedef psa_status_t (*psa_drv_se_export_key_t)(psa_key_slot_number_t key,
  * \param[in] extra         Extra parameters for key generation. The
  *                          interpretation of this parameter should match the
  *                          interpretation in the `extra` parameter is the
- *                          `psa_generate_key` function
+ *                          `psa_generate_random_key` function
  * \param[in] extra_size    The size in bytes of the \p extra buffer
  * \param[out] p_pubkey_out The buffer where the public key information will
  *                          be placed

library/psa_crypto.c

@@ -4313,7 +4313,7 @@ static void psa_des_set_key_parity( uint8_t *data, size_t data_size )
 }
 #endif /* MBEDTLS_DES_C */
 
-static psa_status_t psa_generator_import_key_internal(
+static psa_status_t psa_generate_derived_key_internal(
     psa_key_slot_t *slot,
     size_t bits,
     psa_crypto_generator_t *generator )
@@ -4344,7 +4344,7 @@ static psa_status_t psa_generator_import_key_internal(
     return( status );
 }
 
-psa_status_t psa_generator_import_key( const psa_key_attributes_t *attributes,
+psa_status_t psa_generate_derived_key( const psa_key_attributes_t *attributes,
                                        psa_key_handle_t *handle,
                                        psa_crypto_generator_t *generator )
 {
@@ -4353,7 +4353,7 @@ psa_status_t psa_generator_import_key( const psa_key_attributes_t *attributes,
     status = psa_start_key_creation( attributes, handle, &slot );
     if( status == PSA_SUCCESS )
     {
-        status = psa_generator_import_key_internal( slot,
+        status = psa_generate_derived_key_internal( slot,
                                                     attributes->bits,
                                                     generator );
     }
@@ -4367,7 +4367,7 @@ psa_status_t psa_generator_import_key( const psa_key_attributes_t *attributes,
     return( status );
 }
 
-psa_status_t psa_generator_import_key_to_handle( psa_key_handle_t handle,
+psa_status_t psa_generate_derived_key_to_handle( psa_key_handle_t handle,
                                        psa_key_type_t type,
                                        size_t bits,
                                        psa_crypto_generator_t *generator )
@@ -5148,7 +5148,7 @@ static psa_status_t psa_read_rsa_exponent( const uint8_t *domain_parameters,
 }
 #endif /* MBEDTLS_RSA_C && MBEDTLS_GENPRIME */
 
-static psa_status_t psa_generate_key_internal(
+static psa_status_t psa_generate_random_key_internal(
     psa_key_slot_t *slot, size_t bits,
     const uint8_t *domain_parameters, size_t domain_parameters_size )
 {
@@ -5254,7 +5254,7 @@ static psa_status_t psa_generate_key_internal(
     return( PSA_SUCCESS );
 }
 
-psa_status_t psa_generate_key_to_handle( psa_key_handle_t handle,
+psa_status_t psa_generate_random_key_to_handle( psa_key_handle_t handle,
                                psa_key_type_t type,
                                size_t bits,
                                const void *extra,
@@ -5274,7 +5274,7 @@ psa_status_t psa_generate_key_to_handle( psa_key_handle_t handle,
         return( status );
 
     slot->type = type;
-    status = psa_generate_key_internal( slot, bits, extra, extra_size );
+    status = psa_generate_random_key_internal( slot, bits, extra, extra_size );
     if( status != PSA_SUCCESS )
         slot->type = 0;
 
@@ -5288,15 +5288,15 @@ psa_status_t psa_generate_key_to_handle( psa_key_handle_t handle,
     return( status );
 }
 
-psa_status_t psa_generate_key( const psa_key_attributes_t *attributes,
+psa_status_t psa_generate_random_key( const psa_key_attributes_t *attributes,
                                psa_key_handle_t *handle )
 {
     psa_status_t status;
     psa_key_slot_t *slot = NULL;
     status = psa_start_key_creation( attributes, handle, &slot );
     if( status == PSA_SUCCESS )
     {
-        status = psa_generate_key_internal(
+        status = psa_generate_random_key_internal(
             slot, attributes->bits,
             attributes->domain_parameters, attributes->domain_parameters_size );
     }

library/ssl_cli.c

@@ -3148,7 +3148,7 @@ static int ssl_write_client_key_exchange( mbedtls_ssl_context *ssl )
             return( MBEDTLS_ERR_SSL_HW_ACCEL_FAILED );
 
         /* Generate ECDH private key. */
-        status = psa_generate_key_to_handle( handshake->ecdh_psa_privkey,
+        status = psa_generate_random_key_to_handle( handshake->ecdh_psa_privkey,
                           PSA_KEY_TYPE_ECC_KEYPAIR( handshake->ecdh_psa_curve ),
                           MBEDTLS_PSA_ECC_KEY_BITS_OF_CURVE( handshake->ecdh_psa_curve ),
                           NULL, 0 );

programs/psa/crypto_examples.c

@@ -164,7 +164,7 @@ cipher_example_encrypt_decrypt_aes_cbc_nopad_1_block( void )
     psa_set_key_type( &attributes, PSA_KEY_TYPE_AES );
     psa_set_key_bits( &attributes, key_bits );
 
-    status = psa_generate_key( &attributes, &key_handle );
+    status = psa_generate_random_key( &attributes, &key_handle );
     ASSERT_STATUS( status, PSA_SUCCESS );
 
     status = cipher_encrypt( key_handle, alg, iv, sizeof( iv ),
@@ -215,7 +215,7 @@ static psa_status_t cipher_example_encrypt_decrypt_aes_cbc_pkcs7_multi( void )
     psa_set_key_type( &attributes, PSA_KEY_TYPE_AES );
     psa_set_key_bits( &attributes, key_bits );
 
-    status = psa_generate_key( &attributes, &key_handle );
+    status = psa_generate_random_key( &attributes, &key_handle );
     ASSERT_STATUS( status, PSA_SUCCESS );
 
     status = cipher_encrypt( key_handle, alg, iv, sizeof( iv ),
@@ -262,7 +262,7 @@ static psa_status_t cipher_example_encrypt_decrypt_aes_ctr_multi( void )
     psa_set_key_type( &attributes, PSA_KEY_TYPE_AES );
     psa_set_key_bits( &attributes, key_bits );
 
-    status = psa_generate_key( &attributes, &key_handle );
+    status = psa_generate_random_key( &attributes, &key_handle );
     ASSERT_STATUS( status, PSA_SUCCESS );
 
     status = cipher_encrypt( key_handle, alg, iv, sizeof( iv ),

programs/psa/key_ladder_demo.c

@@ -208,7 +208,7 @@ static psa_status_t generate( const char *key_file_name )
     psa_set_key_type( &attributes, PSA_KEY_TYPE_DERIVE );
     psa_set_key_bits( &attributes, PSA_BYTES_TO_BITS( KEY_SIZE_BYTES ) );
 
-    PSA_CHECK( psa_generate_key( &attributes, &key_handle ) );
+    PSA_CHECK( psa_generate_random_key( &attributes, &key_handle ) );
 
     PSA_CHECK( save_key( key_handle, key_file_name ) );
 
@@ -306,7 +306,7 @@ static psa_status_t derive_key_ladder( const char *ladder[],
         *key_handle = 0;
         /* Use the generator obtained from the parent key to create
          * the next intermediate key. */
-        PSA_CHECK( psa_generator_import_key( &attributes, key_handle,
+        PSA_CHECK( psa_generate_derived_key( &attributes, key_handle,
                                              &generator ) );
         PSA_CHECK( psa_generator_abort( &generator ) );
     }
@@ -343,7 +343,7 @@ static psa_status_t derive_wrapping_key( psa_key_usage_t usage,
                    WRAPPING_KEY_SALT, WRAPPING_KEY_SALT_LENGTH,
                    NULL, 0,
                    PSA_BITS_TO_BYTES( WRAPPING_KEY_BITS ) ) );
-    PSA_CHECK( psa_generator_import_key( &attributes, wrapping_key_handle,
+    PSA_CHECK( psa_generate_derived_key( &attributes, wrapping_key_handle,
                                          &generator ) );
 
 exit:

tests/suites/test_suite_pk.function

@@ -97,7 +97,7 @@ psa_key_handle_t pk_psa_genkey( void )
         return( PK_PSA_INVALID_SLOT );
 
     /* generate key */
-    if( PSA_SUCCESS != psa_generate_key_to_handle( key, type, bits, NULL, 0 ) )
+    if( PSA_SUCCESS != psa_generate_random_key_to_handle( key, type, bits, NULL, 0 ) )
         return( PK_PSA_INVALID_SLOT );
 
     return( key );

tests/suites/test_suite_psa_crypto.function

@@ -4322,7 +4322,7 @@ void derive_key_exercise( int alg_arg,
     psa_set_key_algorithm( &attributes, derived_alg );
     psa_set_key_type( &attributes, derived_type );
     psa_set_key_bits( &attributes, derived_bits );
-    PSA_ASSERT( psa_generator_import_key( &attributes, &derived_handle,
+    PSA_ASSERT( psa_generate_derived_key( &attributes, &derived_handle,
                                           &generator ) );
 
     /* Test the key information */
@@ -4393,15 +4393,15 @@ void derive_key_export( int alg_arg,
     psa_set_key_algorithm( &derived_attributes, 0 );
     psa_set_key_type( &derived_attributes, PSA_KEY_TYPE_RAW_DATA );
     psa_set_key_bits( &derived_attributes, PSA_BYTES_TO_BITS( bytes1 ) );
-    PSA_ASSERT( psa_generator_import_key( &derived_attributes, &derived_handle,
+    PSA_ASSERT( psa_generate_derived_key( &derived_attributes, &derived_handle,
                                           &generator ) );
     PSA_ASSERT( psa_export_key( derived_handle,
                                 export_buffer, bytes1,
                                 &length ) );
     TEST_EQUAL( length, bytes1 );
     PSA_ASSERT( psa_destroy_key( derived_handle ) );
     psa_set_key_bits( &derived_attributes, PSA_BYTES_TO_BITS( bytes2 ) );
-    PSA_ASSERT( psa_generator_import_key( &derived_attributes, &derived_handle,
+    PSA_ASSERT( psa_generate_derived_key( &derived_attributes, &derived_handle,
                                           &generator ) );
     PSA_ASSERT( psa_export_key( derived_handle,
                                 export_buffer + bytes1, bytes2,
@@ -4695,7 +4695,7 @@ void generate_key( int type_arg,
     psa_set_key_bits( &attributes, bits );
 
     /* Generate a key */
-    TEST_EQUAL( psa_generate_key( &attributes, &handle ), expected_status );
+    TEST_EQUAL( psa_generate_random_key( &attributes, &handle ), expected_status );
     if( expected_status != PSA_SUCCESS )
         goto exit;
 
@@ -4755,7 +4755,7 @@ void generate_key_rsa( int bits_arg,
     psa_set_key_bits( &attributes, bits );
 
     /* Generate a key */
-    TEST_EQUAL( psa_generate_key( &attributes, &handle ), expected_status );
+    TEST_EQUAL( psa_generate_random_key( &attributes, &handle ), expected_status );
     if( expected_status != PSA_SUCCESS )
         goto exit;
 
@@ -4863,7 +4863,7 @@ void persistent_key_load_key_from_storage( data_t *data,
 
         case GENERATE_KEY:
             /* Generate a key */
-            PSA_ASSERT( psa_generate_key( &attributes, &handle ) );
+            PSA_ASSERT( psa_generate_random_key( &attributes, &handle ) );
             break;
 
         case DERIVE_KEY:
@@ -4885,7 +4885,7 @@ void persistent_key_load_key_from_storage( data_t *data,
                 PSA_ASSERT( psa_key_derivation_input_bytes(
                                 &generator, PSA_KDF_STEP_INFO,
                                 NULL, 0 ) );
-                PSA_ASSERT( psa_generator_import_key( &attributes, &handle,
+                PSA_ASSERT( psa_generate_derived_key( &attributes, &handle,
                                                       &generator ) );
                 PSA_ASSERT( psa_generator_abort( &generator ) );
                 PSA_ASSERT( psa_destroy_key( base_key ) );