Skip to content

Commit 87a5e56

Browse files
gilles-peskine-armgilles-peskine-arm
committed
Rename functions that inject key material to an allocated handle
This commit starts a migration to a new interface for key creation. Today, the application allocates a handle, then fills its metadata, and finally injects key material. The new interface fills metadata into a temporary structure, and a handle is allocated at the same time it gets filled with both metadata and key material. This commit was obtained by moving the declaration of the old-style functions to crypto_extra.h and renaming them with the to_handle suffix, adding declarations for the new-style functions in crypto.h under their new name, and running perl -i -pe 's/\bpsa_(import|copy|generator_import|generate)_key\b/$&_to_handle/g' library/*.c tests/suites/*.function programs/psa/*.c perl -i -pe 's/\bpsa_get_key_lifetime\b/$&_from_handle/g' library/*.c tests/suites/*.function programs/psa/*.c Many functions that are specific to the old interface, and which will not remain under the same name with the new interface, are still in crypto.h for now. All functional tests should still pass. The documentation may have some broken links.
1 parent c69af20 commit 87a5e56

15 files changed

+222
-171
lines changed

‎include/psa/crypto.h

Lines changed: 26 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,24 @@ psa_status_t psa_crypto_init(void);
9393

9494
/**@}*/
9595

96+
/** \defgroup attributes Key attributes
97+
* @{
98+
*/
99+
100+
/** The type of a structure containing key attributes.
101+
*
102+
* This is an opaque structure that can represent the metadata of a key
103+
* object, including the key type and size, domain parameters, usage policies,
104+
* location in storage, and any other similar information.
105+
*
106+
* The actual key material is not considered an attribute of a key.
107+
* Key attributes do not contain information that is generally considered
108+
* highly confidential.
109+
*/
110+
typedef struct psa_key_attributes_s psa_key_attributes_t;
111+
112+
/**@}*/
113+
96114
/** \defgroup policy Key policies
97115
* @{
98116
*/
@@ -231,26 +249,6 @@ psa_status_t psa_get_key_policy(psa_key_handle_t handle,
231249
* @{
232250
*/
233251

234-
/** \brief Retrieve the lifetime of an open key.
235-
*
236-
* \param handle Handle to query.
237-
* \param[out] lifetime On success, the lifetime value.
238-
*
239-
* \retval #PSA_SUCCESS
240-
* Success.
241-
* \retval #PSA_ERROR_INVALID_HANDLE
242-
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
243-
* \retval #PSA_ERROR_HARDWARE_FAILURE
244-
* \retval #PSA_ERROR_TAMPERING_DETECTED
245-
* \retval #PSA_ERROR_BAD_STATE
246-
* The library has not been previously initialized by psa_crypto_init().
247-
* It is implementation-dependent whether a failure to initialize
248-
* results in this error code.
249-
*/
250-
psa_status_t psa_get_key_lifetime(psa_key_handle_t handle,
251-
psa_key_lifetime_t *lifetime);
252-
253-
254252
/** Allocate a key slot for a transient key, i.e. a key which is only stored
255253
* in volatile memory.
256254
*
@@ -302,43 +300,6 @@ psa_status_t psa_open_key(psa_key_lifetime_t lifetime,
302300
psa_key_id_t id,
303301
psa_key_handle_t *handle);
304302

305-
/** Create a new persistent key slot.
306-
*
307-
* Create a new persistent key slot and return a handle to it. The handle
308-
* remains valid until the application calls psa_close_key() or terminates.
309-
* The application can open the key again with psa_open_key() until it
310-
* removes the key by calling psa_destroy_key().
311-
*
312-
* \param lifetime The lifetime of the key. This designates a storage
313-
* area where the key material is stored. This must not
314-
* be #PSA_KEY_LIFETIME_VOLATILE.
315-
* \param id The persistent identifier of the key.
316-
* \param[out] handle On success, a handle to the newly created key slot.
317-
* When key material is later created in this key slot,
318-
* it will be saved to the specified persistent location.
319-
*
320-
* \retval #PSA_SUCCESS
321-
* Success. The application can now use the value of `*handle`
322-
* to access the newly allocated key slot.
323-
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
324-
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
325-
* \retval #PSA_ERROR_ALREADY_EXISTS
326-
* There is already a key with the identifier \p id in the storage
327-
* area designated by \p lifetime.
328-
* \retval #PSA_ERROR_INVALID_ARGUMENT
329-
* \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
330-
* \retval #PSA_ERROR_INVALID_ARGUMENT
331-
* \p id is invalid for the specified lifetime.
332-
* \retval #PSA_ERROR_NOT_SUPPORTED
333-
* \p lifetime is not supported.
334-
* \retval #PSA_ERROR_NOT_PERMITTED
335-
* \p lifetime is valid, but the application does not have the
336-
* permission to create a key there.
337-
*/
338-
psa_status_t psa_create_key(psa_key_lifetime_t lifetime,
339-
psa_key_id_t id,
340-
psa_key_handle_t *handle);
341-
342303
/** Close a key handle.
343304
*
344305
* If the handle designates a volatile key, destroy the key material and
@@ -417,7 +378,8 @@ psa_status_t psa_close_key(psa_key_handle_t handle);
417378
* It is implementation-dependent whether a failure to initialize
418379
* results in this error code.
419380
*/
420-
psa_status_t psa_import_key(psa_key_handle_t handle,
381+
psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
382+
psa_key_handle_t *handle,
421383
psa_key_type_t type,
422384
const uint8_t *data,
423385
size_t data_length);
@@ -809,8 +771,8 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
809771
* \retval #PSA_ERROR_TAMPERING_DETECTED
810772
*/
811773
psa_status_t psa_copy_key(psa_key_handle_t source_handle,
812-
psa_key_handle_t target_handle,
813-
const psa_key_policy_t *constraint);
774+
const psa_key_attributes_t *attributes,
775+
psa_key_handle_t *target_handle);
814776

815777
/**@}*/
816778

@@ -3006,7 +2968,8 @@ psa_status_t psa_generator_read(psa_crypto_generator_t *generator,
30062968
* It is implementation-dependent whether a failure to initialize
30072969
* results in this error code.
30082970
*/
3009-
psa_status_t psa_generator_import_key(psa_key_handle_t handle,
2971+
psa_status_t psa_generator_import_key(const psa_key_attributes_t *attributes,
2972+
psa_key_handle_t *handle,
30102973
psa_key_type_t type,
30112974
size_t bits,
30122975
psa_crypto_generator_t *generator);
@@ -3398,7 +3361,8 @@ typedef struct {
33983361
* It is implementation-dependent whether a failure to initialize
33993362
* results in this error code.
34003363
*/
3401-
psa_status_t psa_generate_key(psa_key_handle_t handle,
3364+
psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
3365+
psa_key_handle_t *handle,
34023366
psa_key_type_t type,
34033367
size_t bits,
34043368
const void *extra,

‎include/psa/crypto_extra.h

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,93 @@ psa_status_t psa_key_derivation(psa_crypto_generator_t *generator,
202202
/* FIXME Deprecated. Remove this as soon as all the tests are updated. */
203203
#define PSA_ALG_SELECT_RAW ((psa_algorithm_t)0x31000001)
204204

205+
/** \defgroup to_handle Key creation to allocated handle
206+
* @{
207+
*
208+
* The functions in this section are legacy interfaces where the properties
209+
* of a key object are set after allocating a handle, in constrast with the
210+
* preferred interface where key objects are created atomically from
211+
* a structure that represents the properties.
212+
*/
213+
214+
/** Create a new persistent key slot.
215+
*
216+
* Create a new persistent key slot and return a handle to it. The handle
217+
* remains valid until the application calls psa_close_key() or terminates.
218+
* The application can open the key again with psa_open_key() until it
219+
* removes the key by calling psa_destroy_key().
220+
*
221+
* \param lifetime The lifetime of the key. This designates a storage
222+
* area where the key material is stored. This must not
223+
* be #PSA_KEY_LIFETIME_VOLATILE.
224+
* \param id The persistent identifier of the key.
225+
* \param[out] handle On success, a handle to the newly created key slot.
226+
* When key material is later created in this key slot,
227+
* it will be saved to the specified persistent location.
228+
*
229+
* \retval #PSA_SUCCESS
230+
* Success. The application can now use the value of `*handle`
231+
* to access the newly allocated key slot.
232+
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
233+
* \retval #PSA_ERROR_INSUFFICIENT_STORAGE
234+
* \retval #PSA_ERROR_ALREADY_EXISTS
235+
* There is already a key with the identifier \p id in the storage
236+
* area designated by \p lifetime.
237+
* \retval #PSA_ERROR_INVALID_ARGUMENT
238+
* \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
239+
* \retval #PSA_ERROR_INVALID_ARGUMENT
240+
* \p id is invalid for the specified lifetime.
241+
* \retval #PSA_ERROR_NOT_SUPPORTED
242+
* \p lifetime is not supported.
243+
* \retval #PSA_ERROR_NOT_PERMITTED
244+
* \p lifetime is valid, but the application does not have the
245+
* permission to create a key there.
246+
*/
247+
psa_status_t psa_create_key(psa_key_lifetime_t lifetime,
248+
psa_key_id_t id,
249+
psa_key_handle_t *handle);
250+
251+
/** \brief Retrieve the lifetime of an open key.
252+
*
253+
* \param handle Handle to query.
254+
* \param[out] lifetime On success, the lifetime value.
255+
*
256+
* \retval #PSA_SUCCESS
257+
* Success.
258+
* \retval #PSA_ERROR_INVALID_HANDLE
259+
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
260+
* \retval #PSA_ERROR_HARDWARE_FAILURE
261+
* \retval #PSA_ERROR_TAMPERING_DETECTED
262+
* \retval #PSA_ERROR_BAD_STATE
263+
* The library has not been previously initialized by psa_crypto_init().
264+
* It is implementation-dependent whether a failure to initialize
265+
* results in this error code.
266+
*/
267+
psa_status_t psa_get_key_lifetime_from_handle(psa_key_handle_t handle,
268+
psa_key_lifetime_t *lifetime);
269+
270+
psa_status_t psa_import_key_to_handle(psa_key_handle_t handle,
271+
psa_key_type_t type,
272+
const uint8_t *data,
273+
size_t data_length);
274+
275+
psa_status_t psa_copy_key_to_handle(psa_key_handle_t source_handle,
276+
psa_key_handle_t target_handle,
277+
const psa_key_policy_t *constraint);
278+
279+
psa_status_t psa_generator_import_key_to_handle(psa_key_handle_t handle,
280+
psa_key_type_t type,
281+
size_t bits,
282+
psa_crypto_generator_t *generator);
283+
284+
psa_status_t psa_generate_key_to_handle(psa_key_handle_t handle,
285+
psa_key_type_t type,
286+
size_t bits,
287+
const void *extra,
288+
size_t extra_size);
289+
290+
/**@}*/
291+
205292
#ifdef __cplusplus
206293
}
207294
#endif

‎library/cipher.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -338,7 +338,7 @@ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx,
338338
return( MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED );
339339

340340
/* Populate new key slot. */
341-
status = psa_import_key( cipher_psa->slot,
341+
status = psa_import_key_to_handle( cipher_psa->slot,
342342
key_type, key, key_bytelen );
343343
if( status != PSA_SUCCESS )
344344
return( MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED );

‎library/pk.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -629,7 +629,7 @@ int mbedtls_pk_wrap_as_opaque( mbedtls_pk_context *pk,
629629
return( MBEDTLS_ERR_PK_HW_ACCEL_FAILED );
630630

631631
/* import private key in slot */
632-
if( PSA_SUCCESS != psa_import_key( key, key_type, d, d_len ) )
632+
if( PSA_SUCCESS != psa_import_key_to_handle( key, key_type, d, d_len ) )
633633
return( MBEDTLS_ERR_PK_HW_ACCEL_FAILED );
634634

635635
/* remember slot number to be destroyed later by caller */

‎library/pk_wrap.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -589,7 +589,7 @@ static int ecdsa_verify_wrap( void *ctx, mbedtls_md_type_t md_alg,
589589
goto cleanup;
590590
}
591591

592-
if( psa_import_key( key_slot, psa_type, buf + sizeof( buf ) - key_len, key_len )
592+
if( psa_import_key_to_handle( key_slot, psa_type, buf + sizeof( buf ) - key_len, key_len )
593593
!= PSA_SUCCESS )
594594
{
595595
ret = MBEDTLS_ERR_PK_BAD_INPUT_DATA;

‎library/psa_crypto.c

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -903,7 +903,7 @@ psa_status_t psa_wipe_key_slot( psa_key_slot_t *slot )
903903
return( status );
904904
}
905905

906-
psa_status_t psa_import_key( psa_key_handle_t handle,
906+
psa_status_t psa_import_key_to_handle( psa_key_handle_t handle,
907907
psa_key_type_t type,
908908
const uint8_t *data,
909909
size_t data_length )
@@ -1228,7 +1228,7 @@ static psa_status_t psa_copy_key_material( const psa_key_slot_t *source,
12281228
status = psa_internal_export_key( source, buffer, buffer_size, &length, 0 );
12291229
if( status != PSA_SUCCESS )
12301230
goto exit;
1231-
status = psa_import_key( target, source->type, buffer, length );
1231+
status = psa_import_key_to_handle( target, source->type, buffer, length );
12321232

12331233
exit:
12341234
if( buffer_size != 0 )
@@ -1237,7 +1237,7 @@ static psa_status_t psa_copy_key_material( const psa_key_slot_t *source,
12371237
return( status );
12381238
}
12391239

1240-
psa_status_t psa_copy_key(psa_key_handle_t source_handle,
1240+
psa_status_t psa_copy_key_to_handle(psa_key_handle_t source_handle,
12411241
psa_key_handle_t target_handle,
12421242
const psa_key_policy_t *constraint)
12431243
{
@@ -3277,7 +3277,7 @@ psa_status_t psa_get_key_policy( psa_key_handle_t handle,
32773277
/* Key Lifetime */
32783278
/****************************************************************/
32793279

3280-
psa_status_t psa_get_key_lifetime( psa_key_handle_t handle,
3280+
psa_status_t psa_get_key_lifetime_from_handle( psa_key_handle_t handle,
32813281
psa_key_lifetime_t *lifetime )
32823282
{
32833283
psa_key_slot_t *slot;
@@ -3996,7 +3996,7 @@ static void psa_des_set_key_parity( uint8_t *data, size_t data_size )
39963996
}
39973997
#endif /* MBEDTLS_DES_C */
39983998

3999-
psa_status_t psa_generator_import_key( psa_key_handle_t handle,
3999+
psa_status_t psa_generator_import_key_to_handle( psa_key_handle_t handle,
40004000
psa_key_type_t type,
40014001
size_t bits,
40024002
psa_crypto_generator_t *generator )
@@ -4020,7 +4020,7 @@ psa_status_t psa_generator_import_key( psa_key_handle_t handle,
40204020
if( type == PSA_KEY_TYPE_DES )
40214021
psa_des_set_key_parity( data, bytes );
40224022
#endif /* MBEDTLS_DES_C */
4023-
status = psa_import_key( handle, type, data, bytes );
4023+
status = psa_import_key_to_handle( handle, type, data, bytes );
40244024

40254025
exit:
40264026
mbedtls_free( data );
@@ -4749,7 +4749,7 @@ psa_status_t mbedtls_psa_inject_entropy( const unsigned char *seed,
47494749
}
47504750
#endif /* MBEDTLS_PSA_INJECT_ENTROPY */
47514751

4752-
psa_status_t psa_generate_key( psa_key_handle_t handle,
4752+
psa_status_t psa_generate_key_to_handle( psa_key_handle_t handle,
47534753
psa_key_type_t type,
47544754
size_t bits,
47554755
const void *extra,

‎library/ssl_cli.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3148,7 +3148,7 @@ static int ssl_write_client_key_exchange( mbedtls_ssl_context *ssl )
31483148
return( MBEDTLS_ERR_SSL_HW_ACCEL_FAILED );
31493149

31503150
/* Generate ECDH private key. */
3151-
status = psa_generate_key( handshake->ecdh_psa_privkey,
3151+
status = psa_generate_key_to_handle( handshake->ecdh_psa_privkey,
31523152
PSA_KEY_TYPE_ECC_KEYPAIR( handshake->ecdh_psa_curve ),
31533153
MBEDTLS_PSA_ECC_KEY_BITS_OF_CURVE( handshake->ecdh_psa_curve ),
31543154
NULL, 0 );

‎library/ssl_tls.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -544,7 +544,7 @@ static int tls_prf_generic( mbedtls_md_type_t md_type,
544544
if( status != PSA_SUCCESS )
545545
return( MBEDTLS_ERR_SSL_HW_ACCEL_FAILED );
546546

547-
status = psa_import_key( master_slot, PSA_KEY_TYPE_DERIVE, secret, slen );
547+
status = psa_import_key_to_handle( master_slot, PSA_KEY_TYPE_DERIVE, secret, slen );
548548
if( status != PSA_SUCCESS )
549549
return( MBEDTLS_ERR_SSL_HW_ACCEL_FAILED );
550550

‎programs/psa/crypto_examples.c

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,7 @@ cipher_example_encrypt_decrypt_aes_cbc_nopad_1_block( void )
179179
alg );
180180
ASSERT_STATUS( status, PSA_SUCCESS );
181181

182-
status = psa_generate_key( key_handle, PSA_KEY_TYPE_AES, key_bits,
182+
status = psa_generate_key_to_handle( key_handle, PSA_KEY_TYPE_AES, key_bits,
183183
NULL, 0 );
184184
ASSERT_STATUS( status, PSA_SUCCESS );
185185

@@ -229,7 +229,7 @@ static psa_status_t cipher_example_encrypt_decrypt_aes_cbc_pkcs7_multi( void )
229229
alg );
230230
ASSERT_STATUS( status, PSA_SUCCESS );
231231

232-
status = psa_generate_key( key_handle, PSA_KEY_TYPE_AES, key_bits,
232+
status = psa_generate_key_to_handle( key_handle, PSA_KEY_TYPE_AES, key_bits,
233233
NULL, 0 );
234234
ASSERT_STATUS( status, PSA_SUCCESS );
235235

@@ -277,7 +277,7 @@ static psa_status_t cipher_example_encrypt_decrypt_aes_ctr_multi( void )
277277
alg );
278278
ASSERT_STATUS( status, PSA_SUCCESS );
279279

280-
status = psa_generate_key( key_handle, PSA_KEY_TYPE_AES, key_bits,
280+
status = psa_generate_key_to_handle( key_handle, PSA_KEY_TYPE_AES, key_bits,
281281
NULL, 0 );
282282
ASSERT_STATUS( status, PSA_SUCCESS );
283283

0 commit comments

Comments
 (0)