provider(7ossl)

1PROVIDER(7ossl)                     OpenSSL                    PROVIDER(7ossl)
2
3
4

NAME

6       provider - OpenSSL operation implementation providers
7

SYNOPSIS

9       #include <openssl/provider.h>
10

DESCRIPTION

12   General
13       This page contains information useful to provider authors.
14
15       A provider, in OpenSSL terms, is a unit of code that provides one or
16       more implementations for various operations for diverse algorithms that
17       one might want to perform.
18
19       An operation is something one wants to do, such as encryption and
20       decryption, key derivation, MAC calculation, signing and verification,
21       etc.
22
23       An algorithm is a named method to perform an operation.  Very often,
24       the algorithms revolve around cryptographic operations, but may also
25       revolve around other types of operation, such as managing certain types
26       of objects.
27
28       See crypto(7) for further details.
29
30   Provider
31       A provider offers an initialization function, as a set of base
32       functions in the form of an OSSL_DISPATCH(3) array, and by extension, a
33       set of OSSL_ALGORITHM(3)s (see openssl-core.h(7)).  It may be a
34       dynamically loadable module, or may be built-in, in OpenSSL libraries
35       or in the application.  If it's a dynamically loadable module, the
36       initialization function must be named "OSSL_provider_init" and must be
37       exported.  If it's built-in, the initialization function may have any
38       name.
39
40       The initialization function must have the following signature:
41
42        int NAME(const OSSL_CORE_HANDLE *handle,
43                 const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
44                 void **provctx);
45
46       handle is the OpenSSL library object for the provider, and works as a
47       handle for everything the OpenSSL libraries need to know about the
48       provider.  For the provider itself, it is passed to some of the
49       functions given in the dispatch array in.
50
51       in is a dispatch array of base functions offered by the OpenSSL
52       libraries, and the available functions are further described in
53       provider-base(7).
54
55       *out must be assigned a dispatch array of base functions that the
56       provider offers to the OpenSSL libraries.  The functions that may be
57       offered are further described in provider-base(7), and they are the
58       central means of communication between the OpenSSL libraries and the
59       provider.
60
61       *provctx should be assigned a provider specific context to allow the
62       provider multiple simultaneous uses.  This pointer will be passed to
63       various operation functions offered by the provider.
64
65       Note that the provider will not be made available for applications to
66       use until the initialization function has completed and returned
67       successfully.
68
69       One of the functions the provider offers to the OpenSSL libraries is
70       the central mechanism for the OpenSSL libraries to get access to
71       operation implementations for diverse algorithms.  Its referred to with
72       the number OSSL_FUNC_PROVIDER_QUERY_OPERATION and has the following
73       signature:
74
75        const OSSL_ALGORITHM *provider_query_operation(void *provctx,
76                                                       int operation_id,
77                                                       const int *no_store);
78
79       provctx is the provider specific context that was passed back by the
80       initialization function.
81
82       operation_id is an operation identity (see "Operations" below).
83
84       no_store is a flag back to the OpenSSL libraries which, when nonzero,
85       signifies that the OpenSSL libraries will not store a reference to the
86       returned data in their internal store of implementations.
87
88       The returned OSSL_ALGORITHM(3) is the foundation of any OpenSSL library
89       API that uses providers for their implementation, most commonly in the
90       fetching type of functions (see "ALGORITHM FETCHING" in crypto(7)).
91
92   Operations
93       Operations are referred to with numbers, via macros with names starting
94       with "OSSL_OP_".
95
96       With each operation comes a set of defined function types that a
97       provider may or may not offer, depending on its needs.
98
99       Currently available operations are:
100
101       Digests
102           In the OpenSSL libraries, the corresponding method object is
103           EVP_MD.  The number for this operation is OSSL_OP_DIGEST.  The
104           functions the provider can offer are described in
105           provider-digest(7).
106
107       Symmetric ciphers
108           In the OpenSSL libraries, the corresponding method object is
109           EVP_CIPHER.  The number for this operation is OSSL_OP_CIPHER.  The
110           functions the provider can offer are described in
111           provider-cipher(7).
112
113       Message Authentication Code (MAC)
114           In the OpenSSL libraries, the corresponding method object is
115           EVP_MAC.  The number for this operation is OSSL_OP_MAC.  The
116           functions the provider can offer are described in provider-mac(7).
117
118       Key Derivation Function (KDF)
119           In the OpenSSL libraries, the corresponding method object is
120           EVP_KDF.  The number for this operation is OSSL_OP_KDF.  The
121           functions the provider can offer are described in provider-kdf(7).
122
123       Key Exchange
124           In the OpenSSL libraries, the corresponding method object is
125           EVP_KEYEXCH.  The number for this operation is OSSL_OP_KEYEXCH.
126           The functions the provider can offer are described in
127           provider-keyexch(7).
128
129       Asymmetric Ciphers
130           In the OpenSSL libraries, the corresponding method object is
131           EVP_ASYM_CIPHER.  The number for this operation is
132           OSSL_OP_ASYM_CIPHER.  The functions the provider can offer are
133           described in provider-asym_cipher(7).
134
135       Asymmetric Key Encapsulation
136           In the OpenSSL libraries, the corresponding method object is
137           EVP_KEM.  The number for this operation is OSSL_OP_KEM.  The
138           functions the provider can offer are described in provider-kem(7).
139
140       Encoding
141           In the OpenSSL libraries, the corresponding method object is
142           OSSL_ENCODER.  The number for this operation is OSSL_OP_ENCODER.
143           The functions the provider can offer are described in
144           provider-encoder(7).
145
146       Decoding
147           In the OpenSSL libraries, the corresponding method object is
148           OSSL_DECODER.  The number for this operation is OSSL_OP_DECODER.
149           The functions the provider can offer are described in
150           provider-decoder(7).
151
152       Random Number Generation
153           The number for this operation is OSSL_OP_RAND.  The functions the
154           provider can offer for random number generation are described in
155           provider-rand(7).
156
157       Key Management
158           The number for this operation is OSSL_OP_KEYMGMT.  The functions
159           the provider can offer for key management are described in
160           provider-keymgmt(7).
161
162       Signing and Signature Verification
163           The number for this operation is OSSL_OP_SIGNATURE.  The functions
164           the provider can offer for digital signatures are described in
165           provider-signature(7).
166
167       Store Management
168           The number for this operation is OSSL_OP_STORE.  The functions the
169           provider can offer for store management are described in
170           provider-storemgmt(7).
171
172       Algorithm naming
173
174       Algorithm names are case insensitive. Any particular algorithm can have
175       multiple aliases associated with it. The canonical OpenSSL naming
176       scheme follows this format:
177
178       ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]
179
180       VERSION is only present if there are multiple versions of an algorithm
181       (e.g.  MD2, MD4, MD5).  It may be omitted if there is only one version.
182
183       SUBNAME may be present where multiple algorithms are combined together,
184       e.g. MD5-SHA1.
185
186       SIZE is only present if multiple versions of an algorithm exist with
187       different sizes (e.g. AES-128-CBC, AES-256-CBC)
188
189       MODE is only present where applicable.
190
191       Other aliases may exist for example where standards bodies or common
192       practice use alternative names or names that OpenSSL has used
193       historically.
194

OPENSSL PROVIDERS

196       OpenSSL provides a number of its own providers. These are the default,
197       base, fips, legacy and null providers. See crypto(7) for an overview of
198       these providers.
199

HISTORY

207       The concept of providers and everything surrounding them was introduced
208       in OpenSSL 3.0.
209

COPYRIGHT

211       Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
212
213       Licensed under the Apache License 2.0 (the "License").  You may not use
214       this file except in compliance with the License.  You can obtain a copy
215       in the file LICENSE in the source distribution or at
216       <https://www.openssl.org/source/license.html>.
217
218
219
2203.1.1                             2023-08-31                   PROVIDER(7ossl)

NAME

SYNOPSIS

DESCRIPTION

OPENSSL PROVIDERS

SEE ALSO

HISTORY

COPYRIGHT