openssl/doc/designs/passing-algorithmidentifier-parameters.md

Handling AlgorithmIdentifier and its parameters with provider operations

Quick background

We currently only support passing the AlgorithmIdentifier (X509_ALGOR) parameter field to symmetric cipher provider implementations. We currently only support getting full AlgorithmIdentifier (X509_ALGOR) from signature provider implementations.

We do support passing them to legacy implementations of other types of operation algorithms as well, but it's done in a way that can't be supported with providers, because it involves sharing specific structures between libcrypto and the backend implementation.

For a longer background and explanation, see Background / tl;dr at the end of this design.

Establish OSSL_PARAM keys that any algorithms may become aware of

We already have known parameter keys:

• "algor_id_param", also known as the macro OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS.

  This is currently only specified for EVP_CIPHER, in support of EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param()

• "algorithm-id", also known as the macro OSSL_SIGNATURE_PARAM_ALGORITHM_ID.

This design proposes:

1. Adding a parameter key "algorithm-id-params", to replace "algor_id_param", and deprecate the latter.
2. Making both "algorithm-id" and "algorithm-id-params" generically available, rather than only tied to EVP_SIGNATURE ("algorithm-id") or EVP_CIPHER ("algor_id_param").

This way, these parameters can be used in the exact same manner with other operations, with the value of the AlgorithmIdentifier as well as its parameters as octet strings, to be used and interpreted by applications and provider implementations alike in whatever way they see fit.

Applications can choose to add these in an OSSL_PARAM array, to be passed with the multitude of initialization functions that take such an array, or using specific operation OSSL_PARAM setters and getters (such as EVP_PKEY_CTX_set_params), or using other available convenience functions (see below).

These parameter will have to be documented in the following files:

• doc/man7/provider-asym_cipher.pod
• doc/man7/provider-cipher.pod
• doc/man7/provider-digest.pod
• doc/man7/provider-kdf.pod
• doc/man7/provider-kem.pod
• doc/man7/provider-keyexch.pod
• doc/man7/provider-mac.pod
• doc/man7/provider-signature.pod

That should cover all algorithms that are, or should be possible to fetch by AlgorithmIdentifier.algorithm, and for which there's potentially a relevant AlgorithmIdentifier.parameters field.

We may arguably want to consider doc/man7/provider-keymgmt.pod too, but an AlgorithmIdentifier that's attached directly to a key is usually part of a PrivKeyInfo or SubjectPublicKeyInfo structure, and those are handled by encoders and decoders as those see fit, and there's no tangible reason why that would have to change.

Public convenience API

For convenience, the following set of functions would be added to pass the AlgorithmIdentifier parameter data to diverse operations, or to retrieve such parameter data from them.

/*
 * These two would essentially be aliases for EVP_CIPHER_param_to_asn1()
 * and EVP_CIPHER_asn1_to_param().
 */
EVP_CIPHER_CTX_set_algor_params(EVP_CIPHER_CTX *ctx, const X509_ALGOR *alg);
EVP_CIPHER_CTX_get_algor_params(EVP_CIPHER_CTX *ctx, X509_ALGOR *alg);
EVP_CIPHER_CTX_get_algor(EVP_CIPHER_CTX *ctx, X509_ALGOR **alg);

EVP_MD_CTX_set_algor_params(EVP_MD_CTX *ctx, const X509_ALGOR *alg);
EVP_MD_CTX_get_algor_params(EVP_MD_CTX *ctx, X509_ALGOR *alg);
EVP_MD_CTX_get_algor(EVP_MD_CTX *ctx, X509_ALGOR **alg);

EVP_MAC_CTX_set_algor_params(EVP_MAC_CTX *ctx, const X509_ALGOR *alg);
EVP_MAC_CTX_get_algor_params(EVP_MAC_CTX *ctx, X509_ALGOR *alg);
EVP_MAC_CTX_get_algor(EVP_MAC_CTX *ctx, X509_ALGOR **alg);

EVP_KDF_CTX_set_algor_params(EVP_KDF_CTX *ctx, const X509_ALGOR *alg);
EVP_KDF_CTX_get_algor_params(EVP_KDF_CTX *ctx, X509_ALGOR *alg);
EVP_KDF_CTX_get_algor(EVP_KDF_CTX *ctx, X509_ALGOR **alg);

EVP_PKEY_CTX_set_algor_params(EVP_PKEY_CTX *ctx, const X509_ALGOR *alg);
EVP_PKEY_CTX_get_algor_params(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
EVP_PKEY_CTX_get_algor(EVP_PKEY_CTX *ctx, X509_ALGOR **alg);

Note that all might not need to be added immediately, depending on if they are considered useful or not. For future proofing, however, they should probably all be added.

Requirements on the providers

Providers that implement ciphers or any operation that uses asymmetric keys will have to implement support for passing AlgorithmIdentifier parameter data, and will have to process that data in whatever manner that's necessary to meet the standards for that operation.

Fallback strategies

There are no possible fallback strategies, which is fine, considering that current provider functionality doesn't support passing AlgorithmIdentifier parameter data at all (except for EVP_CIPHER), and therefore do not work at all when such parameter data needs to be passed.

---

---

Background / tl;dr

AlgorithmIdenfier parameter and how it's used

OpenSSL has historically done a few tricks to not have to pass AlgorithmIdenfier parameter data to the backend implementations of cryptographic operations:

• In some cases, they were passed as part of the lower level key structure (for example, the RSA structure can also carry RSA-PSS parameters).
• In the EVP_CIPHER case, there is functionality to pass the parameter data specifically.
• For asymmetric key operations, PKCS#7 and CMS support was added as EVP_PKEY ctrls.

With providers, some of that support was retained, but not others. Most crucially, the EVP_PKEY ctrls for PKCS#7 and CMS were not retained, because the way they were implemented violated the principle that provider implementations MUST NOT share complex OpenSSL specific structures with libcrypto.

Usage examples

Quite a lot of the available examples today revolve around CMS, with a number of RFCs that specify what parameters should be passed with certain operations / algorithms. This list is not exhaustive, the reader is encouraged to research further usages.

• DSA signatures typically have the domain parameters p, q and g.

• RC2 key wrap

• PBKDF2

• 3DES-CBC

• RC2-CBC

• GOST 28147-89

• RSA-OAEP

• RSA-PSS

• XOR-MD5 is experimental, but it does demonstrate the possibility of a parametrized hash algorithm.

Some of it can be claimed to already have support in OpenSSL. However, this is with old libcrypto code that has special knowledge of the algorithms that are involved.