Skip to content

Commit 9aa37e0

Browse files
PataterPatater
committed
psa: Add initializers for key policies
Add new initializers for key policies and use them in our docs, example programs, tests, and library code. Prefer using the macro initializers due to their straightforwardness.
1 parent 8c7e95d commit 9aa37e0

10 files changed

+134
-142
lines changed

‎docs/getting_started.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -116,14 +116,13 @@ This allows the key in the key slot to be used for RSA signing.
116116
int key_slot = 1;
117117
unsigned char key[] = "RSA_KEY";
118118
unsigned char payload[] = "ASYMMETRIC_INPUT_FOR_SIGN";
119-
psa_key_policy_t policy;
119+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
120120
unsigned char signature[PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE] = {0};
121121
size_t signature_length;
122122
123123
status = psa_crypto_init();
124124
125125
/* Import the key */
126-
psa_key_policy_init(&policy);
127126
psa_key_policy_set_usage(&policy, PSA_KEY_USAGE_SIGN,
128127
PSA_ALG_RSA_PKCS1V15_SIGN_RAW);
129128
status = psa_set_key_policy(key_slot, &policy);
@@ -343,7 +342,7 @@ At this point the derived key slot holds a new 128-bit AES-CTR encryption key de
343342
```C
344343
psa_key_slot_t base_key = 1;
345344
psa_key_slot_t derived_key = 2;
346-
psa_key_policy_t policy;
345+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
347346
348347
unsigned char key[] = {
349348
0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b,
@@ -358,14 +357,14 @@ At this point the derived key slot holds a new 128-bit AES-CTR encryption key de
358357
0xf7, 0xf8, 0xf9 };
359358
360359
psa_algorithm_t alg = PSA_ALG_HKDF(PSA_ALG_SHA_256);
360+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
361361
psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
362362
size_t derived_bits = 128;
363363
size_t capacity = PSA_BITS_TO_BYTES(derived_bits);
364364
365365
status = psa_crypto_init();
366366
367367
/* Import a key for use in key derivation, if such a key has already been imported you can skip this part */
368-
psa_key_policy_init(&policy);
369368
psa_key_policy_set_usage(&policy, PSA_KEY_USAGE_DERIVE, alg);
370369
status = psa_set_key_policy(base_key, &policy);
371370
@@ -416,12 +415,12 @@ To authenticate and encrypt a message:
416415
size_t output_size = 0;
417416
size_t output_length = 0;
418417
size_t tag_length = 16;
418+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
419419

420420
output_size = sizeof(input_data) + tag_length;
421421
output_data = malloc(output_size);
422422
status = psa_crypto_init();
423423

424-
psa_key_policy_init(&policy);
425424
psa_key_policy_set_usage(&policy, PSA_KEY_USAGE_ENCRYPT, PSA_ALG_CCM);
426425
status = psa_set_key_policy(slot, &policy);
427426

@@ -463,12 +462,12 @@ To authenticate and decrypt a message:
463462
unsigned char *output_data = NULL;
464463
size_t output_size = 0;
465464
size_t output_length = 0;
465+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
466466
467467
output_size = sizeof(input_data);
468468
output_data = malloc(output_size);
469469
status = psa_crypto_init();
470470
471-
psa_key_policy_init(&policy);
472471
psa_key_policy_set_usage(&policy, PSA_KEY_USAGE_DECRYPT, PSA_ALG_CCM);
473472
status = psa_set_key_policy(slot, &policy);
474473
@@ -503,10 +502,10 @@ Generate a piece of random 128-bit AES data:
503502
size_t exported_size = bits;
504503
size_t exported_length = 0;
505504
uint8_t *exported = malloc(exported_size);
505+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
506506

507507
psa_crypto_init();
508508

509-
psa_key_policy_init(&policy);
510509
psa_key_policy_set_usage(&policy, PSA_KEY_USAGE_EXPORT, PSA_ALG_GCM);
511510
psa_set_key_policy(slot, &policy);
512511

‎include/psa/crypto.h

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -571,28 +571,62 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
571571
*/
572572

573573
/** The type of the key policy data structure.
574+
*
575+
* Before calling any function on a key policy, the application must initialize
576+
* it by any of the following means:
577+
* - Set the structure to all-bits-zero, for example:
578+
* \code
579+
* psa_key_policy_t policy;
580+
* memset(&policy, 0, sizeof(policy));
581+
* \endcode
582+
* - Initialize the structure to logical zero values, for example:
583+
* \code
584+
* psa_key_policy_t policy = {0};
585+
* \endcode
586+
* - Initialize the structure to the initializer #PSA_KEY_POLICY_INIT,
587+
* for example:
588+
* \code
589+
* psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
590+
* \endcode
591+
* - Assign the result of the function psa_key_policy_init()
592+
* to the structure, for example:
593+
* \code
594+
* psa_key_policy_t policy;
595+
* policy = psa_key_policy_init();
596+
* \endcode
574597
*
575598
* This is an implementation-defined \c struct. Applications should not
576599
* make any assumptions about the content of this structure except
577600
* as directed by the documentation of a specific implementation. */
578601
typedef struct psa_key_policy_s psa_key_policy_t;
579602

580-
/** \brief Initialize a key policy structure to a default that forbids all
581-
* usage of the key.
603+
/** \def PSA_KEY_POLICY_INIT
582604
*
583-
* \param[out] policy The policy object to initialize.
605+
* This macro returns a suitable initializer for a key policy object of type
606+
* #psa_key_policy_t.
607+
*/
608+
#ifdef __DOXYGEN_ONLY__
609+
/* This is an example definition for documentation purposes.
610+
* Implementations should define a suitable value in `crypto_struct.h`.
611+
*/
612+
#define PSA_KEY_POLICY_INIT {0}
613+
#endif
614+
615+
/** Return an initial value for a key policy that forbids all usage of the key.
584616
*/
585-
void psa_key_policy_init(psa_key_policy_t *policy);
617+
static psa_key_policy_t psa_key_policy_init(void);
586618

587619
/** \brief Set the standard fields of a policy structure.
588620
*
589621
* Note that this function does not make any consistency check of the
590622
* parameters. The values are only checked when applying the policy to
591623
* a key slot with psa_set_key_policy().
592624
*
593-
* \param[out] policy The policy object to modify.
594-
* \param usage The permitted uses for the key.
595-
* \param alg The algorithm that the key may be used for.
625+
* \param[in,out] policy The key policy to modify. It must have been
626+
* initialized as per the documentation for
627+
* #psa_key_policy_t.
628+
* \param usage The permitted uses for the key.
629+
* \param alg The algorithm that the key may be used for.
596630
*/
597631
void psa_key_policy_set_usage(psa_key_policy_t *policy,
598632
psa_key_usage_t usage,

‎include/psa/crypto_struct.h

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,4 +208,11 @@ struct psa_key_policy_s
208208
psa_algorithm_t alg;
209209
};
210210

211+
#define PSA_KEY_POLICY_INIT {0, 0}
212+
static inline struct psa_key_policy_s psa_key_policy_init( void )
213+
{
214+
const struct psa_key_policy_s v = PSA_KEY_POLICY_INIT;
215+
return( v );
216+
}
217+
211218
#endif /* PSA_CRYPTO_STRUCT_H */

‎library/psa_crypto.c

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2938,11 +2938,6 @@ psa_status_t psa_cipher_abort( psa_cipher_operation_t *operation )
29382938
/****************************************************************/
29392939

29402940
#if !defined(MBEDTLS_PSA_CRYPTO_SPM)
2941-
void psa_key_policy_init( psa_key_policy_t *policy )
2942-
{
2943-
memset( policy, 0, sizeof( *policy ) );
2944-
}
2945-
29462941
void psa_key_policy_set_usage( psa_key_policy_t *policy,
29472942
psa_key_usage_t usage,
29482943
psa_algorithm_t alg )

‎programs/psa/crypto_examples.c

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,8 @@ static psa_status_t set_key_policy( psa_key_handle_t key_handle,
4949
psa_algorithm_t alg )
5050
{
5151
psa_status_t status;
52-
psa_key_policy_t policy;
52+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
5353

54-
psa_key_policy_init( &policy );
5554
psa_key_policy_set_usage( &policy, key_usage, alg );
5655
status = psa_set_key_policy( key_handle, &policy );
5756
ASSERT_STATUS( status, PSA_SUCCESS );

‎programs/psa/key_ladder_demo.c

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -209,12 +209,11 @@ static psa_status_t generate( const char *key_file_name )
209209
{
210210
psa_status_t status = PSA_SUCCESS;
211211
psa_key_handle_t key_handle = 0;
212-
psa_key_policy_t policy;
212+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
213213

214214
PSA_CHECK( psa_allocate_key( PSA_KEY_TYPE_DERIVE,
215215
PSA_BYTES_TO_BITS( KEY_SIZE_BYTES ),
216216
&key_handle ) );
217-
psa_key_policy_init( &policy );
218217
psa_key_policy_set_usage( &policy,
219218
PSA_KEY_USAGE_DERIVE | PSA_KEY_USAGE_EXPORT,
220219
KDF_ALG );
@@ -243,7 +242,7 @@ static psa_status_t import_key_from_file( psa_key_usage_t usage,
243242
psa_key_handle_t *master_key_handle )
244243
{
245244
psa_status_t status = PSA_SUCCESS;
246-
psa_key_policy_t policy;
245+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
247246
uint8_t key_data[KEY_SIZE_BYTES];
248247
size_t key_size;
249248
FILE *key_file = NULL;
@@ -267,7 +266,6 @@ static psa_status_t import_key_from_file( psa_key_usage_t usage,
267266
PSA_CHECK( psa_allocate_key( PSA_KEY_TYPE_DERIVE,
268267
PSA_BYTES_TO_BITS( key_size ),
269268
master_key_handle ) );
270-
psa_key_policy_init( &policy );
271269
psa_key_policy_set_usage( &policy, usage, alg );
272270
PSA_CHECK( psa_set_key_policy( *master_key_handle, &policy ) );
273271
PSA_CHECK( psa_import_key( *master_key_handle,
@@ -297,10 +295,9 @@ static psa_status_t derive_key_ladder( const char *ladder[],
297295
psa_key_handle_t *key_handle )
298296
{
299297
psa_status_t status = PSA_SUCCESS;
300-
psa_key_policy_t policy;
298+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
301299
psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
302300
size_t i;
303-
psa_key_policy_init( &policy );
304301
psa_key_policy_set_usage( &policy,
305302
PSA_KEY_USAGE_DERIVE | PSA_KEY_USAGE_EXPORT,
306303
KDF_ALG );
@@ -351,13 +348,12 @@ static psa_status_t derive_wrapping_key( psa_key_usage_t usage,
351348
psa_key_handle_t *wrapping_key_handle )
352349
{
353350
psa_status_t status = PSA_SUCCESS;
354-
psa_key_policy_t policy;
351+
psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
355352
psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
356353

357354
*wrapping_key_handle = 0;
358355
PSA_CHECK( psa_allocate_key( PSA_KEY_TYPE_AES, WRAPPING_KEY_BITS,
359356
wrapping_key_handle ) );
360-
psa_key_policy_init( &policy );
361357
psa_key_policy_set_usage( &policy, usage, WRAPPING_ALG );
362358
PSA_CHECK( psa_set_key_policy( *wrapping_key_handle, &policy ) );
363359

‎tests/suites/test_suite_psa_crypto.data

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,9 @@ import_rsa_made_up:PSA_VENDOR_RSA_MAX_KEY_BITS+8:0:PSA_ERROR_NOT_SUPPORTED
332332
PSA key policy set and get
333333
key_policy:PSA_KEY_USAGE_ENCRYPT:PSA_ALG_CBC_NO_PADDING
334334

335+
Key policy initializers zero properly
336+
key_policy_init:
337+
335338
PSA key policy: MAC, sign | verify
336339
depends_on:MBEDTLS_MD_C:MBEDTLS_SHA256_C
337340
mac_key_policy:PSA_KEY_USAGE_SIGN | PSA_KEY_USAGE_VERIFY:PSA_ALG_HMAC(PSA_ALG_SHA_256):PSA_KEY_TYPE_HMAC:"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa":PSA_ALG_HMAC(PSA_ALG_SHA_256)

0 commit comments

Comments
 (0)