xref: /freebsd/secure/lib/libcrypto/man/man7/provider.7 (revision 4c9a0adad18263ec8725d9bfc5f560c6ad1da8bd)
Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)

Standard preamble:
========================================================================
..
..
.. Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.

If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.

Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================

Title "PROVIDER 7ossl"
PROVIDER 7ossl "2023-09-19" "3.0.11" "OpenSSL"
For nroff, turn off justification. Always turn off hyphenation; it makes
way too many mistakes in technical documents.
"NAME"
provider - OpenSSL operation implementation providers
"SYNOPSIS"
Header "SYNOPSIS" #include <openssl/provider.h>
"DESCRIPTION"
Header "DESCRIPTION"
"General"
Subsection "General" This page contains information useful to provider authors.

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, \s-1MAC\s0 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.

See crypto\|(7) for further details.

"Provider"
Subsection "Provider" A provider offers an initialization function, as a set of base functions in the form of an \s-1OSSL_DISPATCH\s0\|(3) array, and by extension, a set of \s-1OSSL_ALGORITHM\s0\|(3)s (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 \*(C`OSSL_provider_init\*(C' and must be exported. If it's built-in, the initialization function may have any name.

The initialization function must have the following signature:

.Vb 3 int NAME(const OSSL_CORE_HANDLE *handle, const OSSL_DISPATCH *in, const OSSL_DISPATCH **out, void **provctx); .Ve

\fIhandle 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.

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

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

\fI*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.

Note that the provider will not be made available for applications to use until the initialization function has completed and returned successfully.

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 \s-1OSSL_FUNC_PROVIDER_QUERY_OPERATION\s0 and has the following signature:

.Vb 3 const OSSL_ALGORITHM *provider_query_operation(void *provctx, int operation_id, const int *no_store); .Ve

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

\fIoperation_id is an operation identity (see \*(L"Operations\*(R" below).

\fIno_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 \s-1OSSL_ALGORITHM\s0\|(3) is the foundation of any OpenSSL library \s-1API\s0 that uses providers for their implementation, most commonly in the fetching type of functions (see \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in crypto\|(7)).

"Operations"
Subsection "Operations" Operations are referred to with numbers, via macros with names starting with \*(C`OSSL_OP_\*(C'.

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" 4
Item "Digests" In the OpenSSL libraries, the corresponding method object is \fB\s-1EVP_MD\s0. The number for this operation is \s-1OSSL_OP_DIGEST\s0. The functions the provider can offer are described in \fBprovider-digest\|(7).
"Symmetric ciphers" 4
Item "Symmetric ciphers" In the OpenSSL libraries, the corresponding method object is \fB\s-1EVP_CIPHER\s0. The number for this operation is \s-1OSSL_OP_CIPHER\s0. The functions the provider can offer are described in \fBprovider-cipher\|(7).
"Message Authentication Code (\s-1MAC\s0)" 4
Item "Message Authentication Code (MAC)" In the OpenSSL libraries, the corresponding method object is \fB\s-1EVP_MAC\s0. The number for this operation is \s-1OSSL_OP_MAC\s0. The functions the provider can offer are described in \fBprovider-mac\|(7).
"Key Derivation Function (\s-1KDF\s0)" 4
Item "Key Derivation Function (KDF)" In the OpenSSL libraries, the corresponding method object is \fB\s-1EVP_KDF\s0. The number for this operation is \s-1OSSL_OP_KDF\s0. The functions the provider can offer are described in \fBprovider-kdf\|(7).
"Key Exchange" 4
Item "Key Exchange" In the OpenSSL libraries, the corresponding method object is \fB\s-1EVP_KEYEXCH\s0. The number for this operation is \s-1OSSL_OP_KEYEXCH\s0. The functions the provider can offer are described in \fBprovider-keyexch\|(7).
"Asymmetric Ciphers" 4
Item "Asymmetric Ciphers" In the OpenSSL libraries, the corresponding method object is \fB\s-1EVP_ASYM_CIPHER\s0. The number for this operation is \s-1OSSL_OP_ASYM_CIPHER\s0. The functions the provider can offer are described in \fBprovider-asym_cipher\|(7).
"Asymmetric Key Encapsulation" 4
Item "Asymmetric Key Encapsulation" In the OpenSSL libraries, the corresponding method object is \s-1EVP_KEM\s0. The number for this operation is \s-1OSSL_OP_KEM\s0. The functions the provider can offer are described in provider-kem\|(7).
"Encoding" 4
Item "Encoding" In the OpenSSL libraries, the corresponding method object is \fB\s-1OSSL_ENCODER\s0. The number for this operation is \s-1OSSL_OP_ENCODER\s0. The functions the provider can offer are described in \fBprovider-encoder\|(7).
"Decoding" 4
Item "Decoding" In the OpenSSL libraries, the corresponding method object is \fB\s-1OSSL_DECODER\s0. The number for this operation is \s-1OSSL_OP_DECODER\s0. The functions the provider can offer are described in \fBprovider-decoder\|(7).
"Random Number Generation" 4
Item "Random Number Generation" The number for this operation is \s-1OSSL_OP_RAND\s0. The functions the provider can offer for random number generation are described in provider-rand\|(7).
"Key Management" 4
Item "Key Management" The number for this operation is \s-1OSSL_OP_KEYMGMT\s0. The functions the provider can offer for key management are described in \fBprovider-keymgmt\|(7).
"Signing and Signature Verification" 4
Item "Signing and Signature Verification" The number for this operation is \s-1OSSL_OP_SIGNATURE\s0. The functions the provider can offer for digital signatures are described in \fBprovider-signature\|(7).
"Store Management" 4
Item "Store Management" The number for this operation is \s-1OSSL_OP_STORE\s0. The functions the provider can offer for store management are described in \fBprovider-storemgmt\|(7).

Algorithm naming Subsection "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[\s-1VERSION\s0?][-SUBNAME[\s-1VERSION\s0?]?][-SIZE?][-MODE?]

\s-1VERSION\s0 is only present if there are multiple versions of an algorithm (e.g. \s-1MD2, MD4, MD5\s0). It may be omitted if there is only one version.

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

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

\s-1MODE\s0 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"
Header "OPENSSL PROVIDERS" OpenSSL provides a number of its own providers. These are the default, base, fips, legacy and null providers. See crypto\|(7) for an overview of these providers.
"SEE ALSO"
Header "SEE ALSO" \fBEVP_DigestInit_ex\|(3), EVP_EncryptInit_ex\|(3), \s-1OSSL_LIB_CTX\s0\|(3), \fBEVP_set_default_properties\|(3), \fBEVP_MD_fetch\|(3), \fBEVP_CIPHER_fetch\|(3), \fBEVP_KEYMGMT_fetch\|(3), \fBopenssl-core.h\|(7), \fBprovider-base\|(7), \fBprovider-digest\|(7), \fBprovider-cipher\|(7), \fBprovider-keyexch\|(7)
"HISTORY"
Header "HISTORY" The concept of providers and everything surrounding them was introduced in OpenSSL 3.0.
"COPYRIGHT"
Header "COPYRIGHT" Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.