Add APIs to support wrapped keys

[ndevillard]

Many secure elements and crypto accelerators require the use of wrapped keys and will not accept importing clear-text keys to their key store. The existing psa_import_key function could be augmented to support wrapped keys, but that puts the burden of identifying wrapping and associated parameters on the underlying implementation. A new function should be proposed to support wrapped key imports.
As there is no standard for key wrapping data formats and associated algorithms, this should be made generic enough to be adaptable to any such key stores.
Same need for exporting wrapped keys.

[gilles-peskine-arm]

Some related internal discussions on the topic:

• https://github.com/ARM-software/psa-crypto-api/issues/32
• https://github.com/ARM-software/psa-crypto-api/issues/39
• https://github.com/ARM-software/psa-crypto-api/issues/77
• https://github.com/ARM-software/psa-crypto-api/issues/90
• https://github.com/ARMmbed/mbedtls-psa/issues/123

[gilles-peskine-arm]

An old proposal, which I don't have time to work on right now: ARMmbed/mbed-crypto#364

[cneveux]

Some related internal discussions on the topic:

* https://github.com/ARM-software/psa-crypto-api/issues/32

* https://github.com/ARM-software/psa-crypto-api/issues/39

* https://github.com/ARM-software/psa-crypto-api/issues/77

* https://github.com/ARM-software/psa-crypto-api/issues/90

* https://github.com/ARMmbed/mbedtls-psa/issues/123

@gilles-peskine-arm

This link above are not working. They are probably to old and no more accessible for the public.

[gilles-peskine-arm]

@cneveux Indeed the psa-crypto-api and mbedtls-psa projects are private. If someone from outside Arm wants to work on the topic, let us know and we'll summarise the internal discussions.

[athoelke]

Wrapping with a device-specific secret key

An API proposed in Mbed-TLS/mbedtls#7910, enables the import of keys in other formats. As currently proposed, this only covers formats where the key material is in cleartext.

However, if we add the equivalent psa_export_key_ext(), and permit implementation-defined formats for the API; then this would enable an implementation to provide import and export of wrapped keys, using a device-secret key wrapping key and implementation-specific algorithm.

This is sufficient for use cases that do not involve an application choice of algorithm or key-wrapping key.

[athoelke]

Wrapping using a standard algorithm and application-selected key-wrapping key

Defining an API for this use case is more challenging, as there are a lack of standards defining key-wrapping algorithms and formats for the wrapped material.

However:

• The NIST AES Key Wrap (AES-KW) and AES Key Wrap With Padding (AES-KWP) algorithms are currently provided by the Mbed TLS API (see mbedtls/nist_kw.h). Having a Crypto API interface for these algorithms would be valuable when the MbedTLS legacy interface is withdrawn in future.
• With the introduction of additional supported import formats (see Work on psa_import_key_ext() Mbed-TLS/mbedtls#7910), we might have a mechanism to specify the format of the plaintext data that is wrapped, where the wrapping algorithm itself does not mandate a specific format.

API proposal

A simple API design could just implement the wrapping algorithm on data provided by the application. This requires that the application export the key material to the application and then encrypt it, exposing the key material within the application memory. In keeping with the design goals of the Crypto API, I would prefer to define an API that enabled the cleartext key material to be kept within a cryptoprocessor implementation, providing better assurance of the key confidentiality and integrity for application developers. Note that this improvement is a reduction in risk: the application is capable of decrypting the wrapped key as it knows the key and algorithm used to wrap it; but an attacker requires more than application-memory-read capability to disclose the key.

Building on the format specifier additions for psa_import_key_ext() in Mbed-TLS/mbedtls#7910, we could define the following functions:

psa_status_t psa_unwrap_key(const psa_key_attributes_t *attributes,
                            psa_key_id_t wrapping_key,
                            psa_algorithm_t alg,
                            psa_key_data_format_t format,
                            const uint8_t *data,
                            size_t data_length,
                            psa_key_id_t *key);

psa_status_t psa_wrap_key(psa_key_id_t key,
                          psa_key_id_t wrapping_key,
                          psa_algorithm_t alg,
                          psa_key_data_format_t format,
                          const uint8_t *data,
                          size_t data_size,
                          size_t *data_length);

Conceptually, psa_unwrap_key(att, format, wrapping_key, alg, data, length, &key) would be equivalent to:

uint8_t cleartext[32];
size_t cleartext_len;
psa_unwrap_keydata(wrapping_key, alg, data, data_length, &cleartext, sizeof(cleartext), &cleartext_len);
psa_import_key_ext(att, format, &cleartext, cleartext_len, &key);

.. except that the cleartext is not visible to the application, and the format might be dictated by the wrapping algorithm.

For psa_unwrap_key(), the wrapping_key must specify the wrapping algorithm as the permitted-algorithm, and have the the [new] usage flag PSA_KEY_USAGE_UNWRAP. The key attributes will be interpreted as for psa_import_key_ext(), and must not conflict with any key attributes and policy that are encoded in the wrapped key data.

For psa_wrap_key(), , the wrapping_key must specify the wrapping algorithm as the permitted-algorithm, and have the the [new] usage flag PSA_KEY_USAGE_WRAP. The key to be wrapped must have the usage flag PSA_KEY_USAGE_EXPORT.

For both functions, the format of the key material must be compatible with the algorithm - for example, AES-KW requires cleartext that is $8n, n>=2$ bytes in size.

An 'unspecified' key format, perhaps PSA_KEY_FORMAT_DEFAULT, requests to use the format associated with the algorithm, if there is one, otherwise the standard PSA Crypto API key format as expected by psa_import_key().