1Passing AlgorithmIdentifier parameters to operations
2====================================================
3
4Quick background
5----------------
6
7We currently only support passing the AlgorithmIdentifier (`X509_ALGOR`)
8parameter field to symmetric cipher provider implementations.
9
10We do support passing them to legacy implementations of other types of
11operation algorithms as well, but it's done in a way that can't be supported
12with providers, because it involves sharing specific structures between
13libcrypto and the backend implementation.
14
15For a longer background and explanation, see
16[Background / tl;dr](#background-tldr) at the end of this design.
17
18Establish an OSSL_PARAM key that any algorithms may become aware of
19-------------------------------------------------------------------
20
21We already have a parameter key, but it's currently only specified for
22`EVP_CIPHER`, in support of `EVP_CIPHER_param_to_asn1()` and
23`EVP_CIPHER_asn1_to_param()`.
24
25"alg_id_param", also known as the macro `OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS`
26
27This parameter can be used in the exact same manner with other operations,
28with the value of the AlgorithmIdentifier parameter as an octet string, to
29be interpreted by the implementations in whatever way they see fit.
30
31Applications can choose to add these in an `OSSL_PARAM` array, to be passed
32with the multitude of initialization functions that take such an array, or
33using specific operation `OSSL_PARAM` setters and getters (such as
34`EVP_PKEY_CTX_set_params`), or using other available convenience functions
35(see below).
36
37This parameter will have to be documented in the following files:
38
39- `doc/man7/provider-asym_cipher.pod`
40- `doc/man7/provider-cipher.pod`
41- `doc/man7/provider-digest.pod`
42- `doc/man7/provider-kdf.pod`
43- `doc/man7/provider-kem.pod`
44- `doc/man7/provider-keyexch.pod`
45- `doc/man7/provider-mac.pod`
46- `doc/man7/provider-signature.pod`
47
48That should cover all algorithms that are, or should be possible to fetch by
49AlgorithmIdentifier.algorithm, and for which there's potentially a relevant
50AlgorithmIdentifier.parameters field.
51
52We may arguably want to consider `doc/man7/provider-keymgmt.pod` too, but
53an AlgorithmIdentifier that's attached directly to a key is usually part of
54a PrivKeyInfo or SubjectPublicKeyInfo structure, and those are handled by
55encoders and decoders as those see fit, and there's no tangible reason why
56that would have to change.
57
58Public convenience API
59----------------------
60
61For convenience, the following set of functions would be added to pass the
62AlgorithmIdentifier parameter data to diverse operations, or to retrieve
63such parameter data from them.
64
65``` C
66/*
67 * These two would essentially be aliases for EVP_CIPHER_param_to_asn1()
68 * and EVP_CIPHER_asn1_to_param().
69 */
70EVP_CIPHER_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
71EVP_CIPHER_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
72
73EVP_MD_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
74EVP_MD_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
75
76EVP_MAC_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
77EVP_MAC_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
78
79EVP_KDF_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
80EVP_KDF_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
81
82EVP_PKEY_CTX_set_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
83EVP_PKEY_CTX_get_algor_param(EVP_PKEY_CTX *ctx, X509_ALGOR *alg);
84```
85
86Note that all might not need to be added immediately, depending on if they
87are considered useful or not.  For future proofing, however, they should
88probably all be added.
89
90Requirements on the providers
91-----------------------------
92
93Providers that implement ciphers or any operation that uses asymmetric keys
94will have to implement support for passing AlgorithmIdentifier parameter
95data, and will have to process that data in whatever manner that's necessary
96to meet the standards for that operation.
97
98Fallback strategies
99-------------------
100
101There are no possible fallback strategies, which is fine, considering that
102current provider functionality doesn't support passing AlgorithmIdentifier
103parameter data at all (except for `EVP_CIPHER`), and therefore do not work
104at all when such parameter data needs to be passed.
105
106-----
107
108-----
109
110Background / tl;dr
111------------------
112
113### AlgorithmIdenfier parameter and how it's used
114
115OpenSSL has historically done a few tricks to not have to pass
116AlgorithmIdenfier parameter data to the backend implementations of
117cryptographic operations:
118
119- In some cases, they were passed as part of the lower level key structure
120  (for example, the `RSA` structure can also carry RSA-PSS parameters).
121- In the `EVP_CIPHER` case, there is functionality to pass the parameter
122  data specifically.
123- For asymmetric key operations, PKCS#7 and CMS support was added as
124  `EVP_PKEY` ctrls.
125
126With providers, some of that support was retained, but not others.  Most
127crucially, the `EVP_PKEY` ctrls for PKCS#7 and CMS were not retained,
128because the way they were implemented violated the principle that provider
129implementations *MUST NOT* share complex OpenSSL specific structures with
130libcrypto.
131
132### Usage examples
133
134Quite a lot of the available examples today revolve around CMS, with a
135number of RFCs that specify what parameters should be passed with certain
136operations / algorithms.  This list is not exhaustive, the reader is
137encouraged to research further usages.
138
139- [DSA](https://www.rfc-editor.org/rfc/rfc3370#section-3.1) signatures
140  typically have the domain parameters *p*, *q* and *g*.
141- [RC2 key wrap](https://www.rfc-editor.org/rfc/rfc3370#section-4.3.2)
142- [PBKDF2](https://www.rfc-editor.org/rfc/rfc3370#section-4.4.1)
143- [3DES-CBC](https://www.rfc-editor.org/rfc/rfc3370#section-5.1)
144- [RC2-CBC](https://www.rfc-editor.org/rfc/rfc3370#section-5.2)
145
146- [GOST 28147-89](https://www.rfc-editor.org/rfc/rfc4490.html#section-5.1)
147
148- [RSA-OAEP](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.1)
149- [RSA-PSS](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.3)
150
151- [XOR-MD5](https://www.rfc-editor.org/rfc/rfc6210.html) is experimental,
152  but it does demonstrate the possibility of a parametrized hash algorithm.
153
154Some of it can be claimed to already have support in OpenSSL.  However, this
155is with old libcrypto code that has special knowledge of the algorithms that
156are involved.
157