=head1 SYNOPSIS
-=for comment generic
+=for openssl generic
#include <openssl/provider.h>
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
+nonzero, signifies that the OpenSSL libraries will not store a
reference to the returned data in their internal store of
implementations.
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
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
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
The functions the provider can offer are described in
L<provider-keyexch(7)>
+=item Serialization
+
+In the OpenSSL libraries, the corresponding method object is
+B<OSSL_SERIALIZER>.
+The number for this operation is B<OSSL_OP_SERIALIZER>.
+The functions the provider can offer are described in
+L<provider-serializer(7)>
+
=back
=head2 Fetching algorithms
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
+Implicit fetching can also occur when 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
+=head3 Algorithm naming
-OpenSSL comes with a set of providers.
-All the algorithm names mentioned can be used as an algorithm
-identifier to the appropriate fetching function.
+Algorithm names are case insensitive. Any particular algorithm can have multiple
+aliases associated with it. The canonical OpenSSL naming scheme follows this
+format:
-=head2 Default provider
+ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]
-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.
+VERSION is only present if there are multiple versions of an algorithm (e.g.
+MD2, MD4, MD5). It may be omitted if there is only one version.
-It currently offers the following named algorithms:
+SUBNAME may be present where multiple algorithms are combined together,
+e.g. MD5-SHA1.
-=over 4
+SIZE is only present if multiple versions of an algorithm exist with different
+sizes (e.g. AES-128-CBC, AES-256-CBC)
-=item Digests
+MODE is only present where applicable.
-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
+Other aliases may exist for example where standards bodies or common practice
+use alternative names or names that OpenSSL has used historically.
-=item Symmetric ciphers
+=head1 OPENSSL PROVIDERS
-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
+OpenSSL comes with a set of providers.
-=item Key Exchange
+The algorithms available in each of these providers may vary due to build time
+configuration options. The L<openssl-list(1)> command can be used to list the
+currently available algorithms.
-dhKeyAgreement
+The names of the algorithms shown from L<openssl-list(1)> can be used as an
+algorithm identifier to the appropriate fetching function.
-=back
+=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 "provider=default"
+can be used as a search criterion for these implementations. Some
+non-cryptographic algorithms (such as serializers for loading keys and
+parameters from files) are not FIPS algorithm implementations in themselves but
+support algorithms from the FIPS provider and are allowed for use in "FIPS
+mode". The property "fips=yes" can be used to select such algorithms.
=head2 FIPS provider
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
+implementations of the same algorithms), the property "provider=fips" can
+be used as a search criterion for these implementations. All approved algorithm
+implementations in the FIPS provider can also be selected with the property
+"fips=yes". The FIPS provider also contains a number of non-approved algorithm
+implementations and these can be selected with the property "fips=no".
=head2 Legacy provider
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
+implementations of the same algorithms), the property "provider=legacy" 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:
+Fetch any available implementation of SHA2-256 in the default context:
- EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
...
EVP_MD_meth_free(md);
...
EVP_CIPHER_meth_free(cipher);
-Fetch an implementation of SHA256 from the default provider in the default
+Fetch an implementation of SHA2-256 from the default provider in the default
context:
- EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider=default");
...
EVP_MD_meth_free(md);
-Fetch an implementation of SHA256 that is not from the default provider in the
+Fetch an implementation of SHA2-256 that is not from the default provider in the
default context:
- EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "provider!=default");
...
EVP_MD_meth_free(md);
-Fetch an implementation of SHA256 from the default provider in the specified
+Fetch an implementation of SHA2-256 from the default provider in the specified
context:
- EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
+ EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default");
...
EVP_MD_meth_free(md);
Load the legacy provider into the default context and then fetch an
-implementation of whirlpool from it:
+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 *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "provider=legacy");
...
EVP_MD_meth_free(md);
-Note that in the above example the property string "legacy=yes" is optional
+Note that in the above example the property string "provider=legacy" 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
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 *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", 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)>,
=head1 COPYRIGHT
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2020 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
projects / openssl.git / blobdiff