1*e7be843bSPierre ProncheryHandling AlgorithmIdentifier and its parameters with provider operations 2*e7be843bSPierre Pronchery======================================================================== 3*e7be843bSPierre Pronchery 4*e7be843bSPierre ProncheryQuick background 5*e7be843bSPierre Pronchery---------------- 6*e7be843bSPierre Pronchery 7*e7be843bSPierre ProncheryWe currently only support passing the AlgorithmIdentifier (`X509_ALGOR`) 8*e7be843bSPierre Proncheryparameter field to symmetric cipher provider implementations. We currently 9*e7be843bSPierre Proncheryonly support getting full AlgorithmIdentifier (`X509_ALGOR`) from signature 10*e7be843bSPierre Proncheryprovider implementations. 11*e7be843bSPierre Pronchery 12*e7be843bSPierre ProncheryWe do support passing them to legacy implementations of other types of 13*e7be843bSPierre Proncheryoperation algorithms as well, but it's done in a way that can't be supported 14*e7be843bSPierre Proncherywith providers, because it involves sharing specific structures between 15*e7be843bSPierre Proncherylibcrypto and the backend implementation. 16*e7be843bSPierre Pronchery 17*e7be843bSPierre ProncheryFor a longer background and explanation, see 18*e7be843bSPierre Pronchery[Background / tl;dr](#background-tldr) at the end of this design. 19*e7be843bSPierre Pronchery 20*e7be843bSPierre ProncheryEstablish OSSL_PARAM keys that any algorithms may become aware of 21*e7be843bSPierre Pronchery----------------------------------------------------------------- 22*e7be843bSPierre Pronchery 23*e7be843bSPierre ProncheryWe already have known parameter keys: 24*e7be843bSPierre Pronchery 25*e7be843bSPierre Pronchery- "algor_id_param", also known as the macro `OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS`. 26*e7be843bSPierre Pronchery 27*e7be843bSPierre Pronchery This is currently only specified for `EVP_CIPHER`, in support of 28*e7be843bSPierre Pronchery `EVP_CIPHER_param_to_asn1()` and `EVP_CIPHER_asn1_to_param()` 29*e7be843bSPierre Pronchery 30*e7be843bSPierre Pronchery- "algorithm-id", also known as the macro `OSSL_SIGNATURE_PARAM_ALGORITHM_ID`. 31*e7be843bSPierre Pronchery 32*e7be843bSPierre ProncheryThis design proposes: 33*e7be843bSPierre Pronchery 34*e7be843bSPierre Pronchery1. Adding a parameter key "algorithm-id-params", to replace "algor_id_param", 35*e7be843bSPierre Pronchery and deprecate the latter. 36*e7be843bSPierre Pronchery2. Making both "algorithm-id" and "algorithm-id-params" generically available, 37*e7be843bSPierre Pronchery rather than only tied to `EVP_SIGNATURE` ("algorithm-id") or `EVP_CIPHER` 38*e7be843bSPierre Pronchery ("algor_id_param"). 39*e7be843bSPierre Pronchery 40*e7be843bSPierre ProncheryThis way, these parameters can be used in the exact same manner with other 41*e7be843bSPierre Proncheryoperations, with the value of the AlgorithmIdentifier as well as its 42*e7be843bSPierre Proncheryparameters as octet strings, to be used and interpreted by applications and 43*e7be843bSPierre Proncheryprovider implementations alike in whatever way they see fit. 44*e7be843bSPierre Pronchery 45*e7be843bSPierre ProncheryApplications can choose to add these in an `OSSL_PARAM` array, to be passed 46*e7be843bSPierre Proncherywith the multitude of initialization functions that take such an array, or 47*e7be843bSPierre Proncheryusing specific operation `OSSL_PARAM` setters and getters (such as 48*e7be843bSPierre Pronchery`EVP_PKEY_CTX_set_params`), or using other available convenience functions 49*e7be843bSPierre Pronchery(see below). 50*e7be843bSPierre Pronchery 51*e7be843bSPierre ProncheryThese parameter will have to be documented in the following files: 52*e7be843bSPierre Pronchery 53*e7be843bSPierre Pronchery- `doc/man7/provider-asym_cipher.pod` 54*e7be843bSPierre Pronchery- `doc/man7/provider-cipher.pod` 55*e7be843bSPierre Pronchery- `doc/man7/provider-digest.pod` 56*e7be843bSPierre Pronchery- `doc/man7/provider-kdf.pod` 57*e7be843bSPierre Pronchery- `doc/man7/provider-kem.pod` 58*e7be843bSPierre Pronchery- `doc/man7/provider-keyexch.pod` 59*e7be843bSPierre Pronchery- `doc/man7/provider-mac.pod` 60*e7be843bSPierre Pronchery- `doc/man7/provider-signature.pod` 61*e7be843bSPierre Pronchery 62*e7be843bSPierre ProncheryThat should cover all algorithms that are, or should be possible to fetch by 63*e7be843bSPierre ProncheryAlgorithmIdentifier.algorithm, and for which there's potentially a relevant 64*e7be843bSPierre ProncheryAlgorithmIdentifier.parameters field. 65*e7be843bSPierre Pronchery 66*e7be843bSPierre ProncheryWe may arguably want to consider `doc/man7/provider-keymgmt.pod` too, but 67*e7be843bSPierre Proncheryan AlgorithmIdentifier that's attached directly to a key is usually part of 68*e7be843bSPierre Proncherya PrivKeyInfo or SubjectPublicKeyInfo structure, and those are handled by 69*e7be843bSPierre Proncheryencoders and decoders as those see fit, and there's no tangible reason why 70*e7be843bSPierre Proncherythat would have to change. 71*e7be843bSPierre Pronchery 72*e7be843bSPierre ProncheryPublic convenience API 73*e7be843bSPierre Pronchery---------------------- 74*e7be843bSPierre Pronchery 75*e7be843bSPierre ProncheryFor convenience, the following set of functions would be added to pass the 76*e7be843bSPierre ProncheryAlgorithmIdentifier parameter data to diverse operations, or to retrieve 77*e7be843bSPierre Proncherysuch parameter data from them. 78*e7be843bSPierre Pronchery 79*e7be843bSPierre Pronchery``` C 80*e7be843bSPierre Pronchery/* 81*e7be843bSPierre Pronchery * These two would essentially be aliases for EVP_CIPHER_param_to_asn1() 82*e7be843bSPierre Pronchery * and EVP_CIPHER_asn1_to_param(). 83*e7be843bSPierre Pronchery */ 84*e7be843bSPierre ProncheryEVP_CIPHER_CTX_set_algor_params(EVP_CIPHER_CTX *ctx, const X509_ALGOR *alg); 85*e7be843bSPierre ProncheryEVP_CIPHER_CTX_get_algor_params(EVP_CIPHER_CTX *ctx, X509_ALGOR *alg); 86*e7be843bSPierre ProncheryEVP_CIPHER_CTX_get_algor(EVP_CIPHER_CTX *ctx, X509_ALGOR **alg); 87*e7be843bSPierre Pronchery 88*e7be843bSPierre ProncheryEVP_MD_CTX_set_algor_params(EVP_MD_CTX *ctx, const X509_ALGOR *alg); 89*e7be843bSPierre ProncheryEVP_MD_CTX_get_algor_params(EVP_MD_CTX *ctx, X509_ALGOR *alg); 90*e7be843bSPierre ProncheryEVP_MD_CTX_get_algor(EVP_MD_CTX *ctx, X509_ALGOR **alg); 91*e7be843bSPierre Pronchery 92*e7be843bSPierre ProncheryEVP_MAC_CTX_set_algor_params(EVP_MAC_CTX *ctx, const X509_ALGOR *alg); 93*e7be843bSPierre ProncheryEVP_MAC_CTX_get_algor_params(EVP_MAC_CTX *ctx, X509_ALGOR *alg); 94*e7be843bSPierre ProncheryEVP_MAC_CTX_get_algor(EVP_MAC_CTX *ctx, X509_ALGOR **alg); 95*e7be843bSPierre Pronchery 96*e7be843bSPierre ProncheryEVP_KDF_CTX_set_algor_params(EVP_KDF_CTX *ctx, const X509_ALGOR *alg); 97*e7be843bSPierre ProncheryEVP_KDF_CTX_get_algor_params(EVP_KDF_CTX *ctx, X509_ALGOR *alg); 98*e7be843bSPierre ProncheryEVP_KDF_CTX_get_algor(EVP_KDF_CTX *ctx, X509_ALGOR **alg); 99*e7be843bSPierre Pronchery 100*e7be843bSPierre ProncheryEVP_PKEY_CTX_set_algor_params(EVP_PKEY_CTX *ctx, const X509_ALGOR *alg); 101*e7be843bSPierre ProncheryEVP_PKEY_CTX_get_algor_params(EVP_PKEY_CTX *ctx, X509_ALGOR *alg); 102*e7be843bSPierre ProncheryEVP_PKEY_CTX_get_algor(EVP_PKEY_CTX *ctx, X509_ALGOR **alg); 103*e7be843bSPierre Pronchery``` 104*e7be843bSPierre Pronchery 105*e7be843bSPierre ProncheryNote that all might not need to be added immediately, depending on if they 106*e7be843bSPierre Proncheryare considered useful or not. For future proofing, however, they should 107*e7be843bSPierre Proncheryprobably all be added. 108*e7be843bSPierre Pronchery 109*e7be843bSPierre ProncheryRequirements on the providers 110*e7be843bSPierre Pronchery----------------------------- 111*e7be843bSPierre Pronchery 112*e7be843bSPierre ProncheryProviders that implement ciphers or any operation that uses asymmetric keys 113*e7be843bSPierre Proncherywill have to implement support for passing AlgorithmIdentifier parameter 114*e7be843bSPierre Proncherydata, and will have to process that data in whatever manner that's necessary 115*e7be843bSPierre Proncheryto meet the standards for that operation. 116*e7be843bSPierre Pronchery 117*e7be843bSPierre ProncheryFallback strategies 118*e7be843bSPierre Pronchery------------------- 119*e7be843bSPierre Pronchery 120*e7be843bSPierre ProncheryThere are no possible fallback strategies, which is fine, considering that 121*e7be843bSPierre Proncherycurrent provider functionality doesn't support passing AlgorithmIdentifier 122*e7be843bSPierre Proncheryparameter data at all (except for `EVP_CIPHER`), and therefore do not work 123*e7be843bSPierre Proncheryat all when such parameter data needs to be passed. 124*e7be843bSPierre Pronchery 125*e7be843bSPierre Pronchery----- 126*e7be843bSPierre Pronchery 127*e7be843bSPierre Pronchery----- 128*e7be843bSPierre Pronchery 129*e7be843bSPierre ProncheryBackground / tl;dr 130*e7be843bSPierre Pronchery------------------ 131*e7be843bSPierre Pronchery 132*e7be843bSPierre Pronchery### AlgorithmIdenfier parameter and how it's used 133*e7be843bSPierre Pronchery 134*e7be843bSPierre ProncheryOpenSSL has historically done a few tricks to not have to pass 135*e7be843bSPierre ProncheryAlgorithmIdenfier parameter data to the backend implementations of 136*e7be843bSPierre Proncherycryptographic operations: 137*e7be843bSPierre Pronchery 138*e7be843bSPierre Pronchery- In some cases, they were passed as part of the lower level key structure 139*e7be843bSPierre Pronchery (for example, the `RSA` structure can also carry RSA-PSS parameters). 140*e7be843bSPierre Pronchery- In the `EVP_CIPHER` case, there is functionality to pass the parameter 141*e7be843bSPierre Pronchery data specifically. 142*e7be843bSPierre Pronchery- For asymmetric key operations, PKCS#7 and CMS support was added as 143*e7be843bSPierre Pronchery `EVP_PKEY` ctrls. 144*e7be843bSPierre Pronchery 145*e7be843bSPierre ProncheryWith providers, some of that support was retained, but not others. Most 146*e7be843bSPierre Proncherycrucially, the `EVP_PKEY` ctrls for PKCS#7 and CMS were not retained, 147*e7be843bSPierre Proncherybecause the way they were implemented violated the principle that provider 148*e7be843bSPierre Proncheryimplementations *MUST NOT* share complex OpenSSL specific structures with 149*e7be843bSPierre Proncherylibcrypto. 150*e7be843bSPierre Pronchery 151*e7be843bSPierre Pronchery### Usage examples 152*e7be843bSPierre Pronchery 153*e7be843bSPierre ProncheryQuite a lot of the available examples today revolve around CMS, with a 154*e7be843bSPierre Proncherynumber of RFCs that specify what parameters should be passed with certain 155*e7be843bSPierre Proncheryoperations / algorithms. This list is not exhaustive, the reader is 156*e7be843bSPierre Proncheryencouraged to research further usages. 157*e7be843bSPierre Pronchery 158*e7be843bSPierre Pronchery- [DSA](https://www.rfc-editor.org/rfc/rfc3370#section-3.1) signatures 159*e7be843bSPierre Pronchery typically have the domain parameters *p*, *q* and *g*. 160*e7be843bSPierre Pronchery- [RC2 key wrap](https://www.rfc-editor.org/rfc/rfc3370#section-4.3.2) 161*e7be843bSPierre Pronchery- [PBKDF2](https://www.rfc-editor.org/rfc/rfc3370#section-4.4.1) 162*e7be843bSPierre Pronchery- [3DES-CBC](https://www.rfc-editor.org/rfc/rfc3370#section-5.1) 163*e7be843bSPierre Pronchery- [RC2-CBC](https://www.rfc-editor.org/rfc/rfc3370#section-5.2) 164*e7be843bSPierre Pronchery 165*e7be843bSPierre Pronchery- [GOST 28147-89](https://www.rfc-editor.org/rfc/rfc4490.html#section-5.1) 166*e7be843bSPierre Pronchery 167*e7be843bSPierre Pronchery- [RSA-OAEP](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.1) 168*e7be843bSPierre Pronchery- [RSA-PSS](https://www.rfc-editor.org/rfc/rfc8017#appendix-A.2.3) 169*e7be843bSPierre Pronchery 170*e7be843bSPierre Pronchery- [XOR-MD5](https://www.rfc-editor.org/rfc/rfc6210.html) is experimental, 171*e7be843bSPierre Pronchery but it does demonstrate the possibility of a parametrized hash algorithm. 172*e7be843bSPierre Pronchery 173*e7be843bSPierre ProncherySome of it can be claimed to already have support in OpenSSL. However, this 174*e7be843bSPierre Proncheryis with old libcrypto code that has special knowledge of the algorithms that 175*e7be843bSPierre Proncheryare involved. 176