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