openssl/doc/designs/evp_skey.md

EVP_SKEY Design

The current API assumes that a byte buffer is always available and sufficient to represent a symmetric key. But for hardware-backed providers, such as PKCS#11 or TPM, keys generally cannot be exported and need to be represented via some kind of handle or id.

This design proposes the use of an opaque type to represent symmetric keys. It doesn't cover any extra parameters (e.g. AEAD-related nonces).

When a provider allows key exporting, the internal representation of the EVP_SKEY may be turned back into an array of bytes, that can be cached and become usable by any current cipher supporting symmetric keys in byte form. In other cases it may happen to be a set of provider-specific parameters, compatible only with the particular provider.

For clarity, when cipher algorithms are mentioned later, the implicit assumption is that any algorithm accepting a symmetric key should be able to deal with an EVP_SKEY object from the same provider.

Libcrypto perspective

EVP_SKEY objects can be a wrapper around a raw key stored in an internal buffer.

A wrapper EVP_SKEY object stores the key and the key length in an internal structure. The key management-backed EVP_SKEY object contains 2 pointers: a pointer to an EVP_SKEYMGMT object and an opaque pointer to a provider specific object that represents the key. EVP_SKEYMGMT specifies what parameters are acceptable by the chosen provider and may be used by specific algorithms of this provider. These parameters are represented as an array of OSSL_PARAM. We create an API to manage the lifecycle of EVP_SKEY objects (see below).

Once an EVP_SKEY object is created it can be used in place of a raw key. The new APIs for this purpose are designed to match the existing ones but use an EVP_SKEY object as an argument. For usability reasons we keep IV and IV length as separate arguments in the new API even though they could have been provided as an element of a OSSL_PARAM array argument.

There are other parameters that some but not all ciphers take. You'll find a substantial list in the manual for EVP_CipherInit(), and they are suitable for passing via OSSL_PARAM. The difference here is that those params are not provider-specific but algorithm-specific or operation-specific.

Things that were previously passed to backend implementations with ctrl functions have become EVP_CIPHER_CTX level OSSL_PARAM items with providers.

If an operation is available only from a different provider than the one that generated the EVP_SKEY object, then the management code will attempt an export (and possibly import) operation of the key, including when the target provider offers only legacy APIs that accept a raw key only. If export fails the operation fails.

Provider perspective

For dealing with opaque keys, we provide a new structure - EVP_SKEYMGMT, similar to EVP_KEYMGMT.

On the provider end, encryption and decryption implementations will receive an opaque pointer similar to the provkey pointer used with asymmetric operations. This pointer is a result of processing an array of OSSL_PARAM by a EVP_SKEYMGMT operation (import, generate, etc..).

Once created, the EVP_SKEY structure can be exported to the extent the provider and EVP_SKEYMGMT supports it. There is no guarantee that the result of export-import operation is the same as the initial set of the parameters.

The EVP_SKEY object generally has a type, however there is a generic catchall secret type for key that are not tied to a specific operation. Whether a key is typed depends on how it was created.

Relationships between Objects

We have an EVP_CIPHER object associated with a particular provider. An EVP_SKEY object should be compatible with the particular EVP_CIPHER object (the check is done via comparing the providers). After that it can be used within a EVP_CIPHER_CTX object associated with the same EVP_CIPHER object.

The way to reuse the key with another provider is through an export/import process. As mentioned before, it may fail. The way to reuse it with a different cipher context is EVP_SKEY_up_ref.

Key management

The provider operating EVP_SKEY objects has to implement a separate symmetric key management to deal with the opaque object.

Allocation and freeing

EVP_SKEY object doesn't reuse the pattern 'allocate - assign', these operations are combined.

EVP_SKEY *EVP_SKEY_generate(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
                            const char *propquery, const OSSL_PARAM *params);
EVP_SKEY *EVP_SKEY_import(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
                          const char *propquery,
                          int selection, const OSSL_PARAM *params);
EVP_SKEY *EVP_SKEY_import_raw(OSSL_LIB_CTX *libctx, const char *skeymgmtname,
                              const char *key, size_t keylen,
                              const char *propquery);
int EVP_SKEY_up_ref(EVP_SKEY *skey);
void EVP_SKEY_free(EVP_SKEY *skey);

Exporting the key object

int EVP_SKEY_export(const EVP_SKEY *skey, int selection,
                    OSSL_CALLBACK *export_cb, void *export_cbarg);

Using EVP_SKEY in cipher operations

We provide a function

int EVP_CipherInit_SKEY(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher,
                        EVP_SKEY *skey, const unsigned char *iv, size_t iv_len,
                        int enc, const OSSL_PARAM params[]);

similar to EVP_CipherInit_ex2. After call to this function, the normal EVP_CipherUpdate/EVP_CipherFinal API can be used.

Using EVP_SKEY with EVP_MAC

int EVP_MAC_init_SKEY(EVP_MAC_CTX *ctx, const EVP_SKEY *skey,
                      const OSSL_PARAM params[]);

similar to EVP_MAC_init

API to derive an EVP_SKEY object

This part is delayed for a while because the proposed API doesn't fit well with TLS KDFs deriving multiple keys simultaneously.