5 provider-digest - The digest library E<lt>-E<gt> provider functions
9 =for comment multiple includes
11 #include <openssl/core_numbers.h>
12 #include <openssl/core_names.h>
15 * None of these are actual functions, but are displayed like this for
16 * the function signatures for functions that are offered as function
17 * pointers in OSSL_DISPATCH arrays.
20 /* Context management */
21 void *OP_digest_newctx(void *provctx);
22 void OP_digest_freectx(void *dctx);
23 void *OP_digest_dupctx(void *dctx);
25 /* Digest generation */
26 int OP_digest_init(void *dctx);
27 int OP_digest_update(void *dctx, const unsigned char *in, size_t inl);
28 int OP_digest_final(void *dctx, unsigned char *out, size_t *outl,
30 int OP_digest_digest(void *provctx, const unsigned char *in, size_t inl,
31 unsigned char *out, size_t *outl, size_t outsz);
33 /* Digest parameters */
34 int OP_digest_get_params(OSSL_PARAM params[]);
36 /* Digest context parameters */
37 int OP_digest_ctx_set_params(void *dctx, const OSSL_PARAM params[]);
38 int OP_digest_ctx_get_params(void *dctx, OSSL_PARAM params[]);
42 This documentation is primarily aimed at provider authors. See L<provider(7)>
43 for further information.
45 The DIGEST operation enables providers to implement digest algorithms and make
46 them available to applications via the API functions L<EVP_DigestInit_ex(3)>,
47 L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal(3)> (and other related functions).
49 All "functions" mentioned here are passed as function pointers between
50 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
51 B<OSSL_ALGORITHM> arrays that are returned by the provider's
52 provider_query_operation() function
53 (see L<provider-base(7)/Provider Functions>).
55 All these "functions" have a corresponding function type definition
56 named B<OSSL_{name}_fn>, and a helper function to retrieve the
57 function pointer from an B<OSSL_DISPATCH> element named
59 For example, the "function" OP_digest_newctx() has these:
61 typedef void *(OSSL_OP_digest_newctx_fn)(void *provctx);
62 static ossl_inline OSSL_OP_digest_newctx_fn
63 OSSL_get_OP_digest_newctx(const OSSL_DISPATCH *opf);
65 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
66 macros in L<openssl-core_numbers.h(7)>, as follows:
68 OP_digest_newctx OSSL_FUNC_DIGEST_NEWCTX
69 OP_digest_freectx OSSL_FUNC_DIGEST_FREECTX
70 OP_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX
72 OP_digest_init OSSL_FUNC_DIGEST_INIT
73 OP_digest_update OSSL_FUNC_DIGEST_UPDATE
74 OP_digest_final OSSL_FUNC_DIGEST_FINAL
75 OP_digest_digest OSSL_FUNC_DIGEST_DIGEST
77 OP_digest_size OSSL_FUNC_DIGEST_SIZE
78 OP_digest_block_size OSSL_FUNC_DIGEST_BLOCK_SIZE
79 OP_digest_set_params OSSL_FUNC_DIGEST_SET_PARAMS
80 OP_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS
82 A digest algorithm implementation may not implement all of these functions.
83 In order to be useable all or none of OP_digest_newctx, OP_digest_freectx,
84 OP_digest_init, OP_digest_update and OP_digest_final should be implemented.
85 All other functions are optional.
87 =head2 Context Management Functions
89 OP_digest_newctx() should create and return a pointer to a provider side
90 structure for holding context information during a digest operation.
91 A pointer to this context will be passed back in a number of the other digest
92 operation function calls.
93 The paramater B<provctx> is the provider context generated during provider
94 initialisation (see L<provider(3)>).
96 OP_digest_freectx() is passed a pointer to the provider side digest context in
97 the B<dctx> parameter.
98 This function should free any resources associated with that context.
100 OP_digest_dupctx() should duplicate the provider side digest context in the
101 B<dctx> parameter and return the duplicate copy.
103 =head2 Digest Generation Functions
105 OP_digest_init() initialises a digest operation given a newly created
106 provider side digest context in the B<dctx> paramter.
108 OP_digest_update() is called to supply data to be digested as part of a
109 previously initialised digest operation.
110 The B<dctx> parameter contains a pointer to a previously initialised provider
112 OP_digest_update() should digest B<inl> bytes of data at the location pointed to
114 OP_digest_update() may be called multiple times for a single digest operation.
116 OP_digest_final() generates a digest started through previous OP_digest_init()
117 and OP_digest_update() calls.
118 The B<dctx> parameter contains a pointer to the provider side context.
119 The digest should be written to B<*out> and the length of the digest to
121 The digest should not exceed B<outsz> bytes.
123 OP_digest_digest() is a "oneshot" digest function.
124 No provider side digest context is used.
125 Instead the provider context that was created during provider initialisation is
126 passed in the B<provctx> parameter (see L<provider(3)>).
127 B<inl> bytes at B<in> should be digested and the result should be stored at
128 B<out>. The length of the digest should be stored in B<*outl> which should not
129 exceed B<outsz> bytes.
131 =head2 Digest Parameters
133 OP_digest_get_params() gets details of the algorithm implementation
134 and stores them in B<params>.
135 See L<OSSL_PARAM(3)> for further details on the parameters structure.
137 Parameters currently recognised by built-in digests with this function
138 are as follows. Not all parametes are relevant to, or are understood
143 =item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> (int)
145 The digest block size.
147 =item B<OSSL_DIGEST_PARAM_SIZE> (int)
149 The digest output size.
151 =item B<OSSL_DIGEST_PARAM_FLAGS> (unsigned long)
153 Diverse flags that describe exceptional behaviour for the digest:
157 =item B<EVP_MD_FLAG_ONESHOT>
159 This digest method can only handle one block of input.
161 =item B<EVP_MD_FLAG_XOF>
163 This digest method is an extensible-output function (XOF) and supports
164 setting the B<OSSL_DIGEST_PARAM_XOFLEN> parameter.
166 =item B<EVP_MD_FLAG_DIGALGID_NULL>
168 When setting up a DigestAlgorithmIdentifier, this flag will have the
169 parameter set to NULL by default. Use this for PKCS#1. I<Note: if
170 combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
172 =item B<EVP_MD_FLAG_DIGALGID_ABSENT>
174 When setting up a DigestAlgorithmIdentifier, this flag will have the
175 parameter be left absent by default. I<Note: if combined with
176 EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
178 =item B<EVP_MD_FLAG_DIGALGID_CUSTOM>
180 Custom DigestAlgorithmIdentifier handling via ctrl, with
181 B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
182 EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
189 =head2 Digest Context Parameters
191 OP_digest_ctx_set_params() sets digest parameters associated with the
192 given provider side digest context B<dctx> to B<params>.
193 Any parameter settings are additional to any that were previously set.
194 See L<OSSL_PARAM(3)> for further details on the parameters structure.
196 OP_digest_ctx_get_params() gets details of currently set parameters
197 values associated with the give provider side digest context B<dctx>
198 and stores them in B<params>.
199 See L<OSSL_PARAM(3)> for further details on the parameters structure.
201 Parameters currently recognised by built-in digests are as follows. Not all
202 parametes are relevant to, or are understood by all digests:
206 =item B<OSSL_DIGEST_PARAM_XOFLEN> (size_t)
208 Sets the digest length for extendable output functions.
210 =item B<OSSL_DIGEST_PARAM_SSL3_MS> (octet string)
212 This parameter is set by libssl in order to calculate a signature hash for an
213 SSLv3 CertificateVerify message as per RFC6101.
214 It is only set after all handshake messages have already been digested via
215 OP_digest_update() calls.
216 The parameter provides the master secret value to be added to the digest.
217 The digest implementation should calculate the complete digest as per RFC6101
219 The next call after setting this parameter will be OP_digest_final().
220 This is only relevant for implementations of SHA1 or MD5_SHA1.
222 =item B<OSSL_DIGEST_PARAM_PAD_TYPE> (int)
224 Sets the pad type to be used.
225 The only built-in digest that uses this is MDC2.
226 Normally the final MDC2 block is padded with 0s.
227 If the pad type is set to 2 then the final block is padded with 0x80 followed by
230 =item B<OSSL_DIGEST_PARAM_MICALG> (utf8 string)
232 Gets the digest Message Integrity Check algorithm string.
233 This is used when creating S/MIME multipart/signed messages, as specified in
240 OP_digest_newctx() and OP_digest_dupctx() should return the newly created
241 provider side digest context, or NULL on failure.
243 OP_digest_init(), OP_digest_update(), OP_digest_final(), OP_digest_digest(),
244 OP_digest_set_params() and OP_digest_get_params() should return 1 for success or
247 OP_digest_size() should return the digest size.
249 OP_digest_block_size() should return the block size of the underlying digest
258 The provider DIGEST interface was introduced in OpenSSL 3.0.
262 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
264 Licensed under the Apache License 2.0 (the "License"). You may not use
265 this file except in compliance with the License. You can obtain a copy
266 in the file LICENSE in the source distribution or at
267 L<https://www.openssl.org/source/license.html>.