Debian Codegraph @

upstream/debian-unstable/man7/provider-cipher.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-CIPHER 7SSL"
58 .TH PROVIDER-CIPHER 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\-cipher \- The cipher library <\-> provider functions
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& #include <openssl/core_dispatch.h>
69 \& #include <openssl/core_names.h>
70 \&
71 \& /*
72 \& * None of these are actual functions, but are displayed like this for
73 \& * the function signatures for functions that are offered as function
74 \& * pointers in OSSL_DISPATCH arrays.
75 \& */
76 \&
77 \& /* Context management */
78 \& void *OSSL_FUNC_cipher_newctx(void *provctx);
79 \& void OSSL_FUNC_cipher_freectx(void *cctx);
80 \& void *OSSL_FUNC_cipher_dupctx(void *cctx);
81 \&
82 \& /* Encryption/decryption */
83 \& int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key,
84 \& size_t keylen, const unsigned char *iv,
85 \& size_t ivlen, const OSSL_PARAM params[]);
86 \& int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key,
87 \& size_t keylen, const unsigned char *iv,
88 \& size_t ivlen, const OSSL_PARAM params[]);
89 \& int OSSL_FUNC_cipher_encrypt_skey_init(void *cctx, void *skeydata,
90 \& const unsigned char *iv, size_t ivlen,
91 \& const OSSL_PARAM params[]);
92 \& int OSSL_FUNC_cipher_encrypt_skey_init(void *cctx, void *skeydata,
93 \& const unsigned char *iv, size_t ivlen,
94 \& const OSSL_PARAM params[]);
95 \& int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl,
96 \& size_t outsize, const unsigned char *in, size_t inl);
97 \& int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl,
98 \& size_t outsize);
99 \& int OSSL_FUNC_cipher_cipher(void *cctx, unsigned char *out, size_t *outl,
100 \& size_t outsize, const unsigned char *in, size_t inl);
101 \&
102 \& /* Encryption/decryption using cipher pipeline */
103 \& int OSSL_FUNC_cipher_pipeline_encrypt_init(void *cctx, const unsigned char *key,
104 \& size_t keylen, size_t numpipes,
105 \& const unsigned char **iv, size_t ivlen,
106 \& const OSSL_PARAM params[]))
107 \& int OSSL_FUNC_cipher_pipeline_decrypt_init(void *cctx, const unsigned char *key,
108 \& size_t keylen, size_t numpipes,
109 \& const unsigned char **iv, size_t ivlen,
110 \& const OSSL_PARAM params[]))
111 \& int OSSL_FUNC_cipher_pipeline_update(void *cctx, size_t numpipes,
112 \& unsigned char **out, size_t *outl,
113 \& const size_t *outsize,
114 \& const unsigned char **in, const size_t *inl))
115 \& int OSSL_FUNC_cipher_pipeline_final(void *cctx, size_t numpipes,
116 \& unsigned char **out, size_t *outl,
117 \& const size_t *outsize))
118 \&
119 \& /* Cipher parameter descriptors */
120 \& const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void *provctx);
121 \&
122 \& /* Cipher operation parameter descriptors */
123 \& const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *cctx,
124 \& void *provctx);
125 \& const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *cctx,
126 \& void *provctx);
127 \&
128 \& /* Cipher parameters */
129 \& int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]);
130 \&
131 \& /* Cipher operation parameters */
132 \& int OSSL_FUNC_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]);
133 \& int OSSL_FUNC_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]);
134 .Ve
135 .SH DESCRIPTION
136 .IX Header "DESCRIPTION"
137 This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7)
138 for further information.
139 .PP
140 The CIPHER operation enables providers to implement cipher algorithms and make
141 them available to applications via the API functions \fBEVP_EncryptInit_ex\fR\|(3),
142 \&\fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_EncryptFinal\fR\|(3) (as well as the decrypt
143 equivalents and other related functions).
144 .PP
145 All "functions" mentioned here are passed as function pointers between
146 \&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via
147 \&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider's
148 \&\fBprovider_query_operation()\fR function
149 (see "Provider Functions" in \fBprovider\-base\fR\|(7)).
150 .PP
151 All these "functions" have a corresponding function type definition
152 named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the
153 function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named
154 \&\fBOSSL_FUNC_{name}\fR.
155 For example, the "function" \fBOSSL_FUNC_cipher_newctx()\fR has these:
156 .PP
157 .Vb 3
158 \& typedef void *(OSSL_FUNC_cipher_newctx_fn)(void *provctx);
159 \& static ossl_inline OSSL_FUNC_cipher_newctx_fn
160 \& OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf);
161 .Ve
162 .PP
163 \&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as
164 macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
165 .PP
166 .Vb 3
167 \& OSSL_FUNC_cipher_newctx OSSL_FUNC_CIPHER_NEWCTX
168 \& OSSL_FUNC_cipher_freectx OSSL_FUNC_CIPHER_FREECTX
169 \& OSSL_FUNC_cipher_dupctx OSSL_FUNC_CIPHER_DUPCTX
170 \&
171 \& OSSL_FUNC_cipher_encrypt_init OSSL_FUNC_CIPHER_ENCRYPT_INIT
172 \& OSSL_FUNC_cipher_decrypt_init OSSL_FUNC_CIPHER_DECRYPT_INIT
173 \& OSSL_FUNC_cipher_encrypt_skey_init OSSL_FUNC_CIPHER_ENCRYPT_SKEY_INIT
174 \& OSSL_FUNC_cipher_decrypt_skey_init OSSL_FUNC_CIPHER_DECRYPT_SKEY_INIT
175 \& OSSL_FUNC_cipher_update OSSL_FUNC_CIPHER_UPDATE
176 \& OSSL_FUNC_cipher_final OSSL_FUNC_CIPHER_FINAL
177 \& OSSL_FUNC_cipher_cipher OSSL_FUNC_CIPHER_CIPHER
178 \&
179 \& OSSL_FUNC_cipher_pipeline_encrypt_init OSSL_FUNC_CIPHER_PIPELINE_ENCRYPT_INIT
180 \& OSSL_FUNC_cipher_pipeline_decrypt_init OSSL_FUNC_CIPHER_PIPELINE_DECRYPT_INIT
181 \& OSSL_FUNC_cipher_pipeline_update OSSL_FUNC_CIPHER_PIPELINE_UPDATE
182 \& OSSL_FUNC_cipher_pipeline_final OSSL_FUNC_CIPHER_PIPELINE_FINAL
183 \&
184 \& OSSL_FUNC_cipher_get_params OSSL_FUNC_CIPHER_GET_PARAMS
185 \& OSSL_FUNC_cipher_get_ctx_params OSSL_FUNC_CIPHER_GET_CTX_PARAMS
186 \& OSSL_FUNC_cipher_set_ctx_params OSSL_FUNC_CIPHER_SET_CTX_PARAMS
187 \&
188 \& OSSL_FUNC_cipher_gettable_params OSSL_FUNC_CIPHER_GETTABLE_PARAMS
189 \& OSSL_FUNC_cipher_gettable_ctx_params OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS
190 \& OSSL_FUNC_cipher_settable_ctx_params OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS
191 .Ve
192 .PP
193 A cipher algorithm implementation may not implement all of these functions.
194 In order to be a consistent set of functions there must at least be a complete
195 set of "encrypt" functions, or a complete set of "decrypt" functions, or a
196 single "cipher" function. Similarly, there can be a complete set of pipeline
197 "encrypt" functions, and/or a complete set of pipeline "decrypt" functions.
198 In all cases the OSSL_FUNC_cipher_get_params and both OSSL_FUNC_cipher_newctx
199 and OSSL_FUNC_cipher_freectx functions must be present.
200 All other functions are optional.
201 .SS "Context Management Functions"
202 .IX Subsection "Context Management Functions"
203 \&\fBOSSL_FUNC_cipher_newctx()\fR should create and return a pointer to a provider side
204 structure for holding context information during a cipher operation.
205 A pointer to this context will be passed back in a number of the other cipher
206 operation function calls.
207 The parameter \fIprovctx\fR is the provider context generated during provider
208 initialisation (see \fBprovider\fR\|(7)).
209 .PP
210 \&\fBOSSL_FUNC_cipher_freectx()\fR is passed a pointer to the provider side cipher context in
211 the \fIcctx\fR parameter.
212 This function should free any resources associated with that context.
213 .PP
214 \&\fBOSSL_FUNC_cipher_dupctx()\fR should duplicate the provider side cipher context in the
215 \&\fIcctx\fR parameter and return the duplicate copy.
216 .SS "Encryption/Decryption Functions"
217 .IX Subsection "Encryption/Decryption Functions"
218 \&\fBOSSL_FUNC_cipher_encrypt_init()\fR initialises a cipher operation for encryption given a
219 newly created provider side cipher context in the \fIcctx\fR parameter.
220 The key to be used is given in \fIkey\fR which is \fIkeylen\fR bytes long.
221 The IV to be used is given in \fIiv\fR which is \fIivlen\fR bytes long.
222 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
223 using \fBOSSL_FUNC_cipher_set_ctx_params()\fR.
224 .PP
225 \&\fBOSSL_FUNC_cipher_decrypt_init()\fR is the same as \fBOSSL_FUNC_cipher_encrypt_init()\fR
226 except that it initialises the context for a decryption operation.
227 .PP
228 \&\fBOSSL_FUNC_cipher_encrypt_skey_init()\fR and
229 \&\fBOSSL_FUNC_cipher_decrypt_skey_init()\fR are variants of
230 \&\fBOSSL_FUNC_cipher_encrypt_init()\fR and \fBOSSL_FUNC_cipher_decrypt_init()\fR for working with
231 opaque objects containing provider-specific key handles instead of raw bytes.
232 .PP
233 \&\fBOSSL_FUNC_cipher_update()\fR is called to supply data to be encrypted/decrypted as part of
234 a previously initialised cipher operation.
235 The \fIcctx\fR parameter contains a pointer to a previously initialised provider
236 side context.
237 \&\fBOSSL_FUNC_cipher_update()\fR should encrypt/decrypt \fIinl\fR bytes of data at the location
238 pointed to by \fIin\fR.
239 The encrypted data should be stored in \fIout\fR and the amount of data written to
240 \&\fI*outl\fR which should not exceed \fIoutsize\fR bytes.
241 \&\fBOSSL_FUNC_cipher_update()\fR may be called multiple times for a single cipher operation.
242 It is the responsibility of the cipher implementation to handle input lengths
243 that are not multiples of the block length.
244 In such cases a cipher implementation will typically cache partial blocks of
245 input data until a complete block is obtained.
246 The pointers \fIout\fR and \fIin\fR may point to the same location, in which
247 case the encryption must be done in-place. If \fIout\fR and \fIin\fR point to different
248 locations, the requirements of \fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_DecryptUpdate\fR\|(3)
249 guarantee that the two buffers are disjoint.
250 Similarly, the requirements of \fBEVP_EncryptUpdate\fR\|(3) and \fBEVP_DecryptUpdate\fR\|(3)
251 ensure that the buffer pointed to by \fIout\fR contains sufficient room for the
252 operation being performed.
253 .PP
254 \&\fBOSSL_FUNC_cipher_final()\fR completes an encryption or decryption started through previous
255 \&\fBOSSL_FUNC_cipher_encrypt_init()\fR or \fBOSSL_FUNC_cipher_decrypt_init()\fR, and \fBOSSL_FUNC_cipher_update()\fR
256 calls.
257 The \fIcctx\fR parameter contains a pointer to the provider side context.
258 Any final encryption/decryption output should be written to \fIout\fR and the
259 amount of data written to \fI*outl\fR which should not exceed \fIoutsize\fR bytes.
260 The same expectations apply to \fIoutsize\fR as documented for
261 \&\fBEVP_EncryptFinal\fR\|(3) and \fBEVP_DecryptFinal\fR\|(3).
262 .PP
263 \&\fBOSSL_FUNC_cipher_cipher()\fR performs encryption/decryption using the provider side cipher
264 context in the \fIcctx\fR parameter that should have been previously initialised via
265 a call to \fBOSSL_FUNC_cipher_encrypt_init()\fR or \fBOSSL_FUNC_cipher_decrypt_init()\fR.
266 This should call the raw underlying cipher function without any padding.
267 This will be invoked in the provider as a result of the application calling
268 \&\fBEVP_Cipher\fR\|(3).
269 The application is responsible for ensuring that the input is a multiple of the
270 block length.
271 The data to be encrypted/decrypted will be in \fIin\fR, and it will be \fIinl\fR bytes
272 in length.
273 The output from the encryption/decryption should be stored in \fIout\fR and the
274 amount of data stored should be put in \fI*outl\fR which should be no more than
275 \&\fIoutsize\fR bytes.
276 .PP
277 \&\fBOSSL_FUNC_cipher_pipeline_encrypt_init()\fR, \fBOSSL_FUNC_cipher_pipeline_decrypt_init()\fR
278 \&\fBOSSL_FUNC_cipher_pipeline_update()\fR, and \fBOSSL_FUNC_cipher_pipeline_final()\fR are similar to
279 the non-pipeline variants, but are used when the application is using cipher pipelining.
280 The \fInumpipes\fR parameter is the number of pipes in the pipeline. The \fIiv\fR parameter
281 is an array of buffers with IVs, each \fIivlen\fR bytes long. The \fIin\fR and \fIout\fR are
282 arrays of buffer pointers. The \fIinl\fR and \fIoutl\fR, \fIoutsize\fR are arrays of size_t
283 representing corresponding buffer length as similar to the non-pipeline variants.
284 All arrays are of length \fInumpipes\fR. See \fBEVP_CipherPipelineEncryptInit\fR\|(3) for more
285 information.
286 .SS "Cipher Parameters"
287 .IX Subsection "Cipher Parameters"
288 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by
289 these functions.
290 .PP
291 \&\fBOSSL_FUNC_cipher_get_params()\fR gets details of the algorithm implementation
292 and stores them in \fIparams\fR.
293 .PP
294 \&\fBOSSL_FUNC_cipher_set_ctx_params()\fR sets cipher operation parameters for the
295 provider side cipher context \fIcctx\fR to \fIparams\fR.
296 Any parameter settings are additional to any that were previously set.
297 Passing NULL for \fIparams\fR should return true.
298 .PP
299 \&\fBOSSL_FUNC_cipher_get_ctx_params()\fR gets cipher operation details details from
300 the given provider side cipher context \fIcctx\fR and stores them in \fIparams\fR.
301 Passing NULL for \fIparams\fR should return true.
302 .PP
303 \&\fBOSSL_FUNC_cipher_gettable_params()\fR, \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR,
304 and \fBOSSL_FUNC_cipher_settable_ctx_params()\fR all return constant \fBOSSL_PARAM\fR\|(3)
305 arrays as descriptors of the parameters that \fBOSSL_FUNC_cipher_get_params()\fR,
306 \&\fBOSSL_FUNC_cipher_get_ctx_params()\fR, and \fBOSSL_FUNC_cipher_set_ctx_params()\fR
307 can handle, respectively. \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR and
308 \&\fBOSSL_FUNC_cipher_settable_ctx_params()\fR will return the parameters associated
309 with the provider side context \fIcctx\fR in its current state if it is
310 not NULL. Otherwise, they return the parameters associated with the
311 provider side algorithm \fIprovctx\fR.
312 .PP
313 Parameters currently recognised by built-in ciphers are listed in
314 "PARAMETERS" in \fBEVP_EncryptInit\fR\|(3).
315 Not all parameters are relevant to, or are understood by all ciphers.
316 .SH "RETURN VALUES"
317 .IX Header "RETURN VALUES"
318 \&\fBOSSL_FUNC_cipher_newctx()\fR and \fBOSSL_FUNC_cipher_dupctx()\fR should return the newly created
319 provider side cipher context, or NULL on failure.
320 .PP
321 \&\fBOSSL_FUNC_cipher_encrypt_init()\fR, \fBOSSL_FUNC_cipher_decrypt_init()\fR, \fBOSSL_FUNC_cipher_update()\fR,
322 \&\fBOSSL_FUNC_cipher_final()\fR, \fBOSSL_FUNC_cipher_cipher()\fR,
323 \&\fBOSSL_FUNC_cipher_encrypt_skey_init()\fR, \fBOSSL_FUNC_cipher_decrypt_skey_init()\fR,
324 \&\fBOSSL_FUNC_cipher_pipeline_encrypt_init()\fR, \fBOSSL_FUNC_cipher_pipeline_decrypt_init()\fR,
325 \&\fBOSSL_FUNC_cipher_pipeline_update()\fR, \fBOSSL_FUNC_cipher_pipeline_final()\fR,
326 \&\fBOSSL_FUNC_cipher_get_params()\fR, \fBOSSL_FUNC_cipher_get_ctx_params()\fR and
327 \&\fBOSSL_FUNC_cipher_set_ctx_params()\fR should return 1 for
328 success or 0 on error.
329 .PP
330 \&\fBOSSL_FUNC_cipher_gettable_params()\fR, \fBOSSL_FUNC_cipher_gettable_ctx_params()\fR and
331 \&\fBOSSL_FUNC_cipher_settable_ctx_params()\fR should return a constant \fBOSSL_PARAM\fR\|(3)
332 array, or NULL if none is offered.
333 .SH "SEE ALSO"
334 .IX Header "SEE ALSO"
335 \&\fBprovider\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7),
336 \&\fBOSSL_PROVIDER\-legacy\fR\|(7),
337 \&\fBEVP_CIPHER\-AES\fR\|(7), \fBEVP_CIPHER\-ARIA\fR\|(7), \fBEVP_CIPHER\-BLOWFISH\fR\|(7),
338 \&\fBEVP_CIPHER\-CAMELLIA\fR\|(7), \fBEVP_CIPHER\-CAST\fR\|(7), \fBEVP_CIPHER\-CHACHA\fR\|(7),
339 \&\fBEVP_CIPHER\-DES\fR\|(7), \fBEVP_CIPHER\-IDEA\fR\|(7), \fBEVP_CIPHER\-RC2\fR\|(7),
340 \&\fBEVP_CIPHER\-RC4\fR\|(7), \fBEVP_CIPHER\-RC5\fR\|(7), \fBEVP_CIPHER\-SEED\fR\|(7),
341 \&\fBEVP_CIPHER\-SM4\fR\|(7), \fBEVP_CIPHER\-NULL\fR\|(7),
342 \&\fBlife_cycle\-cipher\fR\|(7), \fBEVP_EncryptInit\fR\|(3)
343 .SH HISTORY
344 .IX Header "HISTORY"
345 The provider CIPHER interface was introduced in OpenSSL 3.0.
346 .PP
347 The \fBOSSL_FUNC_cipher_encrypt_skey_init()\fR and
348 \&\fBOSSL_FUNC_cipher_decrypt_skey_init()\fR were introduced in OpenSSL 3.5.
349 .SH COPYRIGHT
350 .IX Header "COPYRIGHT"
351 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
352 .PP
353 Licensed under the Apache License 2.0 (the "License"). You may not use
354 this file except in compliance with the License. You can obtain a copy
355 in the file LICENSE in the source distribution or at
356 <https://www.openssl.org/source/license.html>.