Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PROVIDER(7)			    OpenSSL			   PROVIDER(7)

NAME
       provider	- OpenSSL operation implementation providers

SYNOPSIS
       #include	<openssl/provider.h>

DESCRIPTION
   General
       A 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 operation is something one wants to do, such as encryption and
       decryption, key derivation, MAC calculation, signing and	verification,
       etc.

       An 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.

   Provider
       NOTE: This section is mostly interesting	for provider authors.

       A provider offers an initialization function, as	a set of base
       functions in the	form of	an OSSL_DISPATCH array,	and by extension, a
       set of OSSL_ALGORITHMs (see 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 "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_CORE_HANDLE	*handle,
		 const OSSL_DISPATCH *in, const	OSSL_DISPATCH **out,
		 void **provctx);

       handle 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 is passed	to some	of the
       functions given in the dispatch array in.

       in is a dispatch	array of base functions	offered	by the OpenSSL
       libraries, and the available functions are further described in
       provider-base(7).

       *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	provider-base(7), and they are the
       central means of	communication between the OpenSSL libraries and	the
       provider.

       *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 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);

       provctx is the provider specific	context	that was passed	back by	the
       initialization function.

       operation_id is an operation identity (see "Operations" below).

       no_store	is a flag back to the OpenSSL libraries	which, when nonzero,
       signifies that the OpenSSL libraries will not store a reference to the
       returned	data in	their internal store of	implementations.

       The returned OSSL_ALGORITHM is the foundation of	any OpenSSL library
       API that	uses providers for their implementation, most commonly in the
       fetching	type of	functions (see "Fetching algorithms" below).

   Operations
       NOTE: This section is mostly interesting	for provider authors.

       Operations are referred to with numbers,	via macros with	names starting
       with "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:

       Digests
	   In the OpenSSL libraries, the corresponding method object is
	   EVP_MD.  The	number for this	operation is OSSL_OP_DIGEST.  The
	   functions the provider can offer are	described in
	   provider-digest(7)

       Symmetric ciphers
	   In the OpenSSL libraries, the corresponding method object is
	   EVP_CIPHER.	The number for this operation is OSSL_OP_CIPHER.  The
	   functions the provider can offer are	described in
	   provider-cipher(7)

       Message Authentication Code (MAC)
	   In the OpenSSL libraries, the corresponding method object is
	   EVP_MAC.  The number	for this operation is OSSL_OP_MAC.  The
	   functions the provider can offer are	described in provider-mac(7)

       Key Derivation Function (KDF)
	   In the OpenSSL libraries, the corresponding method object is
	   EVP_KDF.  The number	for this operation is OSSL_OP_KDF.  The
	   functions the provider can offer are	described in provider-kdf(7)

       Key Exchange
	   In the OpenSSL libraries, the corresponding method object is
	   EVP_KEYEXCH.	 The number for	this operation is OSSL_OP_KEYEXCH.
	   The functions the provider can offer	are described in
	   provider-keyexch(7)

       Asymmetric Ciphers
	   In the OpenSSL libraries, the corresponding method object is
	   EVP_ASYM_CIPHER.  The number	for this operation is
	   OSSL_OP_ASYM_CIPHER.	 The functions the provider can	offer are
	   described in	provider-asym_cipher(7)

       Asymmetric Key Encapsulation
	   In the OpenSSL libraries, the corresponding method object is
	   EVP_KEM.  The number	for this operation is OSSL_OP_KEM.  The
	   functions the provider can offer are	described in provider-kem(7)

       Encoding
	   In the OpenSSL libraries, the corresponding method object is
	   OSSL_ENCODER.  The number for this operation	is OSSL_OP_ENCODER.
	   The functions the provider can offer	are described in
	   provider-encoder(7)

   Fetching algorithms
       Explicit	fetch

       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 "APINAME_fetch", where "APINAME" is the name of
       the API,	for example EVP_MD_fetch(3).

       These fetching functions	follow a fairly	common pattern,	where three
       arguments are passed:

       The library context
	   See OSSL_LIB_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	OSSL_PROVIDER_load(3)) will be considered by the fetching
	   function. In	case no	provider has been loaded in this library
	   context the default provider	will be	loaded as fallback (see
	   OSSL_PROVIDER-default(7)).

       An identifier
	   This	is most	commonly an algorithm name (this is the	case for all
	   EVP methods), but may also be called	something else.

       A property query	string
	   See property(7) for a more detailed description.  This is used to
	   select more exactly which providers will get	to offer an
	   implementation.

       The method object that is fetched can then be used with diverse other
       functions that use them,	for example EVP_DigestInit_ex(3).

       Implicit	fetch

       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 EVP_sha256(3), EVP_blake2b512(3) or
       EVP_aes_128_cbc(3), which are present for compatibility with OpenSSL
       before version 3.0.

       When they are used with functions like EVP_DigestInit_ex(3) or
       EVP_CipherInit_ex(3), the actual	implementation to be used is fetched
       implicitly using	default	search criteria.

       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.

       Algorithm naming

       Algorithm names are case	insensitive. Any particular algorithm can have
       multiple	aliases	associated with	it. The	canonical OpenSSL naming
       scheme follows this format:

       ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]

       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.

       SUBNAME may be present where multiple algorithms	are combined together,
       e.g. MD5-SHA1.

       SIZE is only present if multiple	versions of an algorithm exist with
       different sizes (e.g. AES-128-CBC, AES-256-CBC)

       MODE is only present where applicable.

       Other aliases may exist for example where standards bodies or common
       practice	use alternative	names or names that OpenSSL has	used
       historically.

OPENSSL	PROVIDERS
       OpenSSL comes with a set	of providers.

       The algorithms available	in each	of these providers may vary due	to
       build time configuration	options. The openssl-list(1) command can be
       used to list the	currently available algorithms.

       The names of the	algorithms shown from openssl-list(1) can be used as
       an algorithm identifier to the appropriate fetching function.

   Default provider
       The default provider is built in	as part	of the 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.	 The default provider includes all the functionality
       of the base provider below.

   Base	provider
       The base	provider is built in as	part of	the libcrypto library.	Should
       it be needed (if	other providers	are loaded and offer implementations
       of the same algorithms),	the property "provider=base" can be used as a
       search criterion	for these implementations. Some	non-cryptographic
       algorithms (such	as encoders 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.

   FIPS	provider
       The FIPS	provider is a dynamically loadable module, and must therefore
       be loaded explicitly, either in code or through OpenSSL configuration
       (see config(5)).	 Should	it be needed (if other providers are loaded
       and offer 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".

   Legacy provider
       The legacy provider is a	dynamically loadable module, and must
       therefore be loaded explicitly, either in code or through OpenSSL
       configuration (see config(5)).  Should it be needed (if other providers
       are loaded and offer implementations of the same	algorithms), the
       property	"provider=legacy" can be used as a search criterion for	these
       implementations.

   Null	provider
       The null	provider is built in as	part of	the libcrypto library. It
       contains	no algorithms in it at all. When fetching algorithms the
       default provider	will be	automatically loaded if	no other provider has
       been explicitly loaded. To prevent that from happening you can
       explicitly load the null	provider.

EXAMPLES
   Fetching
       Fetch any available implementation of SHA2-256 in the default context:

	EVP_MD *md = EVP_MD_fetch(NULL,	"SHA2-256", NULL);
	...
	EVP_MD_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_free(cipher);

       Fetch an	implementation of SHA2-256 from	the default provider in	the
       default context:

	EVP_MD *md = EVP_MD_fetch(NULL,	"SHA2-256", "provider=default");
	...
	EVP_MD_free(md);

       Fetch an	implementation of SHA2-256 that	is not from the	default
       provider	in the default context:

	EVP_MD *md = EVP_MD_fetch(NULL,	"SHA2-256", "provider!=default");
	...
	EVP_MD_free(md);

       Fetch an	implementation of SHA2-256 from	the default provider in	the
       specified context:

	EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "provider=default");
	...
	EVP_MD_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", "provider=legacy");
	...
	EVP_MD_free(md);

       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 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, "SHA2-256", NULL);
	...
	EVP_MD_free(md_whirlpool);
	EVP_MD_free(md_sha256);

SEE ALSO
       EVP_DigestInit_ex(3), EVP_EncryptInit_ex(3), OSSL_LIB_CTX(3),
       EVP_set_default_properties(3), EVP_MD_fetch(3), EVP_CIPHER_fetch(3),
       EVP_KEYMGMT_fetch(3), openssl-core.h(7),	provider-base(7),
       provider-digest(7), provider-cipher(7), provider-keyexch(7)

HISTORY
       The concept of providers	and everything surrounding them	was introduced
       in OpenSSL 3.0.

COPYRIGHT
       Copyright 2019-2021 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
       <https://www.openssl.org/source/license.html>.

3.0.0-alpha12			  2021-02-18			   PROVIDER(7)

NAME | SYNOPSIS | DESCRIPTION | OPENSSL PROVIDERS | EXAMPLES | SEE ALSO | HISTORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=provider&sektion=7&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help