Documentation: Add provider(7), for general description of providers
This includes an enumeration of the providers supplied with OpenSSL, and what implementations they offer. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9409)
This commit is contained in:
Richard Levitte
parent
a80278b071
commit
e4c0ec6278
1 changed files with 401 additions and 0 deletions
401
doc/man7/provider.pod
Normal file
401
doc/man7/provider.pod
Normal file
|
|
@ -0,0 +1,401 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
provider - OpenSSL operation implementation providers
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment generic
|
||||
|
||||
#include <openssl/provider.h>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
=head2 General
|
||||
|
||||
A I<provider>, in OpenSSL terms, is a unit of code that provides one
|
||||
or more implementations for various operations for diverse algorithms
|
||||
that one might want to perform.
|
||||
|
||||
An I<operation> is something one wants to do, such as encryption and
|
||||
decryption, key derivation, MAC calculation, signing and verification,
|
||||
etc.
|
||||
|
||||
An I<algorithm> is a named method to perform an operation.
|
||||
Very often, the algorithms revolve around cryptographic operations,
|
||||
but may also revolve around other types of operation, such as managing
|
||||
certain types of objects.
|
||||
|
||||
=head2 Provider
|
||||
|
||||
I<NOTE: This section is mostly interesting for provider authors.>
|
||||
|
||||
A I<provider> offers an initialization function, as a set of base
|
||||
functions in the form of an B<OSSL_DISPATCH> array, and by extension,
|
||||
a set of B<OSSL_ALGORITHM>s (see L<openssl-core.h(7)>).
|
||||
It may be a dynamically loadable module, or may be built-in, in
|
||||
OpenSSL libraries or in the application.
|
||||
If it's a dynamically loadable module, the initialization function
|
||||
must be named C<OSSL_provider_init> and must be exported.
|
||||
If it's built-in, the initialization function may have any name.
|
||||
|
||||
The initialization function must have the following signature:
|
||||
|
||||
int NAME(const OSSL_PROVIDER *provider,
|
||||
const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
|
||||
void **provctx);
|
||||
|
||||
I<provider> is the OpenSSL library object for the provider, and works
|
||||
as a handle for everything the OpenSSL libraries need to know about
|
||||
the provider.
|
||||
For the provider itself, it may hold some interesting information,
|
||||
and is also passed to some of the functions given in the dispatch
|
||||
array I<in>.
|
||||
|
||||
I<in> is a dispatch array of base functions offered by the OpenSSL
|
||||
libraries, and the available functions are further described in
|
||||
L<provider-base(7)>.
|
||||
|
||||
I<*out> must be assigned a dispatch array of base functions that the
|
||||
provider offers to the OpenSSL libraries.
|
||||
The functions that may be offered are further described in
|
||||
L<provider-base(7)>, and they are the central means of communication
|
||||
between the OpenSSL libraries and the provider.
|
||||
|
||||
I<*provctx> should be assigned a provider specific context to allow
|
||||
the provider multiple simultaneous uses.
|
||||
This pointer will be passed to various operation functions offered by
|
||||
the provider.
|
||||
|
||||
One of the functions the provider offers to the OpenSSL libraries is
|
||||
the central mechanism for the OpenSSL libraries to get access to
|
||||
operation implementations for diverse algorithms.
|
||||
Its referred to with the number B<OSSL_FUNC_PROVIDER_QUERY_OPERATION>
|
||||
and has the following signature:
|
||||
|
||||
const OSSL_ALGORITHM *provider_query_operation(void *provctx,
|
||||
int operation_id,
|
||||
const int *no_store);
|
||||
|
||||
I<provctx> is the provider specific context that was passed back by
|
||||
the initialization function.
|
||||
|
||||
I<operation_id> is an operation identity (see L</Operations> below).
|
||||
|
||||
I<no_store> is a flag back to the OpenSSL libraries which, when
|
||||
non-zero, signifies that the OpenSSL libraries will not store a
|
||||
reference to the returned data in their internal store of
|
||||
implementations.
|
||||
|
||||
The returned B<OSSL_ALGORITHM> is the foundation of any OpenSSL
|
||||
library API that uses providers for their implementation, most
|
||||
commonly in the I<fetching> type of functions
|
||||
(see L</Fetching algorithms> below).
|
||||
|
||||
=head2 Operations
|
||||
|
||||
I<NOTE: This section is mostly interesting for provider authors.>
|
||||
|
||||
Operations are referred to with numbers, via macros with names
|
||||
starting with C<OSSL_OP_>.
|
||||
|
||||
With each operation comes a set of defined function types that a
|
||||
provider may or may not offer, depending on its needs.
|
||||
|
||||
Currently available operations are:
|
||||
|
||||
=over 4
|
||||
|
||||
=item Digests
|
||||
|
||||
In the OpenSSL libraries, the corresponding method object is
|
||||
B<EVP_MD>.
|
||||
The number for this operation is B<OSSL_OP_DIGEST>.
|
||||
The functions the provider can offer are described in
|
||||
L<provider-digest(7)>
|
||||
|
||||
=item Symmetric ciphers
|
||||
|
||||
In the OpenSSL libraries, the corresponding method object is
|
||||
B<EVP_CIPHER>.
|
||||
The number for this operation is B<OSSL_OP_CIPHER>.
|
||||
The functions the provider can offer are described in
|
||||
L<provider-cipher(7)>
|
||||
|
||||
=begin comment NOT AVAILABLE YET
|
||||
|
||||
=item Message Authentication Code (MAC)
|
||||
|
||||
In the OpenSSL libraries, the corresponding method object is
|
||||
B<EVP_MAC>.
|
||||
The number for this operation is B<OSSL_OP_MAC>.
|
||||
The functions the provider can offer are described in
|
||||
L<provider-mac(7)>
|
||||
|
||||
=end comment
|
||||
|
||||
=begin comment NOT AVAILABLE YET
|
||||
|
||||
=item Key Derivation Function (KDF)
|
||||
|
||||
In the OpenSSL libraries, the corresponding method object is
|
||||
B<EVP_KDF>.
|
||||
The number for this operation is B<OSSL_OP_KDF>.
|
||||
The functions the provider can offer are described in
|
||||
L<provider-kdf(7)>
|
||||
|
||||
=end comment
|
||||
|
||||
=item Key Exchange
|
||||
|
||||
In the OpenSSL libraries, the corresponding method object is
|
||||
B<EVP_KEYEXCh>.
|
||||
The number for this operation is B<OSSL_OP_KEYEXCH>.
|
||||
The functions the provider can offer are described in
|
||||
L<provider-keyexch(7)>
|
||||
|
||||
=back
|
||||
|
||||
=head2 Fetching algorithms
|
||||
|
||||
=head3 Explicit fetch
|
||||
|
||||
I<NOTE: This section is mostly interesting to OpenSSL users.>
|
||||
|
||||
Users of the OpenSSL libraries never query the provider directly for
|
||||
its diverse implementations and dispatch tables.
|
||||
Instead, the diverse OpenSSL APIs often have fetching functions that
|
||||
do the work, and they return an appropriate method object back to the
|
||||
user.
|
||||
These functions usually have the name C<APINAME_fetch>, where
|
||||
C<APINAME> is the name of the API, for example L<EVP_MD_fetch(3)>.
|
||||
|
||||
These fetching functions follow a fairly common pattern, where three
|
||||
arguments are passed:
|
||||
|
||||
=over 4
|
||||
|
||||
=item The library context
|
||||
|
||||
See L<OPENSSL_CTX(3)> for a more detailed description.
|
||||
This may be NULL to signify the default (global) library context, or a
|
||||
context created by the user.
|
||||
Only providers loaded in this library context (see
|
||||
L<OSSL_PROVIDER_load(3)>) will be considered by the fetching
|
||||
function.
|
||||
|
||||
=item An identifier
|
||||
|
||||
This is most commonly an algorithm name (this is the case for all EVP
|
||||
methods), but may also be called something else.
|
||||
|
||||
=for comment For example, an OSSL_STORE implementation would use the
|
||||
URI scheme as an identifier.
|
||||
|
||||
=item A property query string
|
||||
|
||||
See L<property(7)> for a more detailed description.
|
||||
This is used to select more exactly which providers will get to offer
|
||||
an implementation.
|
||||
|
||||
=back
|
||||
|
||||
The method object that is fetched can then be used with diverse other
|
||||
functions that use them, for example L<EVP_DigestInit_ex(3)>.
|
||||
|
||||
=head2 Implicit fetch
|
||||
|
||||
I<NOTE: This section is mostly interesting to OpenSSL users.>
|
||||
|
||||
OpenSSL has a number of functions that return a method object with no
|
||||
associated implementation, such as L<EVP_sha256(3)>,
|
||||
L<EVP_blake2b512(3)> or L<EVP_aes_128_cbc(3)>, which are present for
|
||||
compatibility with OpenSSL before version 3.0.
|
||||
|
||||
When they are used with functions like L<EVP_DigestInit_ex(3)> or
|
||||
L<EVP_CipherInit_ex(3)>, the actual implementation to be used is
|
||||
fetched implicitly using default search criteria.
|
||||
|
||||
Implicit fetching can also occur with functions such as
|
||||
L<EVP_PKEY_CTX_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.
|
||||
|
||||
=head1 OPENSSL PROVIDERS
|
||||
|
||||
OpenSSL comes with a set of providers.
|
||||
All the algorithm names mentioned can be used as an algorithm
|
||||
identifier to the appropriate fetching function.
|
||||
|
||||
=head2 Default provider
|
||||
|
||||
The default provider is built in as part of the F<libcrypto> library.
|
||||
Should it be needed (if other providers are loaded and offer
|
||||
implementations of the same algorithms), the property "default=yes"
|
||||
can be used as a search criterion for these implementations.
|
||||
|
||||
It currently offers the following named algorithms:
|
||||
|
||||
=over 4
|
||||
|
||||
=item Digests
|
||||
|
||||
SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
|
||||
SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3,
|
||||
BLAKE2b512, BLAKE2s256, KMAC128, KMAC256, MD5, MD5-SHA1
|
||||
|
||||
=item Symmetric ciphers
|
||||
|
||||
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, id-aes128-GCM
|
||||
|
||||
=item Key Exchange
|
||||
|
||||
dhKeyAgreement
|
||||
|
||||
=back
|
||||
|
||||
=head2 FIPS provider
|
||||
|
||||
The FIPS provider is a dynamically loadable module, and must therefore
|
||||
be loaded explicitly, either in code or through OpenSSL configuration
|
||||
(see L<config(5)>).
|
||||
Should it be needed (if other providers are loaded and offer
|
||||
implementations of the same algorithms), the property "fips=yes" can
|
||||
be used as a search criterion for these implementations.
|
||||
|
||||
It currently offers the following FIPS approved named algorithms:
|
||||
|
||||
=over 4
|
||||
|
||||
=item Digests
|
||||
|
||||
SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
|
||||
SHA3-224, SHA3-256, SHA3-384, SHA3-512, KMAC128, KMAC256
|
||||
|
||||
=item Symmetric ciphers
|
||||
|
||||
AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
|
||||
AES-128-CBC, AES-256-CTR, AES-192-CTR, AES-128-CTR
|
||||
|
||||
=back
|
||||
|
||||
=head2 Legacy provider
|
||||
|
||||
The legacy provider is a dynamically loadable module, and must therefore
|
||||
be loaded explicitly, either in code or through OpenSSL configuration
|
||||
(see L<config(5)>).
|
||||
Should it be needed (if other providers are loaded and offer
|
||||
implementations of the same algorithms), the property "legacy=yes" can be
|
||||
used as a search criterion for these implementations.
|
||||
|
||||
It currently offers the following named algorithms:
|
||||
|
||||
=over 4
|
||||
|
||||
=item Digest algorithms:
|
||||
|
||||
RIPEMD160, MD2, MD4, MDC2, whirlpool.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
=head2 Fetching
|
||||
|
||||
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_PKEY_derive_init_ex(3)>,
|
||||
L<OPENSSL_CTX(3)>,
|
||||
L<EVP_set_default_properties(3)>,
|
||||
L<EVP_MD_fetch(3)>,
|
||||
L<EVP_CIPHER_fetch(3)>,
|
||||
L<EVP_KEYMGMT_fetch(3)>,
|
||||
L<openssl-core.h(7)>,
|
||||
L<provider-base(7)>,
|
||||
L<provider-digest(7)>,
|
||||
L<provider-cipher(7)>,
|
||||
L<provider-keyexch(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The concept of providers and everything surrounding them was
|
||||
introduced 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