]>
Commit | Line | Data |
---|---|---|
8ccf2ffb MC |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | provider-digest - The digest library E<lt>-E<gt> provider functions | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | =for comment multiple includes | |
10 | ||
11 | #include <openssl/core_numbers.h> | |
12 | #include <openssl/core_names.h> | |
13 | ||
14 | /* | |
c85d5e02 SL |
15 | * Digests support the following function signatures in OSSL_DISPATCH arrays. |
16 | * (The function signatures are not actual functions). | |
8ccf2ffb MC |
17 | */ |
18 | ||
19 | /* Context management */ | |
20 | void *OP_digest_newctx(void *provctx); | |
21 | void OP_digest_freectx(void *dctx); | |
22 | void *OP_digest_dupctx(void *dctx); | |
23 | ||
24 | /* Digest generation */ | |
25 | int OP_digest_init(void *dctx); | |
26 | int OP_digest_update(void *dctx, const unsigned char *in, size_t inl); | |
27 | int OP_digest_final(void *dctx, unsigned char *out, size_t *outl, | |
28 | size_t outsz); | |
29 | int OP_digest_digest(void *provctx, const unsigned char *in, size_t inl, | |
30 | unsigned char *out, size_t *outl, size_t outsz); | |
31 | ||
ae3ff60e RL |
32 | /* Digest parameter descriptors */ |
33 | const OSSL_PARAM *OP_cipher_gettable_params(void); | |
34 | ||
35 | /* Digest operation parameter descriptors */ | |
36 | const OSSL_PARAM *OP_cipher_gettable_ctx_params(void); | |
37 | const OSSL_PARAM *OP_cipher_settable_ctx_params(void); | |
38 | ||
8ccf2ffb | 39 | /* Digest parameters */ |
2893111f RL |
40 | int OP_digest_get_params(OSSL_PARAM params[]); |
41 | ||
ae3ff60e | 42 | /* Digest operation parameters */ |
92d9d0ae RL |
43 | int OP_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]); |
44 | int OP_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]); | |
8ccf2ffb MC |
45 | |
46 | =head1 DESCRIPTION | |
47 | ||
48 | This documentation is primarily aimed at provider authors. See L<provider(7)> | |
49 | for further information. | |
50 | ||
51 | The DIGEST operation enables providers to implement digest algorithms and make | |
52 | them available to applications via the API functions L<EVP_DigestInit_ex(3)>, | |
53 | L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal(3)> (and other related functions). | |
54 | ||
55 | All "functions" mentioned here are passed as function pointers between | |
56 | F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via | |
57 | B<OSSL_ALGORITHM> arrays that are returned by the provider's | |
58 | provider_query_operation() function | |
59 | (see L<provider-base(7)/Provider Functions>). | |
60 | ||
61 | All these "functions" have a corresponding function type definition | |
62 | named B<OSSL_{name}_fn>, and a helper function to retrieve the | |
63 | function pointer from an B<OSSL_DISPATCH> element named | |
64 | B<OSSL_get_{name}>. | |
65 | For example, the "function" OP_digest_newctx() has these: | |
66 | ||
67 | typedef void *(OSSL_OP_digest_newctx_fn)(void *provctx); | |
68 | static ossl_inline OSSL_OP_digest_newctx_fn | |
69 | OSSL_get_OP_digest_newctx(const OSSL_DISPATCH *opf); | |
70 | ||
71 | B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as | |
72 | macros in L<openssl-core_numbers.h(7)>, as follows: | |
73 | ||
ae3ff60e RL |
74 | OP_digest_newctx OSSL_FUNC_DIGEST_NEWCTX |
75 | OP_digest_freectx OSSL_FUNC_DIGEST_FREECTX | |
76 | OP_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX | |
8ccf2ffb | 77 | |
ae3ff60e RL |
78 | OP_digest_init OSSL_FUNC_DIGEST_INIT |
79 | OP_digest_update OSSL_FUNC_DIGEST_UPDATE | |
80 | OP_digest_final OSSL_FUNC_DIGEST_FINAL | |
81 | OP_digest_digest OSSL_FUNC_DIGEST_DIGEST | |
8ccf2ffb | 82 | |
ae3ff60e | 83 | OP_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS |
92d9d0ae RL |
84 | OP_digest_get_ctx_params OSSL_FUNC_DIGEST_GET_CTX_PARAMS |
85 | OP_digest_set_ctx_params OSSL_FUNC_DIGEST_SET_CTX_PARAMS | |
ae3ff60e RL |
86 | |
87 | OP_digest_gettable_params OSSL_FUNC_DIGEST_GETTABLE_PARAMS | |
88 | OP_digest_gettable_ctx_params OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS | |
89 | OP_digest_settable_ctx_params OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS | |
8ccf2ffb MC |
90 | |
91 | A digest algorithm implementation may not implement all of these functions. | |
c85d5e02 | 92 | In order to be usable all or none of OP_digest_newctx, OP_digest_freectx, |
8ccf2ffb MC |
93 | OP_digest_init, OP_digest_update and OP_digest_final should be implemented. |
94 | All other functions are optional. | |
95 | ||
96 | =head2 Context Management Functions | |
97 | ||
98 | OP_digest_newctx() should create and return a pointer to a provider side | |
99 | structure for holding context information during a digest operation. | |
100 | A pointer to this context will be passed back in a number of the other digest | |
101 | operation function calls. | |
c85d5e02 | 102 | The parameter B<provctx> is the provider context generated during provider |
8ccf2ffb MC |
103 | initialisation (see L<provider(3)>). |
104 | ||
105 | OP_digest_freectx() is passed a pointer to the provider side digest context in | |
106 | the B<dctx> parameter. | |
107 | This function should free any resources associated with that context. | |
108 | ||
109 | OP_digest_dupctx() should duplicate the provider side digest context in the | |
110 | B<dctx> parameter and return the duplicate copy. | |
111 | ||
112 | =head2 Digest Generation Functions | |
113 | ||
114 | OP_digest_init() initialises a digest operation given a newly created | |
c85d5e02 | 115 | provider side digest context in the B<dctx> parameter. |
8ccf2ffb MC |
116 | |
117 | OP_digest_update() is called to supply data to be digested as part of a | |
118 | previously initialised digest operation. | |
119 | The B<dctx> parameter contains a pointer to a previously initialised provider | |
120 | side context. | |
121 | OP_digest_update() should digest B<inl> bytes of data at the location pointed to | |
122 | by B<in>. | |
123 | OP_digest_update() may be called multiple times for a single digest operation. | |
124 | ||
125 | OP_digest_final() generates a digest started through previous OP_digest_init() | |
126 | and OP_digest_update() calls. | |
127 | The B<dctx> parameter contains a pointer to the provider side context. | |
128 | The digest should be written to B<*out> and the length of the digest to | |
129 | B<*outl>. | |
130 | The digest should not exceed B<outsz> bytes. | |
131 | ||
132 | OP_digest_digest() is a "oneshot" digest function. | |
133 | No provider side digest context is used. | |
134 | Instead the provider context that was created during provider initialisation is | |
135 | passed in the B<provctx> parameter (see L<provider(3)>). | |
136 | B<inl> bytes at B<in> should be digested and the result should be stored at | |
137 | B<out>. The length of the digest should be stored in B<*outl> which should not | |
138 | exceed B<outsz> bytes. | |
139 | ||
140 | =head2 Digest Parameters | |
141 | ||
ae3ff60e RL |
142 | See L<OSSL_PARAM(3)> for further details on the parameters structure used by |
143 | these functions. | |
144 | ||
2893111f RL |
145 | OP_digest_get_params() gets details of the algorithm implementation |
146 | and stores them in B<params>. | |
ae3ff60e | 147 | |
92d9d0ae | 148 | OP_digest_set_ctx_params() sets digest operation parameters for the |
ae3ff60e RL |
149 | provider side digest context B<dctx> to B<params>. |
150 | Any parameter settings are additional to any that were previously set. | |
151 | ||
92d9d0ae | 152 | OP_digest_get_ctx_params() gets digest operation details details from |
ae3ff60e RL |
153 | the given provider side digest context B<dctx> and stores them in B<params>. |
154 | ||
155 | OP_digest_gettable_params(), OP_digest_gettable_ctx_params(), and | |
156 | OP_digest_settable_ctx_params() all return constant B<OSSL_PARAM> arrays | |
157 | as descriptors of the parameters that OP_digest_get_params(), | |
92d9d0ae | 158 | OP_digest_get_ctx_params(), and OP_digest_set_ctx_params() can handle, |
ae3ff60e | 159 | respectively. |
2893111f RL |
160 | |
161 | Parameters currently recognised by built-in digests with this function | |
c85d5e02 | 162 | are as follows. Not all parameters are relevant to, or are understood |
2893111f RL |
163 | by all digests: |
164 | ||
165 | =over 4 | |
166 | ||
1c3ace68 | 167 | =item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> (size_t) |
2893111f RL |
168 | |
169 | The digest block size. | |
170 | ||
1c3ace68 | 171 | =item B<OSSL_DIGEST_PARAM_SIZE> (size_t) |
2893111f RL |
172 | |
173 | The digest output size. | |
174 | ||
175 | =item B<OSSL_DIGEST_PARAM_FLAGS> (unsigned long) | |
176 | ||
177 | Diverse flags that describe exceptional behaviour for the digest: | |
178 | ||
179 | =over 4 | |
180 | ||
181 | =item B<EVP_MD_FLAG_ONESHOT> | |
182 | ||
183 | This digest method can only handle one block of input. | |
184 | ||
185 | =item B<EVP_MD_FLAG_XOF> | |
186 | ||
187 | This digest method is an extensible-output function (XOF) and supports | |
188 | setting the B<OSSL_DIGEST_PARAM_XOFLEN> parameter. | |
189 | ||
190 | =item B<EVP_MD_FLAG_DIGALGID_NULL> | |
191 | ||
192 | When setting up a DigestAlgorithmIdentifier, this flag will have the | |
193 | parameter set to NULL by default. Use this for PKCS#1. I<Note: if | |
194 | combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.> | |
195 | ||
196 | =item B<EVP_MD_FLAG_DIGALGID_ABSENT> | |
197 | ||
198 | When setting up a DigestAlgorithmIdentifier, this flag will have the | |
199 | parameter be left absent by default. I<Note: if combined with | |
200 | EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> | |
201 | ||
202 | =item B<EVP_MD_FLAG_DIGALGID_CUSTOM> | |
203 | ||
204 | Custom DigestAlgorithmIdentifier handling via ctrl, with | |
205 | B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with | |
206 | EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> | |
207 | Currently unused. | |
208 | ||
209 | =back | |
210 | ||
211 | =back | |
8ccf2ffb | 212 | |
2893111f | 213 | =head2 Digest Context Parameters |
8ccf2ffb | 214 | |
92d9d0ae | 215 | OP_digest_set_ctx_params() sets digest parameters associated with the |
2893111f | 216 | given provider side digest context B<dctx> to B<params>. |
8ccf2ffb MC |
217 | Any parameter settings are additional to any that were previously set. |
218 | See L<OSSL_PARAM(3)> for further details on the parameters structure. | |
219 | ||
92d9d0ae | 220 | OP_digest_get_ctx_params() gets details of currently set parameters |
2893111f RL |
221 | values associated with the give provider side digest context B<dctx> |
222 | and stores them in B<params>. | |
8ccf2ffb MC |
223 | See L<OSSL_PARAM(3)> for further details on the parameters structure. |
224 | ||
225 | Parameters currently recognised by built-in digests are as follows. Not all | |
c85d5e02 | 226 | parameters are relevant to, or are understood by all digests: |
8ccf2ffb MC |
227 | |
228 | =over 4 | |
229 | ||
230 | =item B<OSSL_DIGEST_PARAM_XOFLEN> (size_t) | |
231 | ||
232 | Sets the digest length for extendable output functions. | |
233 | ||
234 | =item B<OSSL_DIGEST_PARAM_SSL3_MS> (octet string) | |
235 | ||
236 | This parameter is set by libssl in order to calculate a signature hash for an | |
237 | SSLv3 CertificateVerify message as per RFC6101. | |
238 | It is only set after all handshake messages have already been digested via | |
239 | OP_digest_update() calls. | |
240 | The parameter provides the master secret value to be added to the digest. | |
241 | The digest implementation should calculate the complete digest as per RFC6101 | |
242 | section 5.6.8. | |
243 | The next call after setting this parameter will be OP_digest_final(). | |
244 | This is only relevant for implementations of SHA1 or MD5_SHA1. | |
245 | ||
1c3ace68 | 246 | =item B<OSSL_DIGEST_PARAM_PAD_TYPE> (uint) |
8ccf2ffb MC |
247 | |
248 | Sets the pad type to be used. | |
249 | The only built-in digest that uses this is MDC2. | |
250 | Normally the final MDC2 block is padded with 0s. | |
251 | If the pad type is set to 2 then the final block is padded with 0x80 followed by | |
252 | 0s. | |
253 | ||
254 | =item B<OSSL_DIGEST_PARAM_MICALG> (utf8 string) | |
255 | ||
256 | Gets the digest Message Integrity Check algorithm string. | |
257 | This is used when creating S/MIME multipart/signed messages, as specified in | |
258 | RFC 5751. | |
259 | ||
260 | =back | |
261 | ||
262 | =head1 RETURN VALUES | |
263 | ||
264 | OP_digest_newctx() and OP_digest_dupctx() should return the newly created | |
265 | provider side digest context, or NULL on failure. | |
266 | ||
267 | OP_digest_init(), OP_digest_update(), OP_digest_final(), OP_digest_digest(), | |
268 | OP_digest_set_params() and OP_digest_get_params() should return 1 for success or | |
269 | 0 on error. | |
270 | ||
271 | OP_digest_size() should return the digest size. | |
272 | ||
273 | OP_digest_block_size() should return the block size of the underlying digest | |
274 | algorithm. | |
275 | ||
276 | =head1 SEE ALSO | |
277 | ||
278 | L<provider(7)> | |
279 | ||
280 | =head1 HISTORY | |
281 | ||
282 | The provider DIGEST interface was introduced in OpenSSL 3.0. | |
283 | ||
284 | =head1 COPYRIGHT | |
285 | ||
286 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
287 | ||
288 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
289 | this file except in compliance with the License. You can obtain a copy | |
290 | in the file LICENSE in the source distribution or at | |
291 | L<https://www.openssl.org/source/license.html>. | |
292 | ||
293 | =cut |