1*e7be843bSPierre ProncheryFetching composite algorithms and using them - adding the bits still missing 2*e7be843bSPierre Pronchery============================================================================ 3*e7be843bSPierre Pronchery 4*e7be843bSPierre ProncheryQuick background 5*e7be843bSPierre Pronchery---------------- 6*e7be843bSPierre Pronchery 7*e7be843bSPierre ProncheryWe currently support - at least in the public libcrypto API - explicitly 8*e7be843bSPierre Proncheryfetching composite algorithms (such as AES-128-CBC or HMAC-SHA256), and 9*e7be843bSPierre Proncheryusing them in most cases. In some cases (symmetric ciphers), our providers 10*e7be843bSPierre Proncheryalso provide them. 11*e7be843bSPierre Pronchery 12*e7be843bSPierre ProncheryHowever, there is one class of algorithms where the support for *using* 13*e7be843bSPierre Proncheryexplicitly fetched algorithms is lacking: asymmetric algorithms. 14*e7be843bSPierre Pronchery 15*e7be843bSPierre ProncheryFor a longer background and explanation, see 16*e7be843bSPierre Pronchery[Background / tl;dr](#background-tldr) at the end of this design. 17*e7be843bSPierre Pronchery 18*e7be843bSPierre ProncheryPublic API - Add variants of `EVP_PKEY_CTX` initializers 19*e7be843bSPierre Pronchery-------------------------------------------------------- 20*e7be843bSPierre Pronchery 21*e7be843bSPierre ProncheryAs far as this design is concerned, these API sets are affected: 22*e7be843bSPierre Pronchery 23*e7be843bSPierre Pronchery- SIGNATURE 24*e7be843bSPierre Pronchery- ASYM_CIPHER 25*e7be843bSPierre Pronchery- KEYEXCH 26*e7be843bSPierre Pronchery 27*e7be843bSPierre ProncheryThe proposal is to add these initializer functions: 28*e7be843bSPierre Pronchery 29*e7be843bSPierre Pronchery``` C 30*e7be843bSPierre Proncheryint EVP_PKEY_sign_init_ex2(EVP_PKEY_CTX *pctx, 31*e7be843bSPierre Pronchery EVP_SIGNATURE *algo, const OSSL_PARAM params[]); 32*e7be843bSPierre Proncheryint EVP_PKEY_verify_init_ex2(EVP_PKEY_CTX *pctx, 33*e7be843bSPierre Pronchery EVP_SIGNATURE *algo, const OSSL_PARAM params[]); 34*e7be843bSPierre Proncheryint EVP_PKEY_verify_recover_init_ex2(EVP_PKEY_CTX *pctx, 35*e7be843bSPierre Pronchery EVP_SIGNATURE *algo, const OSSL_PARAM params[]); 36*e7be843bSPierre Pronchery 37*e7be843bSPierre Proncheryint EVP_PKEY_encrypt_init_ex2(EVP_PKEY_CTX *ctx, EVP_ASYM_CIPHER *asymciph, 38*e7be843bSPierre Pronchery const OSSL_PARAM params[]); 39*e7be843bSPierre Proncheryint EVP_PKEY_decrypt_init_ex2(EVP_PKEY_CTX *ctx, EVP_ASYM_CIPHER *asymciph, 40*e7be843bSPierre Pronchery const OSSL_PARAM params[]); 41*e7be843bSPierre Pronchery 42*e7be843bSPierre Proncheryint EVP_PKEY_derive_init_ex2(EVP_PKEY_CTX *ctx, EVP_KEYEXCH *exchange, 43*e7be843bSPierre Pronchery const OSSL_PARAM params[]); 44*e7be843bSPierre Pronchery``` 45*e7be843bSPierre Pronchery 46*e7be843bSPierre ProncheryDetailed proposal for these APIs will be or are prepared in other design 47*e7be843bSPierre Proncherydocuments: 48*e7be843bSPierre Pronchery 49*e7be843bSPierre Pronchery- [Functions for explicitly fetched signature algorithms] 50*e7be843bSPierre Pronchery- [Functions for explicitly fetched asym-cipher algorithms] (not yet designed) 51*e7be843bSPierre Pronchery- [Functions for explicitly fetched keyexch algorithms] (not yet designed) 52*e7be843bSPierre Pronchery 53*e7be843bSPierre Pronchery----- 54*e7be843bSPierre Pronchery 55*e7be843bSPierre Pronchery----- 56*e7be843bSPierre Pronchery 57*e7be843bSPierre ProncheryBackground / tl;dr 58*e7be843bSPierre Pronchery------------------ 59*e7be843bSPierre Pronchery 60*e7be843bSPierre Pronchery### What is a composite algorithm? 61*e7be843bSPierre Pronchery 62*e7be843bSPierre ProncheryA composite algorithm is an algorithm that's composed of more than one other 63*e7be843bSPierre Proncheryalgorithm. In OpenSSL parlance with a focus on signatures, they have been 64*e7be843bSPierre Proncheryknown as "sigalgs", but this is really broader than just signature algorithms. 65*e7be843bSPierre ProncheryExamples are: 66*e7be843bSPierre Pronchery 67*e7be843bSPierre Pronchery- AES-128-CBC 68*e7be843bSPierre Pronchery- hmacWithSHA256 69*e7be843bSPierre Pronchery- sha256WithRSAEncryption 70*e7be843bSPierre Pronchery 71*e7be843bSPierre Pronchery### The connection with AlgorithmIdentifiers 72*e7be843bSPierre Pronchery 73*e7be843bSPierre ProncheryAlgorithmIdentifier is an ASN.1 structure that defines an algorithm as an 74*e7be843bSPierre ProncheryOID, along with parameters that should be passed to that algorithm. 75*e7be843bSPierre Pronchery 76*e7be843bSPierre ProncheryIt is expected that an application should be able to take that OID and 77*e7be843bSPierre Proncheryfetch it directly, after conversion to string form (either a name if the 78*e7be843bSPierre Proncheryapplication or libcrypto happens to know it, or the OID itself in canonical 79*e7be843bSPierre Proncherynumerical form). To enable this, explicit fetching is necessary. 80*e7be843bSPierre Pronchery 81*e7be843bSPierre Pronchery### What we have today 82*e7be843bSPierre Pronchery 83*e7be843bSPierre ProncheryAs a matter of fact, we already have built-in support for fetching 84*e7be843bSPierre Proncherycomposite algorithms, although our providers do not fully participate in 85*e7be843bSPierre Proncherythat support, and *most of the time*, we also have public APIs to use the 86*e7be843bSPierre Proncheryfetched result, commonly known as support for explicit fetching. 87*e7be843bSPierre Pronchery 88*e7be843bSPierre ProncheryThe idea is that providers can declare the different compositions of a base 89*e7be843bSPierre Proncheryalgorithm in the `OSSL_ALGORITHM` array, each pointing to different 90*e7be843bSPierre Pronchery`OSSL_DISPATCH` tables, which would in turn refer to pretty much the same 91*e7be843bSPierre Proncheryfunctions, apart from the constructor function. 92*e7be843bSPierre Pronchery 93*e7be843bSPierre ProncheryFor example, we already do this with symmetric ciphers. 94*e7be843bSPierre Pronchery 95*e7be843bSPierre ProncheryAnother example, which we could implement in our providers today, would be 96*e7be843bSPierre Proncherycompositions of HMAC: 97*e7be843bSPierre Pronchery 98*e7be843bSPierre Pronchery``` C 99*e7be843bSPierre Proncherystatic const OSSL_ALGORITHM deflt_macs[] = { 100*e7be843bSPierre Pronchery /* ... */ 101*e7be843bSPierre Pronchery { "HMAC-SHA1:hmacWithSHA1:1.2.840.113549.2.7", 102*e7be843bSPierre Pronchery "provider=default", ossl_hmac_sha1_functions }, 103*e7be843bSPierre Pronchery { "HMAC-SHA224:hmacWithSHA224:1.2.840.113549.2.8", 104*e7be843bSPierre Pronchery "provider=default", ossl_hmac_sha224_functions }, 105*e7be843bSPierre Pronchery { "HMAC-SHA256:hmacWithSHA256:1.2.840.113549.2.9", 106*e7be843bSPierre Pronchery "provider=default", ossl_hmac_sha256_functions }, 107*e7be843bSPierre Pronchery { "HMAC-SHA384:hmacWithSHA384:1.2.840.113549.2.10", 108*e7be843bSPierre Pronchery "provider=default", ossl_hmac_sha384_functions }, 109*e7be843bSPierre Pronchery { "HMAC-SHA512:hmacWithSHA512:1.2.840.113549.2.11", 110*e7be843bSPierre Pronchery "provider=default", ossl_hmac_sha512_functions }, 111*e7be843bSPierre Pronchery /* ... */ 112*e7be843bSPierre Pronchery``` 113*e7be843bSPierre Pronchery 114*e7be843bSPierre Pronchery### What we don't have today 115*e7be843bSPierre Pronchery 116*e7be843bSPierre ProncheryThere are some classes of algorithms for which we have no support for using 117*e7be843bSPierre Proncherythe result of explicit fetching. So for example, while it's possible for a 118*e7be843bSPierre Proncheryprovider to declare composite algorithms through the `OSSL_ALGORITHM` array, 119*e7be843bSPierre Proncherythere's currently no way for an application to use them. 120*e7be843bSPierre Pronchery 121*e7be843bSPierre ProncheryThis all revolves around asymmetric algorithms, where we currently only 122*e7be843bSPierre Proncherysupport implicit fetching. 123*e7be843bSPierre Pronchery 124*e7be843bSPierre ProncheryThis is hurtful in multiple ways: 125*e7be843bSPierre Pronchery 126*e7be843bSPierre Pronchery- It fails the provider authors in terms being able to consistently 127*e7be843bSPierre Pronchery declare all algorithms through `OSSL_ALGORITHM` arrays. 128*e7be843bSPierre Pronchery- It fails the applications in terms of being able to fetch algorithms and 129*e7be843bSPierre Pronchery use the result. 130*e7be843bSPierre Pronchery- It fails discoverability, for example through the `openssl list` 131*e7be843bSPierre Pronchery command. 132*e7be843bSPierre Pronchery 133*e7be843bSPierre Pronchery<!-- links --> 134*e7be843bSPierre Pronchery[Functions for explicitly fetched signature algorithms]: 135*e7be843bSPierre Pronchery functions-for-explicitly-fetched-signature-algorithms.md 136