Importing and exporting keys that are in non-default formats

[athoelke]

This issue is a broader set of use cases than the one defined in #44, which only considers the import of a key from a data format that specifies the key type and/or policy.

There are a number of uses cases where built-in support for additional key data formats are valuable for applications using the Crypto API:

• Importing data in a format that provides some or all of the key meta-data alongside the key material. (see also Importing a key without knowing its exact type #44)
• Exporting keys to a standard format, that is not the default key format for the API.
• Import and export of wrapped keys, that use a device-specific, secret wrapping key and an implementation-specified algorithm. This use case can be useful for provisioning keys to a device, or securely storing keys outside of the key-store.

For more general key-wrapping support, where the application can select the algorithm and key-wrapping key, see #50.

[athoelke]

Initial work drafting an API to support the first use case - "import keys in other formats" - has been carried out in the Mbed TLS project, here: Mbed-TLS/mbedtls#7910.

I plan to extend that design to support key export, and implementation-defined formats, in order to support the other use cases.

[athoelke]

Key formats to support

Key format related requirements:

• Can specify the current default key format in the Crypto API, for all key types.

• Can specify values in the Mbed TLS draft, for asymmetric RSA and ECC keys:

  • DER or PEM encoded RSAPublicKey, as defined in RFC 8017
  • DER or PEM encoded SubjectPublicKeyInfo data structure, as defined in RFC 5280
  • DER or PEM encoded RSAPrivateKey, as defined in RFC 8017
  • DER or PEM encoded ECPrivateKey, as defined in RFC 5915
  • DER or PEM encoded OneAsymmetricKey (previously PrivateKeyInfo), as defined in RFC 5958

  The Mbed TLS draft proposes that the SubjectPublicKeyInfo format can also be used to import key data that is in one of the enclosed structure formats, in particular, RSAPublicKey. Likewise, the OneSymmetricKey format also permits key data in the RSAPrivateKey or ECPrivateKey format.

  Is this relaxation important for the key import API?

• An implementation can define implementation-specific formats.

• Are there other important key formats that should be supported?

The API design in Mbed-TLS/mbedtls#7910 only addresses key import, and the definition of key formats in the psa_key_data_format_t enumeration is imprecise: each of the five proposed key format values support both PEM and DER encoding. For export, the encoding has to be specified by the application.

Proposal: Split the format specifier into separate 'format structure' and 'data encoding' fields, so that it is possible to use a relaxed specifier on import (expecting the implementation to detect PEM or DER encoding), but use a precise specifier on export. This seems like a reasonable approach - it permits additional encoding mechanisms for the same structural data layout, but also permits implementation-specific formats to reuse one or both of the fields independently.

Question: how much future space do we need for the structure and encoding fields in the format specifier?

API proposal

The key data formats are defined as 16-bit integer values.

The format value zero is special, indicating the Crypto API default format and encoding for all key types.

For other values, the top bit (bit 15) is reserved for use by implementation-specific formats, eleven bits (bits [14:4]) define the structure, and four bits ([3:0]) the encoding.

An encoding value of zero, indicates 'any' encoding, permitted for use in key import. Key export must specify an encoding, if the structure support multiple types of data encoding.

typedef uint16_t psa_key_data_format_t;

#define PSA_KEY_FORMAT_DEFAULT ((psa_key_data_format_t) 0)

#define PSA_KEY_FORMAT_RSA_PUBLIC_KEY(encoding)          \
    ((psa_key_data_format_t) 0x0010 | (encoding))
#define PSA_KEY_FORMAT_SUBJECT_PUBLIC_KEY_INFO(encoding) \
    ((psa_key_data_format_t) 0x0020 | (encoding))
#define PSA_KEY_FORMAT_RSA_PRIVATE_KEY(encoding)         \
    ((psa_key_data_format_t) 0x0030 | (encoding))
#define PSA_KEY_FORMAT_EC_PRIVATE_KEY(encoding)          \
    ((psa_key_data_format_t) 0x0040 | (encoding))
#define PSA_KEY_FORMAT_ONE_ASYMMETRIC_KEY(encoding)      \
    ((psa_key_data_format_t) 0x0050 | (encoding))

#define PSA_KEY_ENCODING_ANY (0x0)
#define PSA_KEY_ENCODING_DER (0x1)
#define PSA_KEY_ENCODING_PEM (0x2)

The extended import and export APIs are just like the current functions, but take a format specifier. Note that if PSA_KEY_FORMAT_DEFAULT is used, then these functions act exactly like psa_import_key() and psa_export_key().

psa_status_t psa_import_key_ext(const psa_key_attributes_t *attributes,
                                psa_key_data_format_t format,
                                const uint8_t *data,
                                size_t data_length,
                                psa_key_id_t *key);

psa_status_t psa_export_key_ext(psa_key_id_t key,
                          psa_key_data_format_t format,
                          const uint8_t *data,
                          size_t data_size,
                          size_t *data_length);

When importing a key where the key data includes some of the key attributes, such as the key type or key policy, any values supplied in the key attributes object much match the values in the imported key data. Specific rules for combining the key policy attributes from the provided attributes and the key data will be defined for each supported key format.

[athoelke]

With only two encodings (plus the 'any' one), the API might be easier to use by just explicitly defining all of the formats (but retaining the field structure)? E.g.:

#define PSA_KEY_FORMAT_RSA_PUBLIC_KEY_ANY          ((psa_key_data_format_t) 0x0010)
#define PSA_KEY_FORMAT_RSA_PUBLIC_KEY_DER          ((psa_key_data_format_t) 0x0011)
#define PSA_KEY_FORMAT_RSA_PUBLIC_KEY_PEM          ((psa_key_data_format_t) 0x0012)
#define PSA_KEY_FORMAT_SUBJECT_PUBLIC_KEY_INFO_ANY ((psa_key_data_format_t) 0x0020)
#define PSA_KEY_FORMAT_SUBJECT_PUBLIC_KEY_INFO_DER ((psa_key_data_format_t) 0x0021)
#define PSA_KEY_FORMAT_SUBJECT_PUBLIC_KEY_INFO_PEM ((psa_key_data_format_t) 0x0022)
#define PSA_KEY_FORMAT_RSA_PRIVATE_KEY_ANY         ((psa_key_data_format_t) 0x0030)
...

[michaelthomasj]

@athoelke , when do you plant/expect to get this merged ?

[athoelke]

when do you plant/expect to get this merged ?

I would be happy to include this in a 1.3 update (along with integration of the PAKE API).

However, I was hoping for some feedback on the proposed draft API (above), in particular regarding some of the perhaps-arbitrary choices relating to the design of the format specifier, and the balance between flexible and rigid interpretation of the format value on import and export.

I'd prefer to have a somewhat-agreed draft to base the specification text on, in order to reduce the risk that significant rewriting is needed if a reason to redesign the API only comes to light after creating the specification text.