diff --git a/docs/getting_started.md b/docs/getting_started.md index 84ed891ac..ec8cc08ce 100644 --- a/docs/getting_started.md +++ b/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) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index fff144cab..2e680b101 100644 --- a/include/psa/crypto.h +++ b/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); /**@}*/ diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index f2cf05150..216039c85 100644 --- a/include/psa/crypto_extra.h +++ b/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, diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h index 5fb7bc3ae..8c7ad6d00 100644 --- a/include/psa/crypto_se_driver.h +++ b/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 diff --git a/library/psa_crypto.c b/library/psa_crypto.c index 6e01997a4..9cf90ddaf 100644 --- a/library/psa_crypto.c +++ b/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 @@ exit: 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,7 +5288,7 @@ 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; @@ -5296,7 +5296,7 @@ psa_status_t psa_generate_key( const psa_key_attributes_t *attributes, 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 ); } diff --git a/library/ssl_cli.c b/library/ssl_cli.c index 65bc64cb7..81c69dd5f 100644 --- a/library/ssl_cli.c +++ b/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 ); diff --git a/programs/psa/crypto_examples.c b/programs/psa/crypto_examples.c index 1a81f45f8..922a30125 100644 --- a/programs/psa/crypto_examples.c +++ b/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 ), diff --git a/programs/psa/key_ladder_demo.c b/programs/psa/key_ladder_demo.c index 6d4c707ac..523668e13 100644 --- a/programs/psa/key_ladder_demo.c +++ b/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: diff --git a/tests/suites/test_suite_pk.function b/tests/suites/test_suite_pk.function index 7415b63a9..a23487b4c 100644 --- a/tests/suites/test_suite_pk.function +++ b/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 ); diff --git a/tests/suites/test_suite_psa_crypto.function b/tests/suites/test_suite_psa_crypto.function index c19439696..67c2c77f9 100644 --- a/tests/suites/test_suite_psa_crypto.function +++ b/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,7 +4393,7 @@ 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, @@ -4401,7 +4401,7 @@ void derive_key_export( int alg_arg, 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 ) );