5 EVP_MD_fetch, EVP_CIPHER_fetch, EVP_KEYEXCH_fetch
6 - Functions to explicitly fetch algorithm implementations
10 #include <openssl/evp.h>
12 EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm,
13 const char *properties);
14 EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
15 const char *properties);
16 EVP_KEYEXCH *EVP_KEYEXCH_fetch(OPENSSL_CTX *ctx, const char *algorithm,
17 const char *properties);
21 Cryptographic algorithms are represented by different OpenSSL objects depending
22 on what type of algorithm it is. The following cryptographic algorithm types are
29 Represents a digest algorithm.
33 Represents a symmetric cipher algorithm.
37 Represents a Message Authentication Code algorithm.
41 Represents a Key Derivation Function algorithm.
45 Represents a Key Exchange algorithm.
49 The algorithm objects may or may not have an associated algorithm
51 Cryptographic algorithms are implemented by providers.
52 Any algorithm may be supported by zero or more providers.
53 In order to use an algorithm an implementation must first be obtained.
54 This can happen in one of three ways, i.e. implicit fetch, explicit fetch or
61 With implicit fetch an application can use functions such as L<EVP_sha256(3)>,
62 L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)> to obtain an algorithm object with
63 no associated implementation.
64 When used in a function like L<EVP_DigestInit_ex(3)> or L<EVP_CipherInit_ex(3)>
65 the actual implementation to be used will be fetched implicitly using default
67 Typically, this will return an implementation of the appropriate algorithm from
68 the default provider unless the default search criteria have been changed and/or
69 different providers have been loaded.
71 Implicit fetching can also occur with functions such as
72 L<EVP_PKEY_derive_init_ex(3)> where a NULL algorithm parameter is supplied.
73 In this case an algorithm implementation is implicitly fetched using default
74 search criteria and an algorithm name that is consistent with the type of
79 With explicit fetch an application uses one of the "fetch" functions to obtain
80 an algorithm object with an associated implementation.
81 An implementation with the given name that satisfies the search criteria
82 specified in the B<properties> parameter combined with the default search
83 criteria will be looked for within the available providers and returned.
84 See L<EVP_set_default_properties(3)> for information on default search criteria
85 and L<OSSL_PROVIDER(3)> for information about providers.
89 Using the user defined approach an application constructs its own algorithm
91 See L<EVP_MD_meth_new(3)> and L<EVP_CIPHER_meth_new(3)> for details.
95 Having obtained an algorithm implementation as an algorithm object it can then
96 be used to perform cryptographic operations.
97 For example to calculate the digest of input data with an B<EVP_MD> algorithm
98 object you can use functions such as L<EVP_DigestInit_ex(3)>,
99 L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>.
101 The fetch functions will look for an algorithm within the providers that
102 have been loaded into the B<OPENSSL_CTX> given in the B<ctx> parameter.
103 This parameter may be NULL in which case the default B<OPENSSL_CTX> will be
105 See L<OPENSSL_CTX_new(3)> and L<OSSL_PROVIDER_load(3)> for further details.
107 The B<algorithm> parameter gives the name of the algorithm to be looked up.
108 Different algorithms can be made available by loading different providers.
110 The built-in default provider digest algorithm implementation names are: SHA1,
111 SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256, SHA3-224, SHA3-256,
112 SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3, BLAKE2b512, BLAKE2s256 and
115 The built-in default provider cipher algorithm implementation names are:
116 AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC, AES-128-CBC,
117 AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB, AES-192-CFB, AES-128-CFB,
118 AES-256-CFB1, AES-192-CFB1, AES-128-CFB1, AES-256-CFB8, AES-192-CFB8,
119 AES-128-CFB8, AES-256-CTR, AES-192-CTR, AES-128-CTR, id-aes256-GCM,
120 id-aes192-GCM and id-aes128-GCM.
122 Additional algorithm implementations may be obtained by loading the "legacy"
125 The legacy provider digest algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and
128 The B<properties> parameter specifies the search criteria that will be used to
129 look for an algorithm implementation. Properties are given as a comma delimited
130 string of name value pairs. In order for an implementation to match, all the
131 properties in the query string must match those defined for that implementation.
132 Any properties defined by an implementation but not given in the query string
133 are ignored. All algorithm implementations in the default provider have the
134 property "default=yes". All algorithm implementations in the legacy provider have
135 the property "legacy=yes". All algorithm implementations in the FIPS provider
136 have the property "fips=yes". In the event that more than one implementation
137 of the given algorithm name matches the specified properties then an unspecified
138 one of those implementations may be returned. The B<properties> parameter may be
139 NULL in which case any implementation from the available providers with the
140 given algorithm name will be returned.
142 The return value from a call to EVP_MD_fetch() must be freed by the caller using
143 L<EVP_MD_meth_free(3)>.
144 Note that EVP_MD objects are reference counted. See L<EVP_MD_up_ref(3)>.
146 The return value from a call to EVP_CIPHER_fetch() must be freed by the caller
147 using L<EVP_CIPHER_meth_free(3)>.
148 Note that EVP_CIPHER objects are reference counted.
149 See L<EVP_CIPHER_up_ref(3)>.
153 Where an application that previously used implicit fetch is converted to use
154 explicit fetch care should be taken with the L<EVP_MD_CTX_md(3)> function.
155 Specifically, this function returns the EVP_MD object originally passed to
156 EVP_DigestInit_ex() (or other similar function). With implicit fetch the
157 returned EVP_MD object is guaranteed to be available throughout the application
158 lifetime. However, with explicit fetch EVP_MD objects are reference counted.
159 EVP_MD_CTX_md does not increment the reference count and so the returned EVP_MD
160 object may not be accessible beyond the lifetime of the EVP_MD_CTX it is
165 EVP_MD_fetch() returns a pointer to the algorithm implementation represented by
166 an EVP_MD object, or NULL on error.
170 Fetch any available implementation of SHA256 in the default context:
172 EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
174 EVP_MD_meth_free(md);
176 Fetch any available implementation of AES-128-CBC in the default context:
178 EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL);
180 EVP_CIPHER_meth_free(cipher);
182 Fetch an implementation of SHA256 from the default provider in the default
185 EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
187 EVP_MD_meth_free(md);
189 Fetch an implementation of SHA256 that is not from the default provider in the
192 EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
194 EVP_MD_meth_free(md);
196 Fetch an implementation of SHA256 from the default provider in the specified
199 EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
201 EVP_MD_meth_free(md);
203 Load the legacy provider into the default context and then fetch an
204 implementation of whirlpool from it:
206 /* This only needs to be done once - usually at application start up */
207 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
209 EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
211 EVP_MD_meth_free(md);
213 Note that in the above example the property string "legacy=yes" is optional
214 since, assuming no other providers have been loaded, the only implementation of
215 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
216 default provider should be explicitly loaded if it is required in addition to
219 /* This only needs to be done once - usually at application start up */
220 OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
221 OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
223 EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
224 EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
226 EVP_MD_meth_free(md_whirlpool);
227 EVP_MD_meth_free(md_sha256);
231 L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>, L<EVP_MD_meth_new(3)>,
232 L<EVP_MD_meth_free(3)>, L<EVP_CIPHER_meth_new(3)>, L<EVP_CIPHER_meth_free(3)>,
233 L<EVP_MD_up_ref(3)>, L<EVP_CIPHER_up_ref(3)>, L<OSSL_PROVIDER_load(3)>,
234 L<OPENSSL_CTX(3)>, L<EVP_set_default_properties(3)>
238 The functions described here were added in OpenSSL 3.0.
242 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
244 Licensed under the Apache License 2.0 (the "License"). You may not use
245 this file except in compliance with the License. You can obtain a copy
246 in the file LICENSE in the source distribution or at
247 L<https://www.openssl.org/source/license.html>.