Debian Codegraph @

upstream/debian-unstable/man7/provider-digest.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-DIGEST 7SSL"
58 .TH PROVIDER-DIGEST 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\-digest \- The digest 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 \& * Digests support the following function signatures in OSSL_DISPATCH arrays.
73 \& * (The function signatures are not actual functions).
74 \& */
75 \&
76 \& /* Context management */
77 \& void *OSSL_FUNC_digest_newctx(void *provctx);
78 \& void OSSL_FUNC_digest_freectx(void *dctx);
79 \& void *OSSL_FUNC_digest_dupctx(void *dctx);
80 \& void OSSL_FUNC_digest_copyctx(void *voutctx, void *vinctx);
81 \&
82 \& /* Digest generation */
83 \& int OSSL_FUNC_digest_init(void *dctx, const OSSL_PARAM params[]);
84 \& int OSSL_FUNC_digest_update(void *dctx, const unsigned char *in, size_t inl);
85 \& int OSSL_FUNC_digest_final(void *dctx, unsigned char *out, size_t *outl,
86 \& size_t outsz);
87 \& int OSSL_FUNC_digest_digest(void *provctx, const unsigned char *in, size_t inl,
88 \& unsigned char *out, size_t *outl, size_t outsz);
89 \&
90 \& /* Digest parameter descriptors */
91 \& const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx);
92 \&
93 \& /* Digest operation parameter descriptors */
94 \& const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *dctx,
95 \& void *provctx);
96 \& const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *dctx,
97 \& void *provctx);
98 \&
99 \& /* Digest parameters */
100 \& int OSSL_FUNC_digest_get_params(OSSL_PARAM params[]);
101 \&
102 \& /* Digest operation parameters */
103 \& int OSSL_FUNC_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]);
104 \& int OSSL_FUNC_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]);
105 .Ve
106 .SH DESCRIPTION
107 .IX Header "DESCRIPTION"
108 This documentation is primarily aimed at provider authors. See \fBprovider\fR\|(7)
109 for further information.
110 .PP
111 The DIGEST operation enables providers to implement digest algorithms and make
112 them available to applications via the API functions \fBEVP_DigestInit_ex\fR\|(3),
113 \&\fBEVP_DigestUpdate\fR\|(3) and \fBEVP_DigestFinal\fR\|(3) (and other related functions).
114 .PP
115 All "functions" mentioned here are passed as function pointers between
116 \&\fIlibcrypto\fR and the provider in \fBOSSL_DISPATCH\fR\|(3) arrays via
117 \&\fBOSSL_ALGORITHM\fR\|(3) arrays that are returned by the provider's
118 \&\fBprovider_query_operation()\fR function
119 (see "Provider Functions" in \fBprovider\-base\fR\|(7)).
120 .PP
121 All these "functions" have a corresponding function type definition
122 named \fBOSSL_FUNC_{name}_fn\fR, and a helper function to retrieve the
123 function pointer from an \fBOSSL_DISPATCH\fR\|(3) element named
124 \&\fBOSSL_FUNC_{name}\fR.
125 For example, the "function" \fBOSSL_FUNC_digest_newctx()\fR has these:
126 .PP
127 .Vb 3
128 \& typedef void *(OSSL_FUNC_digest_newctx_fn)(void *provctx);
129 \& static ossl_inline OSSL_FUNC_digest_newctx_fn
130 \& OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf);
131 .Ve
132 .PP
133 \&\fBOSSL_DISPATCH\fR\|(3) arrays are indexed by numbers that are provided as
134 macros in \fBopenssl\-core_dispatch.h\fR\|(7), as follows:
135 .PP
136 .Vb 4
137 \& OSSL_FUNC_digest_newctx OSSL_FUNC_DIGEST_NEWCTX
138 \& OSSL_FUNC_digest_freectx OSSL_FUNC_DIGEST_FREECTX
139 \& OSSL_FUNC_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX
140 \& OSSL_FUNC_digest_copyctx OSSL_FUNC_DIGEST_COPYCTX
141 \&
142 \& OSSL_FUNC_digest_init OSSL_FUNC_DIGEST_INIT
143 \& OSSL_FUNC_digest_update OSSL_FUNC_DIGEST_UPDATE
144 \& OSSL_FUNC_digest_final OSSL_FUNC_DIGEST_FINAL
145 \& OSSL_FUNC_digest_digest OSSL_FUNC_DIGEST_DIGEST
146 \&
147 \& OSSL_FUNC_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS
148 \& OSSL_FUNC_digest_get_ctx_params OSSL_FUNC_DIGEST_GET_CTX_PARAMS
149 \& OSSL_FUNC_digest_set_ctx_params OSSL_FUNC_DIGEST_SET_CTX_PARAMS
150 \&
151 \& OSSL_FUNC_digest_gettable_params OSSL_FUNC_DIGEST_GETTABLE_PARAMS
152 \& OSSL_FUNC_digest_gettable_ctx_params OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS
153 \& OSSL_FUNC_digest_settable_ctx_params OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS
154 .Ve
155 .PP
156 A digest algorithm implementation may not implement all of these functions.
157 In order to be usable all or none of OSSL_FUNC_digest_newctx, OSSL_FUNC_digest_freectx,
158 OSSL_FUNC_digest_init, OSSL_FUNC_digest_update, OSSL_FUNC_digest_final
159 and OSSL_FUNC_digest_get_params should be implemented.
160 All other functions are optional.
161 .SS "Context Management Functions"
162 .IX Subsection "Context Management Functions"
163 \&\fBOSSL_FUNC_digest_newctx()\fR should create and return a pointer to a provider side
164 structure for holding context information during a digest operation.
165 A pointer to this context will be passed back in a number of the other digest
166 operation function calls.
167 The parameter \fIprovctx\fR is the provider context generated during provider
168 initialisation (see \fBprovider\fR\|(7)).
169 .PP
170 \&\fBOSSL_FUNC_digest_freectx()\fR is passed a pointer to the provider side digest context in
171 the \fIdctx\fR parameter.
172 This function should free any resources associated with that context.
173 .PP
174 \&\fBOSSL_FUNC_digest_dupctx()\fR should duplicate the provider side digest context in the
175 \&\fIdctx\fR parameter and return the duplicate copy.
176 .PP
177 \&\fBOSSL_FUNC_digest_copyctx()\fR should copy the provider side digest context in the
178 \&\fIvinctx\fR parameter to the \fIvoutctx\fR parameter which is the another provider side
179 context.
180 The OSSL_FUNC_digest_copyctx function is used in the EVP_MD_CTX_copy_ex function to
181 speed up HMAC operations in the PBKDF2.
182 This function is optional, and dupctx will be used if there is no EVP_MD_CTX_copy_ex
183 function.
184 .SS "Digest Generation Functions"
185 .IX Subsection "Digest Generation Functions"
186 \&\fBOSSL_FUNC_digest_init()\fR initialises a digest operation given a newly created
187 provider side digest context in the \fIdctx\fR parameter.
188 The \fIparams\fR, if not NULL, should be set on the context in a manner similar to
189 using \fBOSSL_FUNC_digest_set_ctx_params()\fR.
190 .PP
191 \&\fBOSSL_FUNC_digest_update()\fR is called to supply data to be digested as part of a
192 previously initialised digest operation.
193 The \fIdctx\fR parameter contains a pointer to a previously initialised provider
194 side context.
195 \&\fBOSSL_FUNC_digest_update()\fR should digest \fIinl\fR bytes of data at the location pointed to
196 by \fIin\fR.
197 \&\fBOSSL_FUNC_digest_update()\fR may be called multiple times for a single digest operation.
198 .PP
199 \&\fBOSSL_FUNC_digest_final()\fR generates a digest started through previous \fBOSSL_FUNC_digest_init()\fR
200 and \fBOSSL_FUNC_digest_update()\fR calls.
201 The \fIdctx\fR parameter contains a pointer to the provider side context.
202 The digest should be written to \fI*out\fR and the length of the digest to
203 \&\fI*outl\fR.
204 The digest should not exceed \fIoutsz\fR bytes.
205 .PP
206 \&\fBOSSL_FUNC_digest_digest()\fR is a "oneshot" digest function.
207 No provider side digest context is used.
208 Instead the provider context that was created during provider initialisation is
209 passed in the \fIprovctx\fR parameter (see \fBprovider\fR\|(7)).
210 \&\fIinl\fR bytes at \fIin\fR should be digested and the result should be stored at
211 \&\fIout\fR. The length of the digest should be stored in \fI*outl\fR which should not
212 exceed \fIoutsz\fR bytes.
213 .SS "Digest Parameters"
214 .IX Subsection "Digest Parameters"
215 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure used by
216 these functions.
217 .PP
218 \&\fBOSSL_FUNC_digest_get_params()\fR gets details of the algorithm implementation
219 and stores them in \fIparams\fR.
220 .PP
221 \&\fBOSSL_FUNC_digest_set_ctx_params()\fR sets digest operation parameters for the
222 provider side digest context \fIdctx\fR to \fIparams\fR.
223 Any parameter settings are additional to any that were previously set.
224 Passing NULL for \fIparams\fR should return true.
225 .PP
226 \&\fBOSSL_FUNC_digest_get_ctx_params()\fR gets digest operation details details from
227 the given provider side digest context \fIdctx\fR and stores them in \fIparams\fR.
228 Passing NULL for \fIparams\fR should return true.
229 .PP
230 \&\fBOSSL_FUNC_digest_gettable_params()\fR returns a constant \fBOSSL_PARAM\fR\|(3) array
231 containing descriptors of the parameters that \fBOSSL_FUNC_digest_get_params()\fR
232 can handle.
233 .PP
234 \&\fBOSSL_FUNC_digest_gettable_ctx_params()\fR and
235 \&\fBOSSL_FUNC_digest_settable_ctx_params()\fR both return constant
236 \&\fBOSSL_PARAM\fR\|(3) arrays as descriptors of the parameters that
237 \&\fBOSSL_FUNC_digest_get_ctx_params()\fR and \fBOSSL_FUNC_digest_set_ctx_params()\fR
238 can handle, respectively. The array is based on the current state of
239 the provider side context if \fIdctx\fR is not NULL and on the provider
240 side algorithm \fIprovctx\fR otherwise.
241 .PP
242 Parameters currently recognised by built-in digests with this function
243 are as follows. Not all parameters are relevant to, or are understood
244 by all digests:
245 .IP """blocksize"" (\fBOSSL_DIGEST_PARAM_BLOCK_SIZE\fR) <unsigned integer>" 4
246 .IX Item """blocksize"" (OSSL_DIGEST_PARAM_BLOCK_SIZE) <unsigned integer>"
247 The digest block size.
248 The length of the "blocksize" parameter should not exceed that of a \fBsize_t\fR.
249 .IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) <unsigned integer>" 4
250 .IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>"
251 The digest output size.
252 The length of the "size" parameter should not exceed that of a \fBsize_t\fR.
253 .IP """flags"" (\fBOSSL_DIGEST_PARAM_FLAGS\fR) <unsigned integer>" 4
254 .IX Item """flags"" (OSSL_DIGEST_PARAM_FLAGS) <unsigned integer>"
255 Diverse flags that describe exceptional behaviour for the digest:
256 .RS 4
257 .IP \fBEVP_MD_FLAG_ONESHOT\fR 4
258 .IX Item "EVP_MD_FLAG_ONESHOT"
259 This digest method can only handle one block of input.
260 .IP \fBEVP_MD_FLAG_XOF\fR 4
261 .IX Item "EVP_MD_FLAG_XOF"
262 This digest method is an extensible-output function (XOF).
263 .IP \fBEVP_MD_FLAG_DIGALGID_NULL\fR 4
264 .IX Item "EVP_MD_FLAG_DIGALGID_NULL"
265 When setting up a DigestAlgorithmIdentifier, this flag will have the
266 parameter set to NULL by default. Use this for PKCS#1. \fINote: if
267 combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.\fR
268 .IP \fBEVP_MD_FLAG_DIGALGID_ABSENT\fR 4
269 .IX Item "EVP_MD_FLAG_DIGALGID_ABSENT"
270 When setting up a DigestAlgorithmIdentifier, this flag will have the
271 parameter be left absent by default. \fINote: if combined with
272 EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.\fR
273 .IP \fBEVP_MD_FLAG_DIGALGID_CUSTOM\fR 4
274 .IX Item "EVP_MD_FLAG_DIGALGID_CUSTOM"
275 Custom DigestAlgorithmIdentifier handling via ctrl, with
276 \&\fBEVP_MD_FLAG_DIGALGID_ABSENT\fR as default. \fINote: if combined with
277 EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.\fR
278 Currently unused.
279 .RE
280 .RS 4
281 .Sp
282 The length of the "flags" parameter should equal that of an
283 \&\fBunsigned long int\fR.
284 .RE
285 .SS "Digest Context Parameters"
286 .IX Subsection "Digest Context Parameters"
287 \&\fBOSSL_FUNC_digest_set_ctx_params()\fR sets digest parameters associated with the
288 given provider side digest context \fIdctx\fR to \fIparams\fR.
289 Any parameter settings are additional to any that were previously set.
290 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure.
291 .PP
292 \&\fBOSSL_FUNC_digest_get_ctx_params()\fR gets details of currently set parameters
293 values associated with the give provider side digest context \fIdctx\fR
294 and stores them in \fIparams\fR.
295 See \fBOSSL_PARAM\fR\|(3) for further details on the parameters structure.
296 .SH "RETURN VALUES"
297 .IX Header "RETURN VALUES"
298 \&\fBOSSL_FUNC_digest_newctx()\fR and \fBOSSL_FUNC_digest_dupctx()\fR should return the newly created
299 provider side digest context, or NULL on failure.
300 .PP
301 \&\fBOSSL_FUNC_digest_init()\fR, \fBOSSL_FUNC_digest_update()\fR, \fBOSSL_FUNC_digest_final()\fR, \fBOSSL_FUNC_digest_digest()\fR,
302 \&\fBOSSL_FUNC_digest_set_params()\fR and \fBOSSL_FUNC_digest_get_params()\fR should return 1 for success or
303 0 on error.
304 .PP
305 \&\fBOSSL_FUNC_digest_size()\fR should return the digest size.
306 .PP
307 \&\fBOSSL_FUNC_digest_block_size()\fR should return the block size of the underlying digest
308 algorithm.
309 .SH BUGS
310 .IX Header "BUGS"
311 The \fBEVP_Q_digest()\fR, \fBEVP_Digest()\fR and \fBEVP_DigestFinal_ex()\fR API calls do not
312 expect the digest size to be larger than EVP_MAX_MD_SIZE. Any algorithm which
313 produces larger digests is unusable with those API calls.
314 .SH "SEE ALSO"
315 .IX Header "SEE ALSO"
316 \&\fBprovider\fR\|(7), \fBOSSL_PROVIDER\-FIPS\fR\|(7), \fBOSSL_PROVIDER\-default\fR\|(7),
317 \&\fBOSSL_PROVIDER\-legacy\fR\|(7),
318 \&\fBEVP_MD\-common\fR\|(7), \fBEVP_MD\-BLAKE2\fR\|(7), \fBEVP_MD\-MD2\fR\|(7),
319 \&\fBEVP_MD\-MD4\fR\|(7), \fBEVP_MD\-MD5\fR\|(7), \fBEVP_MD\-MD5\-SHA1\fR\|(7),
320 \&\fBEVP_MD\-MDC2\fR\|(7), \fBEVP_MD\-RIPEMD160\fR\|(7), \fBEVP_MD\-SHA1\fR\|(7),
321 \&\fBEVP_MD\-SHA2\fR\|(7), \fBEVP_MD\-SHA3\fR\|(7), \fBEVP_MD\-KECCAK\fR\|(7)
322 \&\fBEVP_MD\-SHAKE\fR\|(7), \fBEVP_MD\-SM3\fR\|(7), \fBEVP_MD\-WHIRLPOOL\fR\|(7),
323 \&\fBEVP_MD\-NULL\fR\|(7),
324 \&\fBlife_cycle\-digest\fR\|(7), \fBEVP_DigestInit\fR\|(3)
325 .SH HISTORY
326 .IX Header "HISTORY"
327 The provider DIGEST interface was introduced in OpenSSL 3.0.
328 \&\fBOSSL_FUNC_digest_copyctx()\fR was added in 3.5 version.
329 .SH COPYRIGHT
330 .IX Header "COPYRIGHT"
331 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
332 .PP
333 Licensed under the Apache License 2.0 (the "License"). You may not use
334 this file except in compliance with the License. You can obtain a copy
335 in the file LICENSE in the source distribution or at
336 <https://www.openssl.org/source/license.html>.