]>
Commit | Line | Data |
---|---|---|
fdf6c0b6 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
42738cde | 5 | EVP_MD_fetch, EVP_CIPHER_fetch |
fdf6c0b6 MC |
6 | - Functions to explicitly fetch algorithm implementations |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/evp.h> | |
11 | ||
12 | EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm, | |
13 | const char *properties); | |
42738cde MC |
14 | EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm, |
15 | const char *properties); | |
fdf6c0b6 MC |
16 | |
17 | =head1 DESCRIPTION | |
18 | ||
42738cde MC |
19 | Cryptographic algorithms are represented by different OpenSSL objects depending |
20 | on what type of algorithm it is. The following cryptographic algorithm types are | |
21 | supported. | |
fdf6c0b6 | 22 | |
42738cde MC |
23 | =over 4 |
24 | ||
25 | =item B<EVP_MD> | |
26 | ||
27 | Represents a digest algorithm. | |
28 | ||
29 | =item B<EVP_CIPHER> | |
30 | ||
31 | Represents a symmetric cipher algorithm. | |
32 | ||
33 | =item B<EVP_MAC> | |
34 | ||
35 | Represents a Message Authentication Code algorithm. | |
36 | ||
37 | =item B<EVP_KDF> | |
38 | ||
39 | Represents a Key Derivation Function algorithm. | |
40 | ||
41 | =back | |
fdf6c0b6 | 42 | |
42738cde MC |
43 | The algorithm objects may or may not have an associated algorithm |
44 | implementation. | |
45 | Cryptographic algorithms are implemented by providers. | |
46 | Any algorithm may be supported by zero or more providers. | |
47 | In order to use an algorithm an implementation must first be obtained. | |
48 | This can happen in one of three ways, i.e. implicit fetch, explicit fetch or | |
49 | user defined. | |
fdf6c0b6 MC |
50 | |
51 | =over 4 | |
52 | ||
b7c913c8 | 53 | =item Implicit Fetch |
fdf6c0b6 | 54 | |
b7c913c8 | 55 | With implicit fetch an application can use functions such as L<EVP_sha256(3)>, |
42738cde MC |
56 | L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)> to obtain an algorithm object with |
57 | no associated implementation. | |
58 | When used in a function like L<EVP_DigestInit_ex(3)> or L<EVP_CipherInit_ex(3)> | |
59 | the actual implementation to be used will be fetched implicitly using default | |
60 | search criteria. | |
61 | Typically, this will return an implementation of the appropriate algorithm from | |
62 | the default provider unless the default search criteria have been changed and/or | |
63 | different providers have been loaded. | |
fdf6c0b6 | 64 | |
b7c913c8 | 65 | =item Explicit Fetch |
fdf6c0b6 | 66 | |
42738cde MC |
67 | With explicit fetch an application uses one of the "fetch" functions to obtain |
68 | an algorithm object with an associated implementation. | |
69 | An implementation with the given name that satisfies the search criteria | |
70 | specified in the B<properties> parameter combined with the default search | |
71 | criteria will be looked for within the available providers and returned. | |
cb929645 RL |
72 | See L<EVP_set_default_properties(3)> for information on default search criteria |
73 | and L<OSSL_PROVIDER(3)> for information about providers. | |
fdf6c0b6 MC |
74 | |
75 | =item User defined | |
76 | ||
42738cde MC |
77 | Using the user defined approach an application constructs its own algorithm |
78 | object. | |
79 | See L<EVP_MD_meth_new(3)> and L<EVP_CIPHER_meth_new(3)> for details. | |
fdf6c0b6 MC |
80 | |
81 | =back | |
82 | ||
42738cde MC |
83 | Having obtained an algorithm implementation as an algorithm object it can then |
84 | be used to perform cryptographic operations. | |
85 | For example to calculate the digest of input data with an B<EVP_MD> algorithm | |
86 | object you can use functions such as L<EVP_DigestInit_ex(3)>, | |
87 | L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>. | |
88 | ||
89 | The fetch functions will look for an algorithm within the providers that | |
90 | have been loaded into the B<OPENSSL_CTX> given in the B<ctx> parameter. | |
91 | This parameter may be NULL in which case the default B<OPENSSL_CTX> will be | |
92 | used. | |
93 | See L<OPENSSL_CTX_new(3)> and L<OSSL_PROVIDER_load(3)> for further details. | |
fdf6c0b6 MC |
94 | |
95 | The B<algorithm> parameter gives the name of the algorithm to be looked up. | |
42738cde MC |
96 | Different algorithms can be made available by loading different providers. |
97 | ||
98 | The built-in default provider digest algorithm implementation names are: SHA1, | |
99 | SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256, SHA3-224, SHA3-256, | |
100 | SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3, BLAKE2b512, BLAKE2s256 and | |
101 | MD5-SHA1. | |
102 | ||
103 | The built-in default provider cipher algorithm implementation names are: | |
104 | AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC, AES-128-CBC, | |
105 | AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB, AES-192-CFB, AES-128-CFB, | |
106 | AES-256-CFB1, AES-192-CFB1, AES-128-CFB1, AES-256-CFB8, AES-192-CFB8, | |
107 | AES-128-CFB8, AES-256-CTR, AES-192-CTR, AES-128-CTR, id-aes256-GCM, | |
108 | id-aes192-GCM and id-aes128-GCM. | |
fdf6c0b6 MC |
109 | |
110 | Additional algorithm implementations may be obtained by loading the "legacy" | |
42738cde MC |
111 | provider. |
112 | ||
113 | The legacy provider digest algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and | |
fdf6c0b6 MC |
114 | whirlpool. |
115 | ||
116 | The B<properties> parameter specifies the search criteria that will be used to | |
117 | look for an algorithm implementation. Properties are given as a comma delimited | |
118 | string of name value pairs. In order for an implementation to match, all the | |
119 | properties in the query string must match those defined for that implementation. | |
120 | Any properties defined by an implementation but not given in the query string | |
121 | are ignored. All algorithm implementations in the default provider have the | |
122 | property "default=yes". All algorithm implementations in the legacy provider have | |
123 | the property "legacy=yes". All algorithm implementations in the FIPS provider | |
124 | have the property "fips=yes". In the event that more than one implementation | |
125 | of the given algorithm name matches the specified properties then an unspecified | |
126 | one of those implementations may be returned. The B<properties> parameter may be | |
127 | NULL in which case any implementation from the available providers with the | |
128 | given algorithm name will be returned. | |
129 | ||
130 | The return value from a call to EVP_MD_fetch() must be freed by the caller using | |
42738cde MC |
131 | L<EVP_MD_meth_free(3)>. |
132 | Note that EVP_MD objects are reference counted. See L<EVP_MD_up_ref(3)>. | |
133 | ||
134 | The return value from a call to EVP_CIPHER_fetch() must be freed by the caller | |
135 | using L<EVP_CIPHER_meth_free(3)>. | |
136 | Note that EVP_CIPHER objects are reference counted. | |
137 | See L<EVP_CIPHER_up_ref(3)>. | |
fdf6c0b6 | 138 | |
b7c913c8 MC |
139 | =head1 NOTES |
140 | ||
141 | Where an application that previously used implicit fetch is converted to use | |
142 | explicit fetch care should be taken with the L<EVP_MD_CTX_md(3)> function. | |
143 | Specifically, this function returns the EVP_MD object orginally passed to | |
144 | EVP_DigestInit_ex() (or other similar function). With implicit fetch the | |
145 | returned EVP_MD object is guaranteed to be available throughout the application | |
146 | lifetime. However, with explicit fetch EVP_MD objects are reference counted. | |
147 | EVP_MD_CTX_md does not increment the reference count and so the returned EVP_MD | |
148 | object may not be accessible beyond the lifetime of the EVP_MD_CTX it is | |
149 | associated with. | |
150 | ||
fdf6c0b6 MC |
151 | =head1 RETURN VALUES |
152 | ||
153 | EVP_MD_fetch() returns a pointer to the algorithm implementation represented by | |
154 | an EVP_MD object, or NULL on error. | |
155 | ||
156 | =head1 EXAMPLES | |
157 | ||
158 | Fetch any available implementation of SHA256 in the default context: | |
159 | ||
160 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL); | |
42738cde MC |
161 | ... |
162 | EVP_MD_meth_free(md); | |
163 | ||
164 | Fetch any available implementation of AES-128-CBC in the default context: | |
165 | ||
166 | EVP_CIPHER *cipher = EVP_CIPHER_fetch(NULL, "AES-128-CBC", NULL); | |
167 | ... | |
168 | EVP_CIPHER_meth_free(cipher); | |
fdf6c0b6 MC |
169 | |
170 | Fetch an implementation of SHA256 from the default provider in the default | |
171 | context: | |
172 | ||
173 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes"); | |
174 | ... | |
175 | EVP_MD_meth_free(md); | |
176 | ||
177 | Fetch an implementation of SHA256 that is not from the default provider in the | |
178 | default context: | |
179 | ||
180 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no"); | |
181 | ... | |
182 | EVP_MD_meth_free(md); | |
183 | ||
184 | Fetch an implementation of SHA256 from the default provider in the specified | |
185 | context: | |
186 | ||
187 | EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes"); | |
188 | ... | |
189 | EVP_MD_meth_free(md); | |
190 | ||
191 | Load the legacy provider into the default context and then fetch an | |
192 | implementation of whirlpool from it: | |
193 | ||
194 | /* This only needs to be done once - usually at application start up */ | |
195 | OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); | |
196 | ||
197 | EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes"); | |
198 | ... | |
199 | EVP_MD_meth_free(md); | |
200 | ||
201 | Note that in the above example the property string "legacy=yes" is optional | |
202 | since, assuming no other providers have been loaded, the only implmentation of | |
203 | the "whirlpool" algorithm is in the "legacy" provider. Also note that the | |
204 | default provider should be explicitly loaded if it is required in addition to | |
205 | other providers: | |
206 | ||
207 | /* This only needs to be done once - usually at application start up */ | |
208 | OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); | |
209 | OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); | |
210 | ||
211 | EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); | |
212 | EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL); | |
213 | ... | |
214 | EVP_MD_meth_free(md_whirlpool); | |
215 | EVP_MD_meth_free(md_sha256); | |
216 | ||
217 | =head1 SEE ALSO | |
218 | ||
42738cde MC |
219 | L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>, L<EVP_MD_meth_new(3)>, |
220 | L<EVP_MD_meth_free(3)>, L<EVP_CIPHER_meth_new(3)>, L<EVP_CIPHER_meth_free(3)>, | |
221 | L<EVP_MD_up_ref(3)>, L<EVP_CIPHER_up_ref(3)>, L<OSSL_PROVIDER_load(3)>, | |
222 | L<OPENSSL_CTX(3)>, L<EVP_set_default_properties(3)> | |
fdf6c0b6 MC |
223 | |
224 | =head1 HISTORY | |
225 | ||
226 | The functions described here were added in OpenSSL 3.0. | |
227 | ||
228 | =head1 COPYRIGHT | |
229 | ||
230 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
231 | ||
232 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
233 | this file except in compliance with the License. You can obtain a copy | |
234 | in the file LICENSE in the source distribution or at | |
235 | L<https://www.openssl.org/source/license.html>. | |
236 | ||
237 | =cut |