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