psa: Move from key handle to key identifier
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>
diff --git a/docs/architecture/testing/invasive-testing.md b/docs/architecture/testing/invasive-testing.md
index 744f194..de611a5 100644
--- a/docs/architecture/testing/invasive-testing.md
+++ b/docs/architecture/testing/invasive-testing.md
@@ -100,7 +100,7 @@
* 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 @@
* 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).
diff --git a/docs/getting_started.md b/docs/getting_started.md
index e274f49..15d5a31 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -64,7 +64,7 @@
### 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 @@
{
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 @@
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 @@
psa_reset_key_attributes(&attributes);
/* Destroy the key */
- psa_destroy_key(handle);
+ psa_destroy_key(key);
mbedtls_psa_crypto_free();
}
@@ -135,7 +135,7 @@
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 @@
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 @@
psa_reset_key_attributes(&attributes);
/* Destroy the key */
- psa_destroy_key(handle);
+ psa_destroy_key(key);
mbedtls_psa_crypto_free();
}
@@ -188,7 +188,7 @@
**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 @@
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 @@
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 @@
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 @@
psa_cipher_abort(&operation);
/* Destroy the key */
- psa_destroy_key(handle);
+ psa_destroy_key(key);
mbedtls_psa_crypto_free();
}
@@ -298,7 +298,7 @@
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 @@
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 @@
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 @@
psa_cipher_abort(&operation);
/* Destroy the key */
- psa_destroy_key(handle);
+ psa_destroy_key(key);
mbedtls_psa_crypto_free();
}
@@ -592,8 +592,8 @@
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 @@
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 @@
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 @@
free(output_data);
/* Destroy the key */
- psa_destroy_key(handle);
+ psa_destroy_key(key);
mbedtls_psa_crypto_free();
```
@@ -756,7 +756,7 @@
```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 @@
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 @@
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 @@
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 @@
free(output_data);
/* Destroy the key */
- psa_destroy_key(handle);
+ psa_destroy_key(key);
mbedtls_psa_crypto_free();
```
@@ -848,7 +848,7 @@
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 @@
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 @@
printf("Exported a public key\n");
/* Destroy the key */
- psa_destroy_key(handle);
+ psa_destroy_key(key);
mbedtls_psa_crypto_free();
```
diff --git a/docs/proposed/psa-driver-developer-guide.md b/docs/proposed/psa-driver-developer-guide.md
index c221bb2..70cb9d3 100644
--- a/docs/proposed/psa-driver-developer-guide.md
+++ b/docs/proposed/psa-driver-developer-guide.md
@@ -36,10 +36,6 @@
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 -->
diff --git a/docs/proposed/psa-driver-interface.md b/docs/proposed/psa-driver-interface.md
index 56e2b29..5ec3134 100644
--- a/docs/proposed/psa-driver-interface.md
+++ b/docs/proposed/psa-driver-interface.md
@@ -580,8 +580,8 @@
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