e4c0ec6278
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)
401 lines
12 KiB
Text
401 lines
12 KiB
Text
=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
|