doc/man3/EVP_MD_fetch.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_MD_fetch, EVP_CIPHER_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  EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
  15                               const char *properties);
  16
  17 =head1 DESCRIPTION
  18
  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.
  22
  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
  42
  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.
  50
  51 =over 4
  52
  53 =item Implicit Fetch
  54
  55 With implicit fetch an application can use functions such as L<EVP_sha256(3)>,
  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.
  64
  65 =item Explicit Fetch
  66
  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.
  72 See L<EVP_set_default_properties(3)> for information on default search criteria
  73 and L<OSSL_PROVIDER(3)> for information about providers.
  74
  75 =item User defined
  76
  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.
  80
  81 =back
  82
  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.
  94
  95 The B<algorithm> parameter gives the name of the algorithm to be looked up.
  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.
 109
 110 Additional algorithm implementations may be obtained by loading the "legacy"
 111 provider.
 112
 113 The legacy provider digest algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and
 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
 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)>.
 138
 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
 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);
 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);
 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
 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)>
 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