Documentation: Move the description of the fetching functions
Now that the general descriptions have moved from doc/man3/EVP_MD_fetch.pod to doc/man7/provider.pod, the description of the fetching functions themselves can be moved to other pages where related functions are already described. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9409)
This commit is contained in:
Richard Levitte
parent
e4c0ec6278
commit
2cafb1dff3
4 changed files with 56 additions and 259 deletions
|
|
@ -2,6 +2,7 @@
|
|||
|
||||
=head1 NAME
|
||||
|
||||
EVP_MD_fetch,
|
||||
EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy,
|
||||
EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_params, EVP_MD_CTX_get_params,
|
||||
EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
|
||||
|
|
@ -18,6 +19,8 @@ EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines
|
|||
|
||||
#include <openssl/evp.h>
|
||||
|
||||
EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm,
|
||||
const char *properties);
|
||||
EVP_MD_CTX *EVP_MD_CTX_new(void);
|
||||
int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);
|
||||
void EVP_MD_CTX_free(EVP_MD_CTX *ctx);
|
||||
|
|
@ -75,6 +78,14 @@ and should be used instead of the cipher-specific functions.
|
|||
|
||||
=over 4
|
||||
|
||||
=item EVP_MD_fetch()
|
||||
|
||||
Fetches the digest implementation for the given B<algorithm> from any
|
||||
provider offering it, within the criteria given by the B<properties>.
|
||||
See L<provider(7)/Fetching algorithms> for further information.
|
||||
|
||||
The returned value must eventually be freed with L<EVP_MD_meth_free(3)>.
|
||||
|
||||
=item EVP_MD_CTX_new()
|
||||
|
||||
Allocates and returns a digest context.
|
||||
|
|
@ -123,9 +134,12 @@ If B<impl> is NULL the default implementation of digest B<type> is used.
|
|||
|
||||
=item EVP_DigestInit_ex()
|
||||
|
||||
Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
|
||||
B<type> will typically be supplied by a function such as EVP_sha1(). If
|
||||
B<impl> is NULL then the default implementation of digest B<type> is used.
|
||||
Sets up digest context B<ctx> to use a digest B<type>.
|
||||
B<type> is typically supplied by a function such as EVP_sha1(), or a
|
||||
value explicitly fetched with EVP_MD_fetch().
|
||||
|
||||
If B<impl> is non-NULL, its implementation of the digest B<type> is used if
|
||||
there is one, and if not, the default implementation is used.
|
||||
|
||||
=item EVP_DigestUpdate()
|
||||
|
||||
|
|
@ -343,6 +357,10 @@ disabled with this flag.
|
|||
|
||||
=over 4
|
||||
|
||||
=item EVP_MD_fetch()
|
||||
|
||||
Returns a pointer to a B<EVP_MD> for success or NULL for failure.
|
||||
|
||||
=item EVP_DigestInit_ex(),
|
||||
EVP_DigestUpdate(),
|
||||
EVP_DigestFinal_ex()
|
||||
|
|
@ -487,6 +505,7 @@ L<EVP_sha224(3)>,
|
|||
L<EVP_sha3_224(3)>,
|
||||
L<EVP_sm3(3)>,
|
||||
L<EVP_whirlpool(3)>
|
||||
L<provider(7)/Fetching algorithms>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
|
|
|||
|
|
@ -2,6 +2,7 @@
|
|||
|
||||
=head1 NAME
|
||||
|
||||
EVP_CIPHER_fetch,
|
||||
EVP_CIPHER_CTX_new,
|
||||
EVP_CIPHER_CTX_reset,
|
||||
EVP_CIPHER_CTX_free,
|
||||
|
|
@ -54,6 +55,8 @@ EVP_enc_null
|
|||
|
||||
#include <openssl/evp.h>
|
||||
|
||||
EVP_CIPHER *EVP_CIPHER_fetch(OPENSSL_CTX *ctx, const char *algorithm,
|
||||
const char *properties);
|
||||
EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
|
||||
int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
|
||||
void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
|
||||
|
|
@ -123,6 +126,14 @@ EVP_enc_null
|
|||
The EVP cipher routines are a high level interface to certain
|
||||
symmetric ciphers.
|
||||
|
||||
EVP_CIPHER_fetch() fetches the cipher implementation for the given
|
||||
B<algorithm> from any provider offering it, within the criteria given
|
||||
by the B<properties>.
|
||||
See L<provider(7)/Fetching algorithms> for further information.
|
||||
|
||||
The returned value must eventually be freed with
|
||||
L<EVP_CIPHER_meth_free(3)>.
|
||||
|
||||
EVP_CIPHER_CTX_new() creates a cipher context.
|
||||
|
||||
EVP_CIPHER_CTX_free() clears all information from a cipher context
|
||||
|
|
@ -132,10 +143,11 @@ cipher are complete so sensitive information does not remain in
|
|||
memory.
|
||||
|
||||
EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
|
||||
with cipher B<type> from ENGINE B<impl>. B<ctx> must be created
|
||||
before calling this function. B<type> is normally supplied
|
||||
by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
|
||||
default implementation is used. B<key> is the symmetric key to use
|
||||
with cipher B<type>. B<type> is typically supplied by a function such
|
||||
as EVP_aes_256_cbc(), or a value explicitly fetched with
|
||||
EVP_CIPHER_fetch(). If B<impl> is non-NULL, its implementation of the
|
||||
cipher B<type> is used if there is one, and if not, the default
|
||||
implementation is used. B<key> is the symmetric key to use
|
||||
and B<iv> is the IV to use (if necessary), the actual number of bytes
|
||||
used for the key and IV depends on the cipher. It is possible to set
|
||||
all parameters to NULL except B<type> in an initial call and supply
|
||||
|
|
@ -280,6 +292,9 @@ buffer at least as big as the value returned by EVP_CIPHER_CTX_key_length().
|
|||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
EVP_CIPHER_fetch() returns a pointer to a B<EVP_CIPHER> for success
|
||||
and B<NULL> for failure.
|
||||
|
||||
EVP_CIPHER_CTX_new() returns a pointer to a newly created
|
||||
B<EVP_CIPHER_CTX> for success and B<NULL> for failure.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,21 +2,30 @@
|
|||
|
||||
=head1 NAME
|
||||
|
||||
EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref
|
||||
EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref
|
||||
- Functions to manage EVP_KEYEXCH algorithm objects
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/evp.h>
|
||||
|
||||
EVP_KEYEXCH *EVP_KEYEXCH_fetch(OPENSSL_CTX *ctx, const char *algorithm,
|
||||
const char *properties);
|
||||
void EVP_KEYEXCH_free(EVP_KEYEXCH *exchange);
|
||||
int EVP_KEYEXCH_up_ref(EVP_KEYEXCH *exchange);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
EVP_KEYEXCH_fetch() fetches the key exchange implementation for the given
|
||||
B<algorithm> from any provider offering it, within the criteria given
|
||||
by the B<properties>.
|
||||
See L<provider(7)/Fetching algorithms> for further information.
|
||||
|
||||
The returned value must eventually be freed with EVP_KEYEXCH_free().
|
||||
|
||||
EVP_KEYEXCH_free() decrements the reference count for the B<EVP_KEYEXCH>
|
||||
structure. Typically this structure will have been obtained from an earlier call
|
||||
to L<EVP_KEYEXCH_fetch(3)>. If the reference count drops to 0 then the
|
||||
to EVP_KEYEXCH_fetch(). If the reference count drops to 0 then the
|
||||
structure is freed.
|
||||
|
||||
EVP_KEYEXCH_up_ref() increments the reference count for an B<EVP_KEYEXCH>
|
||||
|
|
@ -24,11 +33,14 @@ structure.
|
|||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
EVP_KEYEXCH_fetch() returns a pointer to a B<EVP_KEYEXCH> for success
|
||||
or B<NULL> for failure.
|
||||
|
||||
EVP_KEYEXCH_up_ref() returns 1 for success or 0 otherwise.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_KEYEXCH_fetch(3)>
|
||||
L<provider(7)/Fetching algorithms>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
|
|
|||
|
|
@ -1,249 +0,0 @@
|
|||
=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_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
|
||||
Loading…
Reference in a new issue