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