]>
Commit | Line | Data |
---|---|---|
fdf6c0b6 MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_MD_fetch | |
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); | |
14 | ||
15 | =head1 DESCRIPTION | |
16 | ||
17 | The B<EVP_MD> object is used for representing a digest method implementation. | |
18 | ||
19 | Having obtained a digest implementation as an B<EVP_MD> type it can be used to | |
20 | calculate the digest of input data using functions such as | |
21 | L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>. | |
22 | ||
23 | Digest implementations may be obtained in one of three ways, i.e. implicit | |
b7c913c8 | 24 | fetch, explicit fetch or user defined. |
fdf6c0b6 MC |
25 | |
26 | =over 4 | |
27 | ||
b7c913c8 | 28 | =item Implicit Fetch |
fdf6c0b6 | 29 | |
b7c913c8 | 30 | With implicit fetch an application can use functions such as L<EVP_sha256(3)>, |
fdf6c0b6 MC |
31 | L<EVP_sha512(3)> or L<EVP_blake2b512(3)> to obtain an B<EVP_MD> object. When |
32 | used in a function like L<EVP_DigestInit_ex(3)> the actual implementation to | |
33 | be used will be fetched implicitly using default search criteria. Typically, | |
34 | (unless the default search criteria have been changed and/or different providers | |
35 | have been loaded), this will return an implementation of the appropriate | |
36 | algorithm from the default provider. | |
37 | ||
b7c913c8 | 38 | =item Explicit Fetch |
fdf6c0b6 | 39 | |
b7c913c8 | 40 | With explicit fetch an application uses the EVP_MD_fetch() function to obtain |
fdf6c0b6 MC |
41 | an algorithm implementation. An implementation with the given name and |
42 | satisfying the search criteria specified in the B<properties> parameter will be | |
43 | looked for within the available providers and returned. See L<OSSL_PROVIDER(3)> | |
44 | for information about providers. | |
45 | ||
46 | =item User defined | |
47 | ||
48 | Using the user defined approach an application constructs its own EVP_MD object. | |
49 | See L<EVP_MD_meth_new(3)> for details. | |
50 | ||
51 | =back | |
52 | ||
53 | The EVP_MD_fetch() function will look for an algorithm within the providers that | |
54 | have been loaded into the B<OPENSSL_CTX> given in the B<ctx> parameter. This | |
55 | parameter may be NULL in which case the default B<OPENSSL_CTX> will be used. See | |
56 | L<OPENSSL_CTX_new(3)> and L<OSSL_PROVIDER_load(3)> for further details. | |
57 | ||
58 | The B<algorithm> parameter gives the name of the algorithm to be looked up. | |
59 | Different algorithms can be made available by loading different providers. The | |
60 | built-in default provider algorithm implementation names are: SHA1, SHA224, | |
61 | SHA256, SHA384, SHA512, SHA512-224, SHA512-256,SHA3-224, SHA3-256, SHA3-384, | |
62 | SHA3-512, SHAKE128, SHAKE256, SM3, BLAKE2b512, BLAKE2s256 and MD5-SHA1. | |
63 | ||
64 | Additional algorithm implementations may be obtained by loading the "legacy" | |
65 | provider. The names of these algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and | |
66 | whirlpool. | |
67 | ||
68 | The B<properties> parameter specifies the search criteria that will be used to | |
69 | look for an algorithm implementation. Properties are given as a comma delimited | |
70 | string of name value pairs. In order for an implementation to match, all the | |
71 | properties in the query string must match those defined for that implementation. | |
72 | Any properties defined by an implementation but not given in the query string | |
73 | are ignored. All algorithm implementations in the default provider have the | |
74 | property "default=yes". All algorithm implementations in the legacy provider have | |
75 | the property "legacy=yes". All algorithm implementations in the FIPS provider | |
76 | have the property "fips=yes". In the event that more than one implementation | |
77 | of the given algorithm name matches the specified properties then an unspecified | |
78 | one of those implementations may be returned. The B<properties> parameter may be | |
79 | NULL in which case any implementation from the available providers with the | |
80 | given algorithm name will be returned. | |
81 | ||
82 | The return value from a call to EVP_MD_fetch() must be freed by the caller using | |
83 | L<EVP_MD_meth_free(3)>. Note that EVP_MD objects are reference counted. See | |
84 | L<EVP_MD_upref(3)>. | |
85 | ||
b7c913c8 MC |
86 | =head1 NOTES |
87 | ||
88 | Where an application that previously used implicit fetch is converted to use | |
89 | explicit fetch care should be taken with the L<EVP_MD_CTX_md(3)> function. | |
90 | Specifically, this function returns the EVP_MD object orginally passed to | |
91 | EVP_DigestInit_ex() (or other similar function). With implicit fetch the | |
92 | returned EVP_MD object is guaranteed to be available throughout the application | |
93 | lifetime. However, with explicit fetch EVP_MD objects are reference counted. | |
94 | EVP_MD_CTX_md does not increment the reference count and so the returned EVP_MD | |
95 | object may not be accessible beyond the lifetime of the EVP_MD_CTX it is | |
96 | associated with. | |
97 | ||
fdf6c0b6 MC |
98 | =head1 RETURN VALUES |
99 | ||
100 | EVP_MD_fetch() returns a pointer to the algorithm implementation represented by | |
101 | an EVP_MD object, or NULL on error. | |
102 | ||
103 | =head1 EXAMPLES | |
104 | ||
105 | Fetch any available implementation of SHA256 in the default context: | |
106 | ||
107 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL); | |
108 | ||
109 | Fetch an implementation of SHA256 from the default provider in the default | |
110 | context: | |
111 | ||
112 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes"); | |
113 | ... | |
114 | EVP_MD_meth_free(md); | |
115 | ||
116 | Fetch an implementation of SHA256 that is not from the default provider in the | |
117 | default context: | |
118 | ||
119 | EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no"); | |
120 | ... | |
121 | EVP_MD_meth_free(md); | |
122 | ||
123 | Fetch an implementation of SHA256 from the default provider in the specified | |
124 | context: | |
125 | ||
126 | EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes"); | |
127 | ... | |
128 | EVP_MD_meth_free(md); | |
129 | ||
130 | Load the legacy provider into the default context and then fetch an | |
131 | implementation of whirlpool from it: | |
132 | ||
133 | /* This only needs to be done once - usually at application start up */ | |
134 | OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); | |
135 | ||
136 | EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes"); | |
137 | ... | |
138 | EVP_MD_meth_free(md); | |
139 | ||
140 | Note that in the above example the property string "legacy=yes" is optional | |
141 | since, assuming no other providers have been loaded, the only implmentation of | |
142 | the "whirlpool" algorithm is in the "legacy" provider. Also note that the | |
143 | default provider should be explicitly loaded if it is required in addition to | |
144 | other providers: | |
145 | ||
146 | /* This only needs to be done once - usually at application start up */ | |
147 | OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy"); | |
148 | OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default"); | |
149 | ||
150 | EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL); | |
151 | EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL); | |
152 | ... | |
153 | EVP_MD_meth_free(md_whirlpool); | |
154 | EVP_MD_meth_free(md_sha256); | |
155 | ||
156 | =head1 SEE ALSO | |
157 | ||
158 | L<EVP_DigestInit(3)>, L<EVP_MD_meth_new(3)>, L<EVP_MD_meth_free(3)>, | |
159 | L<EVP_MD_upref(3)>, L<OSSL_PROVIDER_load(3)>, L<OPENSSL_CTX(3)> | |
160 | ||
161 | =head1 HISTORY | |
162 | ||
163 | The functions described here were added in OpenSSL 3.0. | |
164 | ||
165 | =head1 COPYRIGHT | |
166 | ||
167 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
168 | ||
169 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
170 | this file except in compliance with the License. You can obtain a copy | |
171 | in the file LICENSE in the source distribution or at | |
172 | L<https://www.openssl.org/source/license.html>. | |
173 | ||
174 | =cut |