eden-emu/mbedtls
15
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

psa: Move from key handle to key identifier

Browse source 
Move all the PSA crypto APIs using key handles
to use key identifiers but psa_key_open() and
psa_key_close(). This is done without modifying
any test as key handles and key identifiers are
now the same.

Update the library modules using PSA crypto APIs
to get rid of key handles.

Programs and unit tests are updated to not use
key handles in subsequent commits, not in this
one.

Signed-off-by: Ronald Cron <ronald.cron@arm.com>
This commit is contained in:
Ronald Cron 2020-08-04 09:51:30 +02:00
parent e4f6d5c5fe
commit cf56a0a320
20 changed files with 445 additions and 415 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/architecture/testing/invasive-testing.md
View file

@ -100,7 +100,7 @@ Resources include:
* Memory.
* Files in storage (PSA API only — in the Mbed TLS API, black-box unit tests are sufficient).
* Key handles (PSA API only).
* Key slots (PSA API only).
* Key slots in a secure element (PSA SE HAL).
* Communication handles (PSA crypto service only).
@ -116,7 +116,7 @@ When code should clean up resources, how do we know that they have truly been cl
* Zeroization of confidential data after use.
* Freeing memory.
* Closing key handles.
* Freeing key slots.
* Freeing key slots in a secure element.
* Deleting files in storage (PSA API only).

64
docs/getting_started.md
View file

@ -64,7 +64,7 @@ To use the Mbed Crypto APIs, call `psa_crypto_init()` before calling any other A
### Importing a key
To use a key for cryptography operations in Mbed Crypto, you need to first
import it. Importing the key creates a handle that refers to the key for use
import it. The import operation returns the identifier of the key for use
with other function calls.
**Prerequisites to importing keys:**
@ -76,7 +76,7 @@ void import_a_key(const uint8_t *key, size_t key_len)
{
psa_status_t status;
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_key_handle_t handle;
psa_key_id_t key;
printf("Import an AES key...\t");
fflush(stdout);
@ -95,7 +95,7 @@ void import_a_key(const uint8_t *key, size_t key_len)
psa_set_key_bits(&attributes, 128);
/* Import the key */
status = psa_import_key(&attributes, key, key_len, &handle);
status = psa_import_key(&attributes, key, key_len, &key);
if (status != PSA_SUCCESS) {
printf("Failed to import key\n");
return;
@ -106,7 +106,7 @@ void import_a_key(const uint8_t *key, size_t key_len)
psa_reset_key_attributes(&attributes);
/* Destroy the key */
psa_destroy_key(handle);
psa_destroy_key(key);
mbedtls_psa_crypto_free();
}
@ -135,7 +135,7 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
0xa9, 0xe8, 0xcc, 0xac, 0xd0, 0xf6, 0x54, 0x5c};
uint8_t signature[PSA_SIGNATURE_MAX_SIZE] = {0};
size_t signature_length;
psa_key_handle_t handle;
psa_key_id_t key;
printf("Sign a message...\t");
fflush(stdout);
@ -154,14 +154,14 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
psa_set_key_bits(&attributes, 1024);
/* Import the key */
status = psa_import_key(&attributes, key, key_len, &handle);
status = psa_import_key(&attributes, key, key_len, &key);
if (status != PSA_SUCCESS) {
printf("Failed to import key\n");
return;
}
/* Sign message using the key */
status = psa_sign_hash(handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW,
status = psa_sign_hash(key, PSA_ALG_RSA_PKCS1V15_SIGN_RAW,
hash, sizeof(hash),
signature, sizeof(signature),
&signature_length);
@ -176,7 +176,7 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
psa_reset_key_attributes(&attributes);
/* Destroy the key */
psa_destroy_key(handle);
psa_destroy_key(key);
mbedtls_psa_crypto_free();
}
@ -188,7 +188,7 @@ Mbed Crypto supports encrypting and decrypting messages using various symmetric
**Prerequisites to working with the symmetric cipher API:**
* Initialize the library with a successful call to `psa_crypto_init()`.
* Have a handle to a symmetric key. This key's usage flags must include `PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to allow decryption.
* Have a symmetric key. This key's usage flags must include `PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to allow decryption.
**To encrypt a message with a symmetric cipher:**
1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
@ -213,7 +213,7 @@ void encrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
size_t iv_len;
uint8_t output[block_size];
size_t output_len;
psa_key_handle_t handle;
psa_key_id_t key;
psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
printf("Encrypt with cipher...\t");
@ -232,7 +232,7 @@ void encrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
psa_set_key_algorithm(&attributes, alg);
psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
psa_set_key_bits(&attributes, 128);
status = psa_import_key(&attributes, key, key_len, &handle);
status = psa_import_key(&attributes, key, key_len, &key);
if (status != PSA_SUCCESS) {
printf("Failed to import a key\n");
return;
@ -240,7 +240,7 @@ void encrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
psa_reset_key_attributes(&attributes);
/* Encrypt the plaintext */
status = psa_cipher_encrypt_setup(&operation, handle, alg);
status = psa_cipher_encrypt_setup(&operation, key, alg);
if (status != PSA_SUCCESS) {
printf("Failed to begin cipher operation\n");
return;
@ -268,7 +268,7 @@ void encrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
psa_cipher_abort(&operation);
/* Destroy the key */
psa_destroy_key(handle);
psa_destroy_key(key);
mbedtls_psa_crypto_free();
}
@ -298,7 +298,7 @@ void decrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
uint8_t iv[block_size] = ENCRYPTED_WITH_IV;
uint8_t output[block_size];
size_t output_len;
psa_key_handle_t handle;
psa_key_id_t key;
printf("Decrypt with cipher...\t");
fflush(stdout);
@ -316,7 +316,7 @@ void decrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
psa_set_key_algorithm(&attributes, alg);
psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
psa_set_key_bits(&attributes, 128);
status = psa_import_key(&attributes, key, key_len, &handle);
status = psa_import_key(&attributes, key, key_len, &key);
if (status != PSA_SUCCESS) {
printf("Failed to import a key\n");
return;
@ -324,7 +324,7 @@ void decrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
psa_reset_key_attributes(&attributes);
/* Decrypt the ciphertext */
status = psa_cipher_decrypt_setup(&operation, handle, alg);
status = psa_cipher_decrypt_setup(&operation, key, alg);
if (status != PSA_SUCCESS) {
printf("Failed to begin cipher operation\n");
return;
@ -352,7 +352,7 @@ void decrypt_with_symmetric_ciphers(const uint8_t *key, size_t key_len)
psa_cipher_abort(&operation);
/* Destroy the key */
psa_destroy_key(handle);
psa_destroy_key(key);
mbedtls_psa_crypto_free();
}
@ -592,8 +592,8 @@ derived from the key, salt and info provided:
PSA_KEY_DERIVATION_OPERATION_INIT;
size_t derived_bits = 128;
size_t capacity = PSA_BITS_TO_BYTES(derived_bits);
psa_key_handle_t base_key;
psa_key_handle_t derived_key;
psa_key_id_t base_key;
psa_key_id_t derived_key;
printf("Derive a key (HKDF)...\t");
fflush(stdout);
@ -702,7 +702,7 @@ This example shows how to authenticate and encrypt a message:
size_t output_length = 0;
size_t tag_length = 16;
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_key_handle_t handle;
psa_key_id_t key;
printf("Authenticate encrypt...\t");
fflush(stdout);
@ -726,11 +726,11 @@ This example shows how to authenticate and encrypt a message:
psa_set_key_algorithm(&attributes, PSA_ALG_CCM);
psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
psa_set_key_bits(&attributes, 128);
status = psa_import_key(&attributes, key, sizeof(key), &handle);
status = psa_import_key(&attributes, key, sizeof(key), &key);
psa_reset_key_attributes(&attributes);
/* Authenticate and encrypt */
status = psa_aead_encrypt(handle, PSA_ALG_CCM,
status = psa_aead_encrypt(key, PSA_ALG_CCM,
nonce, sizeof(nonce),
additional_data, sizeof(additional_data),
input_data, sizeof(input_data),
@ -747,7 +747,7 @@ This example shows how to authenticate and encrypt a message:
free(output_data);
/* Destroy the key */
psa_destroy_key(handle);
psa_destroy_key(key);
mbedtls_psa_crypto_free();
```
@ -756,7 +756,7 @@ This example shows how to authenticate and decrypt a message:
```C
psa_status_t status;
static const uint8_t key[] = {
static const uint8_t key_data[] = {
0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7,
0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF };
static const uint8_t nonce[] = {
@ -773,7 +773,7 @@ This example shows how to authenticate and decrypt a message:
size_t output_size = 0;
size_t output_length = 0;
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_key_handle_t handle;
psa_key_id_t key;
printf("Authenticate decrypt...\t");
fflush(stdout);
@ -797,7 +797,7 @@ This example shows how to authenticate and decrypt a message:
psa_set_key_algorithm(&attributes, PSA_ALG_CCM);
psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
psa_set_key_bits(&attributes, 128);
status = psa_import_key(&attributes, key, sizeof(key), &handle);
status = psa_import_key(&attributes, key_data, sizeof(key_data), &key);
if (status != PSA_SUCCESS) {
printf("Failed to import a key\n");
return;
@ -805,7 +805,7 @@ This example shows how to authenticate and decrypt a message:
psa_reset_key_attributes(&attributes);
/* Authenticate and decrypt */
status = psa_aead_decrypt(handle, PSA_ALG_CCM,
status = psa_aead_decrypt(key, PSA_ALG_CCM,
nonce, sizeof(nonce),
additional_data, sizeof(additional_data),
input_data, sizeof(input_data),
@ -822,7 +822,7 @@ This example shows how to authenticate and decrypt a message:
free(output_data);
/* Destroy the key */
psa_destroy_key(handle);
psa_destroy_key(key);
mbedtls_psa_crypto_free();
```
@ -848,7 +848,7 @@ Mbed Crypto provides a simple way to generate a key or key pair.
size_t exported_length = 0;
static uint8_t exported[PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits)];
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
psa_key_handle_t handle;
psa_key_id_t key;
printf("Generate a key pair...\t");
fflush(stdout);
@ -867,14 +867,14 @@ Mbed Crypto provides a simple way to generate a key or key pair.
psa_set_key_type(&attributes,
PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
psa_set_key_bits(&attributes, key_bits);
status = psa_generate_key(&attributes, &handle);
status = psa_generate_key(&attributes, &key);
if (status != PSA_SUCCESS) {
printf("Failed to generate key\n");
return;
}
psa_reset_key_attributes(&attributes);
status = psa_export_public_key(handle, exported, sizeof(exported),
status = psa_export_public_key(key, exported, sizeof(exported),
&exported_length);
if (status != PSA_SUCCESS) {
printf("Failed to export public key %ld\n", status);
@ -884,7 +884,7 @@ Mbed Crypto provides a simple way to generate a key or key pair.
printf("Exported a public key\n");
/* Destroy the key */
psa_destroy_key(handle);
psa_destroy_key(key);
mbedtls_psa_crypto_free();
```

4
docs/proposed/psa-driver-developer-guide.md
View file

@ -36,10 +36,6 @@ A driver therefore consists of:
Mbed TLS calls driver entry points [as specified in the PSA Cryptography Driver Interface specification](psa-driver-interface.html#driver-entry-points) except as otherwise indicated in this section.
### Key handles
Mbed TLS currently implements the interface for opening and closing persistent keys from version 1.0 beta 3 of the PSA Crypto specification. As a consequence, functions that operate on an existing key take an argument of type `psa_key_handle_t` instead of `psa_key_id_t`. Functions that create a new key take an argument of type `psa_key_handle_t *` instead of `psa_key_id_t *`.
## Building and testing your driver
<!-- TODO -->

4
docs/proposed/psa-driver-interface.md
View file

@ -580,8 +580,8 @@ psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
psa_set_key_size(&attributes, 128);
psa_set_key_algorithm(&attributes, PSA_ALG_GCM);
psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_ENCRYPT | PSA_KEY_USAGE_DECRYPT);
psa_key_handle_t handle = 0;
psa_generate_key(&attributes, &handle);
psa_key_id_t key;
psa_generate_key(&attributes, &key);
```
## Using opaque drivers from an application