doc/man3/EVP_MD_fetch.pod

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