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