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](#background-tldr) 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.

``` C
/*
 * 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](https://www.rfc-editor.org/rfc/rfc3370#section-3.1) signatures
  typically have the domain parameters *p*, *q* and *g*.
- [RC2 key wrap](https://www.rfc-editor.org/rfc/rfc3370#section-4.3.2)
- [PBKDF2](https://www.rfc-editor.org/rfc/rfc3370#section-4.4.1)
- [3DES-CBC](https://www.rfc-editor.org/rfc/rfc3370#section-5.1)
- [RC2-CBC](https://www.rfc-editor.org/rfc/rfc3370#section-5.2)

- [GOST 28147-89](https://www.rfc-editor.org/rfc/rfc4490.html#section-5.1)

- [RSA-OAEP](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.1)
- [RSA-PSS](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.3)

- [XOR-MD5](https://www.rfc-editor.org/rfc/rfc6210.html) 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.