Document the functions EVP_MD_fetch() and EVP_MD_upref()
[openssl.git] / doc / man3 / EVP_MD_fetch.pod
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
24 lookup, explicit lookup or user defined.
25
26 =over 4
27
28 =item Implicit Lookup
29
30 With implicit lookup an application can use functions such as L<EVP_sha256(3)>,
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
38 =item Explicit Lookup
39
40 With explicit lookup an application uses the EVP_MD_fetch() function to obtain
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
86 =head1 RETURN VALUES
87
88 EVP_MD_fetch() returns a pointer to the algorithm implementation represented by
89 an EVP_MD object, or NULL on error.
90
91 =head1 EXAMPLES
92
93 Fetch any available implementation of SHA256 in the default context:
94
95  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
96
97 Fetch an implementation of SHA256 from the default provider in the default
98 context:
99
100  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
101  ...
102  EVP_MD_meth_free(md);
103
104 Fetch an implementation of SHA256 that is not from the default provider in the
105 default context:
106
107  EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
108  ...
109  EVP_MD_meth_free(md);
110
111 Fetch an implementation of SHA256 from the default provider in the specified
112 context:
113
114  EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
115  ...
116  EVP_MD_meth_free(md);
117
118 Load the legacy provider into the default context and then fetch an
119 implementation of whirlpool from it:
120
121  /* This only needs to be done once - usually at application start up */
122  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
123
124  EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
125  ...
126  EVP_MD_meth_free(md);
127
128 Note that in the above example the property string "legacy=yes" is optional
129 since, assuming no other providers have been loaded, the only implmentation of
130 the "whirlpool" algorithm is in the "legacy" provider. Also note that the
131 default provider should be explicitly loaded if it is required in addition to
132 other providers:
133
134  /* This only needs to be done once - usually at application start up */
135  OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
136  OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
137
138  EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
139  EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
140  ...
141  EVP_MD_meth_free(md_whirlpool);
142  EVP_MD_meth_free(md_sha256);
143
144 =head1 SEE ALSO
145
146 L<EVP_DigestInit(3)>, L<EVP_MD_meth_new(3)>, L<EVP_MD_meth_free(3)>,
147 L<EVP_MD_upref(3)>, L<OSSL_PROVIDER_load(3)>, L<OPENSSL_CTX(3)>
148
149 =head1 HISTORY
150
151 The functions described here were added in OpenSSL 3.0.
152
153 =head1 COPYRIGHT
154
155 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
156
157 Licensed under the Apache License 2.0 (the "License").  You may not use
158 this file except in compliance with the License.  You can obtain a copy
159 in the file LICENSE in the source distribution or at
160 L<https://www.openssl.org/source/license.html>.
161
162 =cut