Debian Codegraph @

upstream/debian-unstable/man7/provider.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PROVIDER 7SSL"
58 .TH PROVIDER 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 provider \- OpenSSL operation implementation providers
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 #include <openssl/provider.h>
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 .SS General
71 .IX Subsection "General"
72 This page contains information useful to provider authors.
73 .PP
74 A \fIprovider\fR, in OpenSSL terms, is a unit of code that provides one
75 or more implementations for various operations for diverse algorithms
76 that one might want to perform.
77 .PP
78 An \fIoperation\fR is something one wants to do, such as encryption and
79 decryption, key derivation, MAC calculation, signing and verification,
80 etc.
81 .PP
82 An \fIalgorithm\fR is a named method to perform an operation.
83 Very often, the algorithms revolve around cryptographic operations,
84 but may also revolve around other types of operation, such as managing
85 certain types of objects.
86 .PP
87 See \fBcrypto\fR\|(7) for further details.
88 .SS Provider
89 .IX Subsection "Provider"
90 A \fIprovider\fR offers an initialization function, as a set of base
91 functions in the form of an \fBOSSL_DISPATCH\fR\|(3) array, and by extension,
92 a set of \fBOSSL_ALGORITHM\fR\|(3)s (see \fBopenssl\-core.h\fR\|(7)).
93 It may be a dynamically loadable module, or may be built-in, in
94 OpenSSL libraries or in the application.
95 If it's a dynamically loadable module, the initialization function
96 must be named \f(CW\*(C`OSSL_provider_init\*(C'\fR and must be exported.
97 If it's built-in, the initialization function may have any name.
98 .PP
99 The initialization function must have the following signature:
100 .PP
101 .Vb 3
102 \& int NAME(const OSSL_CORE_HANDLE *handle,
103 \& const OSSL_DISPATCH *in, const OSSL_DISPATCH **out,
104 \& void **provctx);
105 .Ve
106 .PP
107 \&\fIhandle\fR is the OpenSSL library object for the provider, and works
108 as a handle for everything the OpenSSL libraries need to know about
109 the provider.
110 For the provider itself, it is passed to some of the functions given in the
111 dispatch array \fIin\fR.
112 .PP
113 \&\fIin\fR is a dispatch array of base functions offered by the OpenSSL
114 libraries, and the available functions are further described in
115 \&\fBprovider\-base\fR\|(7).
116 .PP
117 \&\fI*out\fR must be assigned a dispatch array of base functions that the
118 provider offers to the OpenSSL libraries.
119 The functions that may be offered are further described in
120 \&\fBprovider\-base\fR\|(7), and they are the central means of communication
121 between the OpenSSL libraries and the provider.
122 .PP
123 \&\fI*provctx\fR should be assigned a provider specific context to allow
124 the provider multiple simultaneous uses.
125 This pointer will be passed to various operation functions offered by
126 the provider.
127 .PP
128 Note that the provider will not be made available for applications to use until
129 the initialization function has completed and returned successfully.
130 .PP
131 One of the functions the provider offers to the OpenSSL libraries is
132 the central mechanism for the OpenSSL libraries to get access to
133 operation implementations for diverse algorithms.
134 Its referred to with the number \fBOSSL_FUNC_PROVIDER_QUERY_OPERATION\fR
135 and has the following signature:
136 .PP
137 .Vb 3
138 \& const OSSL_ALGORITHM *provider_query_operation(void *provctx,
139 \& int operation_id,
140 \& const int *no_store);
141 .Ve
142 .PP
143 \&\fIprovctx\fR is the provider specific context that was passed back by
144 the initialization function.
145 .PP
146 \&\fIoperation_id\fR is an operation identity (see "Operations" below).
147 .PP
148 \&\fIno_store\fR is a flag back to the OpenSSL libraries which, when
149 nonzero, signifies that the OpenSSL libraries will not store a
150 reference to the returned data in their internal store of
151 implementations.
152 .PP
153 The returned \fBOSSL_ALGORITHM\fR\|(3) is the foundation of any OpenSSL
154 library API that uses providers for their implementation, most
155 commonly in the \fIfetching\fR type of functions
156 (see "ALGORITHM FETCHING" in \fBcrypto\fR\|(7)).
157 .SS Operations
158 .IX Subsection "Operations"
159 Operations are referred to with numbers, via macros with names
160 starting with \f(CW\*(C`OSSL_OP_\*(C'\fR.
161 .PP
162 With each operation comes a set of defined function types that a
163 provider may or may not offer, depending on its needs.
164 .PP
165 Currently available operations are:
166 .IP Digests 4
167 .IX Item "Digests"
168 In the OpenSSL libraries, the corresponding method object is
169 \&\fBEVP_MD\fR.
170 The number for this operation is \fBOSSL_OP_DIGEST\fR.
171 The functions the provider can offer are described in
172 \&\fBprovider\-digest\fR\|(7).
173 .IP "Symmetric ciphers" 4
174 .IX Item "Symmetric ciphers"
175 In the OpenSSL libraries, the corresponding method object is
176 \&\fBEVP_CIPHER\fR.
177 The number for this operation is \fBOSSL_OP_CIPHER\fR.
178 The functions the provider can offer are described in
179 \&\fBprovider\-cipher\fR\|(7).
180 .IP "Message Authentication Code (MAC)" 4
181 .IX Item "Message Authentication Code (MAC)"
182 In the OpenSSL libraries, the corresponding method object is
183 \&\fBEVP_MAC\fR.
184 The number for this operation is \fBOSSL_OP_MAC\fR.
185 The functions the provider can offer are described in
186 \&\fBprovider\-mac\fR\|(7).
187 .IP "Key Derivation Function (KDF)" 4
188 .IX Item "Key Derivation Function (KDF)"
189 In the OpenSSL libraries, the corresponding method object is
190 \&\fBEVP_KDF\fR.
191 The number for this operation is \fBOSSL_OP_KDF\fR.
192 The functions the provider can offer are described in
193 \&\fBprovider\-kdf\fR\|(7).
194 .IP "Key Exchange" 4
195 .IX Item "Key Exchange"
196 In the OpenSSL libraries, the corresponding method object is
197 \&\fBEVP_KEYEXCH\fR.
198 The number for this operation is \fBOSSL_OP_KEYEXCH\fR.
199 The functions the provider can offer are described in
200 \&\fBprovider\-keyexch\fR\|(7).
201 .IP "Asymmetric Ciphers" 4
202 .IX Item "Asymmetric Ciphers"
203 In the OpenSSL libraries, the corresponding method object is
204 \&\fBEVP_ASYM_CIPHER\fR.
205 The number for this operation is \fBOSSL_OP_ASYM_CIPHER\fR.
206 The functions the provider can offer are described in
207 \&\fBprovider\-asym_cipher\fR\|(7).
208 .IP "Asymmetric Key Encapsulation" 4
209 .IX Item "Asymmetric Key Encapsulation"
210 In the OpenSSL libraries, the corresponding method object is \fBEVP_KEM\fR.
211 The number for this operation is \fBOSSL_OP_KEM\fR.
212 The functions the provider can offer are described in \fBprovider\-kem\fR\|(7).
213 .IP Encoding 4
214 .IX Item "Encoding"
215 In the OpenSSL libraries, the corresponding method object is
216 \&\fBOSSL_ENCODER\fR.
217 The number for this operation is \fBOSSL_OP_ENCODER\fR.
218 The functions the provider can offer are described in
219 \&\fBprovider\-encoder\fR\|(7).
220 .IP Decoding 4
221 .IX Item "Decoding"
222 In the OpenSSL libraries, the corresponding method object is
223 \&\fBOSSL_DECODER\fR.
224 The number for this operation is \fBOSSL_OP_DECODER\fR.
225 The functions the provider can offer are described in
226 \&\fBprovider\-decoder\fR\|(7).
227 .IP "Random Number Generation" 4
228 .IX Item "Random Number Generation"
229 The number for this operation is \fBOSSL_OP_RAND\fR.
230 The functions the provider can offer for random number generation are described
231 in \fBprovider\-rand\fR\|(7).
232 .IP "Key Management" 4
233 .IX Item "Key Management"
234 The number for this operation is \fBOSSL_OP_KEYMGMT\fR.
235 The functions the provider can offer for key management are described in
236 \&\fBprovider\-keymgmt\fR\|(7).
237 .IP "Signing and Signature Verification" 4
238 .IX Item "Signing and Signature Verification"
239 The number for this operation is \fBOSSL_OP_SIGNATURE\fR.
240 The functions the provider can offer for digital signatures are described in
241 \&\fBprovider\-signature\fR\|(7).
242 .IP "Store Management" 4
243 .IX Item "Store Management"
244 The number for this operation is \fBOSSL_OP_STORE\fR.
245 The functions the provider can offer for store management are described in
246 \&\fBprovider\-storemgmt\fR\|(7).
247 .PP
248 \fIAlgorithm naming\fR
249 .IX Subsection "Algorithm naming"
250 .PP
251 Algorithm names are case insensitive. Any particular algorithm can have multiple
252 aliases associated with it. The canonical OpenSSL naming scheme follows this
253 format:
254 .PP
255 ALGNAME[VERSION?][\-SUBNAME[VERSION?]?][\-SIZE?][\-MODE?]
256 .PP
257 VERSION is only present if there are multiple versions of an algorithm (e.g.
258 MD2, MD4, MD5). It may be omitted if there is only one version.
259 .PP
260 SUBNAME may be present where multiple algorithms are combined together,
261 e.g. MD5\-SHA1.
262 .PP
263 SIZE is only present if multiple versions of an algorithm exist with different
264 sizes (e.g. AES\-128\-CBC, AES\-256\-CBC)
265 .PP
266 MODE is only present where applicable.
267 .PP
268 Other aliases may exist for example where standards bodies or common practice
269 use alternative names or names that OpenSSL has used historically.
270 .PP
271 \fIProvider dependencies\fR
272 .IX Subsection "Provider dependencies"
273 .PP
274 Providers may depend for their proper operation on the availability of
275 (functionality implemented in) other providers. As there is no mechanism to
276 express such dependencies towards the OpenSSL core, provider authors must
277 take care that such dependencies are either completely avoided or made visible
278 to users, e.g., by documentation and/or defensive programming, e.g.,
279 outputting error messages if required external dependencies are not available,
280 e.g., when no provider implementing the required functionality has been
281 activated. In particular, provider initialization should not depend on other
282 providers already having been initialized.
283 .PP
284 \fINote on naming clashes\fR
285 .IX Subsection "Note on naming clashes"
286 .PP
287 It is possible to register the same algorithm name from within different
288 providers. Users should note that if no property query is specified, or
289 more than one implementation matches the property query then it is
290 unspecified which implementation of a particular algorithm will be returned.
291 Such naming clashes may also occur if algorithms only differ in
292 capitalization as "Algorithm naming" is case insensitive.
293 .SH "OPENSSL PROVIDERS"
294 .IX Header "OPENSSL PROVIDERS"
295 OpenSSL provides a number of its own providers. These are the default, base,
296 fips, legacy and null providers. See \fBcrypto\fR\|(7) for an overview of these
297 providers.
298 .SH "SEE ALSO"
299 .IX Header "SEE ALSO"
300 \&\fBEVP_DigestInit_ex\fR\|(3), \fBEVP_EncryptInit_ex\fR\|(3),
301 \&\fBOSSL_LIB_CTX\fR\|(3),
302 \&\fBEVP_set_default_properties\fR\|(3),
303 \&\fBEVP_MD_fetch\fR\|(3),
304 \&\fBEVP_CIPHER_fetch\fR\|(3),
305 \&\fBEVP_KEYMGMT_fetch\fR\|(3),
306 \&\fBopenssl\-core.h\fR\|(7),
307 \&\fBprovider\-base\fR\|(7),
308 \&\fBprovider\-digest\fR\|(7),
309 \&\fBprovider\-cipher\fR\|(7),
310 \&\fBprovider\-keyexch\fR\|(7)
311 .SH HISTORY
312 .IX Header "HISTORY"
313 The concept of providers and everything surrounding them was
314 introduced in OpenSSL 3.0.
315 .SH COPYRIGHT
316 .IX Header "COPYRIGHT"
317 Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved.
318 .PP
319 Licensed under the Apache License 2.0 (the "License"). You may not use
320 this file except in compliance with the License. You can obtain a copy
321 in the file LICENSE in the source distribution or at
322 <https://www.openssl.org/source/license.html>.