PSA key audit API: never-exposable property for keys

[athoelke]

Add an API to indicate if a key can be guaranteed to have never been exposed outside of its security boundary. This is required to enable PSA key attestation.

The current Crypto API does have PSA_KEY_USAGE_EXPORT as part of the key usage policy. However, a key which has this policy clear does not indicate that the key value has not been exposed. For example,

• A key can be imported with psa_import_key() and the new key does not permit export.
• A key that has PSA_KEY_USAGE_EXPORT policy, is copied to a new key that does not.

A new API is required to identify if the key has never been exposed outside of the security domain in which it was created.

https://github.com/Mbed-TLS/mbedtls/pull/6377 is a pull-request for Mbed-TLS that provides a proposed API (and implementation) for this feature.

The current definition of the API in the PR is:

PSA_KEY_AUDIT_FLAG_NEVER_EXPORTED (macro)

Audit flag indicating that the key material was never and will never be exposed in plaintext form outside the security boundary of its location.

#define PSA_KEY_AUDIT_FLAG_NEVER_EXPORTED ((psa_key_audit_flags_t) 0x00000001u)

This flag should be set if all of the following conditions are met:

• The key material was generated randomly with psa_generate_key().
• The key has never had the flag PSA_KEY_USAGE_EXPORT.
• If the key can be exposed outside its security boundary in wrapped form, the implementation guarantees that the wrapping key itself cannot be exposed.
• If the key was created by copying another key, these properties also apply to the original key.

This flag must not be set in any of the following cases:

• The key was created by import.
• The key, or a copy of it, was exportable in the past (unless the implementation can guarantee that it was never exported).
• The key, or a copy of it, is currently exportable.
• The key was created by derivation, unless an implementation-specific policy on the secret from which the key was derived prevents the same key material from being derived again with an exportable policy.
• The key is located in a secure element, and it or a copy of it may have been present outside that secure element, even if it could not escape the security boundary of the Crypto API implementation.

psa_key_audit_flags_t (type)

Key audit information in the form of a flag mask.

typedef uint32_t psa_key_audit_flags_t;

A value of this type is a mask (bitwise-or) of PSA_KEY_AUDIT_FLAG_xxx values.

A flag is set in the audit flag mask only if the implementation can guarantee that the corresponding security property was always true. If this is not possible, the implementation must leave the flag unset. Implementations should document which audit flags they support and any applicable limitations.

psa_get_key_audit_flags (function)

Retrieve the audit information flags for a key.

psa_status_t psa_get_key_audit_flags(psa_key_id_t key,
                                     psa_key_audit_flags_t *audit_flags);

Parameters
key	The key to query.
audit_flags	On success, the key's audit information flags.

Returns: psa_status_t
PSA_SUCCESS	Success. audit_flags contains the key's audit information flags.
PSA_ERROR_INVALID_HANDLE	key does not exist.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
PSA_ERROR_BAD_STATE	The library has not been previously initialized by psa_crypto_init()