1=pod 2 3=head1 NAME 4 5provider-digest - The digest library E<lt>-E<gt> provider functions 6 7=head1 SYNOPSIS 8 9=for openssl multiple includes 10 11 #include <openssl/core_dispatch.h> 12 #include <openssl/core_names.h> 13 14 /* 15 * Digests support the following function signatures in OSSL_DISPATCH arrays. 16 * (The function signatures are not actual functions). 17 */ 18 19 /* Context management */ 20 void *OSSL_FUNC_digest_newctx(void *provctx); 21 void OSSL_FUNC_digest_freectx(void *dctx); 22 void *OSSL_FUNC_digest_dupctx(void *dctx); 23 void OSSL_FUNC_digest_copyctx(void *voutctx, void *vinctx); 24 25 /* Digest generation */ 26 int OSSL_FUNC_digest_init(void *dctx, const OSSL_PARAM params[]); 27 int OSSL_FUNC_digest_update(void *dctx, const unsigned char *in, size_t inl); 28 int OSSL_FUNC_digest_final(void *dctx, unsigned char *out, size_t *outl, 29 size_t outsz); 30 int OSSL_FUNC_digest_digest(void *provctx, const unsigned char *in, size_t inl, 31 unsigned char *out, size_t *outl, size_t outsz); 32 33 /* Digest parameter descriptors */ 34 const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx); 35 36 /* Digest operation parameter descriptors */ 37 const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *dctx, 38 void *provctx); 39 const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *dctx, 40 void *provctx); 41 42 /* Digest parameters */ 43 int OSSL_FUNC_digest_get_params(OSSL_PARAM params[]); 44 45 /* Digest operation parameters */ 46 int OSSL_FUNC_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]); 47 int OSSL_FUNC_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]); 48 49=head1 DESCRIPTION 50 51This documentation is primarily aimed at provider authors. See L<provider(7)> 52for further information. 53 54The DIGEST operation enables providers to implement digest algorithms and make 55them available to applications via the API functions L<EVP_DigestInit_ex(3)>, 56L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal(3)> (and other related functions). 57 58All "functions" mentioned here are passed as function pointers between 59F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via 60L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's 61provider_query_operation() function 62(see L<provider-base(7)/Provider Functions>). 63 64All these "functions" have a corresponding function type definition 65named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the 66function pointer from an L<OSSL_DISPATCH(3)> element named 67B<OSSL_FUNC_{name}>. 68For example, the "function" OSSL_FUNC_digest_newctx() has these: 69 70 typedef void *(OSSL_FUNC_digest_newctx_fn)(void *provctx); 71 static ossl_inline OSSL_FUNC_digest_newctx_fn 72 OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf); 73 74L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as 75macros in L<openssl-core_dispatch.h(7)>, as follows: 76 77 OSSL_FUNC_digest_newctx OSSL_FUNC_DIGEST_NEWCTX 78 OSSL_FUNC_digest_freectx OSSL_FUNC_DIGEST_FREECTX 79 OSSL_FUNC_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX 80 OSSL_FUNC_digest_copyctx OSSL_FUNC_DIGEST_COPYCTX 81 82 OSSL_FUNC_digest_init OSSL_FUNC_DIGEST_INIT 83 OSSL_FUNC_digest_update OSSL_FUNC_DIGEST_UPDATE 84 OSSL_FUNC_digest_final OSSL_FUNC_DIGEST_FINAL 85 OSSL_FUNC_digest_digest OSSL_FUNC_DIGEST_DIGEST 86 87 OSSL_FUNC_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS 88 OSSL_FUNC_digest_get_ctx_params OSSL_FUNC_DIGEST_GET_CTX_PARAMS 89 OSSL_FUNC_digest_set_ctx_params OSSL_FUNC_DIGEST_SET_CTX_PARAMS 90 91 OSSL_FUNC_digest_gettable_params OSSL_FUNC_DIGEST_GETTABLE_PARAMS 92 OSSL_FUNC_digest_gettable_ctx_params OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS 93 OSSL_FUNC_digest_settable_ctx_params OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS 94 95A digest algorithm implementation may not implement all of these functions. 96In order to be usable all or none of OSSL_FUNC_digest_newctx, OSSL_FUNC_digest_freectx, 97OSSL_FUNC_digest_init, OSSL_FUNC_digest_update, OSSL_FUNC_digest_final 98and OSSL_FUNC_digest_get_params should be implemented. 99All other functions are optional. 100 101=head2 Context Management Functions 102 103OSSL_FUNC_digest_newctx() should create and return a pointer to a provider side 104structure for holding context information during a digest operation. 105A pointer to this context will be passed back in a number of the other digest 106operation function calls. 107The parameter I<provctx> is the provider context generated during provider 108initialisation (see L<provider(7)>). 109 110OSSL_FUNC_digest_freectx() is passed a pointer to the provider side digest context in 111the I<dctx> parameter. 112This function should free any resources associated with that context. 113 114OSSL_FUNC_digest_dupctx() should duplicate the provider side digest context in the 115I<dctx> parameter and return the duplicate copy. 116 117OSSL_FUNC_digest_copyctx() should copy the provider side digest context in the 118I<vinctx> parameter to the I<voutctx> parameter which is the another provider side 119context. 120The OSSL_FUNC_digest_copyctx function is used in the EVP_MD_CTX_copy_ex function to 121speed up HMAC operations in the PBKDF2. 122This function is optional, and dupctx will be used if there is no EVP_MD_CTX_copy_ex 123function. 124 125=head2 Digest Generation Functions 126 127OSSL_FUNC_digest_init() initialises a digest operation given a newly created 128provider side digest context in the I<dctx> parameter. 129The I<params>, if not NULL, should be set on the context in a manner similar to 130using OSSL_FUNC_digest_set_ctx_params(). 131 132OSSL_FUNC_digest_update() is called to supply data to be digested as part of a 133previously initialised digest operation. 134The I<dctx> parameter contains a pointer to a previously initialised provider 135side context. 136OSSL_FUNC_digest_update() should digest I<inl> bytes of data at the location pointed to 137by I<in>. 138OSSL_FUNC_digest_update() may be called multiple times for a single digest operation. 139 140OSSL_FUNC_digest_final() generates a digest started through previous OSSL_FUNC_digest_init() 141and OSSL_FUNC_digest_update() calls. 142The I<dctx> parameter contains a pointer to the provider side context. 143The digest should be written to I<*out> and the length of the digest to 144I<*outl>. 145The digest should not exceed I<outsz> bytes. 146 147OSSL_FUNC_digest_digest() is a "oneshot" digest function. 148No provider side digest context is used. 149Instead the provider context that was created during provider initialisation is 150passed in the I<provctx> parameter (see L<provider(7)>). 151I<inl> bytes at I<in> should be digested and the result should be stored at 152I<out>. The length of the digest should be stored in I<*outl> which should not 153exceed I<outsz> bytes. 154 155=head2 Digest Parameters 156 157See L<OSSL_PARAM(3)> for further details on the parameters structure used by 158these functions. 159 160OSSL_FUNC_digest_get_params() gets details of the algorithm implementation 161and stores them in I<params>. 162 163OSSL_FUNC_digest_set_ctx_params() sets digest operation parameters for the 164provider side digest context I<dctx> to I<params>. 165Any parameter settings are additional to any that were previously set. 166Passing NULL for I<params> should return true. 167 168OSSL_FUNC_digest_get_ctx_params() gets digest operation details details from 169the given provider side digest context I<dctx> and stores them in I<params>. 170Passing NULL for I<params> should return true. 171 172OSSL_FUNC_digest_gettable_params() returns a constant L<OSSL_PARAM(3)> array 173containing descriptors of the parameters that OSSL_FUNC_digest_get_params() 174can handle. 175 176OSSL_FUNC_digest_gettable_ctx_params() and 177OSSL_FUNC_digest_settable_ctx_params() both return constant 178L<OSSL_PARAM(3)> arrays as descriptors of the parameters that 179OSSL_FUNC_digest_get_ctx_params() and OSSL_FUNC_digest_set_ctx_params() 180can handle, respectively. The array is based on the current state of 181the provider side context if I<dctx> is not NULL and on the provider 182side algorithm I<provctx> otherwise. 183 184Parameters currently recognised by built-in digests with this function 185are as follows. Not all parameters are relevant to, or are understood 186by all digests: 187 188=over 4 189 190=item "blocksize" (B<OSSL_DIGEST_PARAM_BLOCK_SIZE>) <unsigned integer> 191 192The digest block size. 193The length of the "blocksize" parameter should not exceed that of a B<size_t>. 194 195=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer> 196 197The digest output size. 198The length of the "size" parameter should not exceed that of a B<size_t>. 199 200=item "flags" (B<OSSL_DIGEST_PARAM_FLAGS>) <unsigned integer> 201 202Diverse flags that describe exceptional behaviour for the digest: 203 204=over 4 205 206=item B<EVP_MD_FLAG_ONESHOT> 207 208This digest method can only handle one block of input. 209 210=item B<EVP_MD_FLAG_XOF> 211 212This digest method is an extensible-output function (XOF). 213 214=item B<EVP_MD_FLAG_DIGALGID_NULL> 215 216When setting up a DigestAlgorithmIdentifier, this flag will have the 217parameter set to NULL by default. Use this for PKCS#1. I<Note: if 218combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.> 219 220=item B<EVP_MD_FLAG_DIGALGID_ABSENT> 221 222When setting up a DigestAlgorithmIdentifier, this flag will have the 223parameter be left absent by default. I<Note: if combined with 224EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> 225 226=item B<EVP_MD_FLAG_DIGALGID_CUSTOM> 227 228Custom DigestAlgorithmIdentifier handling via ctrl, with 229B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with 230EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> 231Currently unused. 232 233=back 234 235The length of the "flags" parameter should equal that of an 236B<unsigned long int>. 237 238=back 239 240=head2 Digest Context Parameters 241 242OSSL_FUNC_digest_set_ctx_params() sets digest parameters associated with the 243given provider side digest context I<dctx> to I<params>. 244Any parameter settings are additional to any that were previously set. 245See L<OSSL_PARAM(3)> for further details on the parameters structure. 246 247OSSL_FUNC_digest_get_ctx_params() gets details of currently set parameters 248values associated with the give provider side digest context I<dctx> 249and stores them in I<params>. 250See L<OSSL_PARAM(3)> for further details on the parameters structure. 251 252=head1 RETURN VALUES 253 254OSSL_FUNC_digest_newctx() and OSSL_FUNC_digest_dupctx() should return the newly created 255provider side digest context, or NULL on failure. 256 257OSSL_FUNC_digest_init(), OSSL_FUNC_digest_update(), OSSL_FUNC_digest_final(), OSSL_FUNC_digest_digest(), 258OSSL_FUNC_digest_set_params() and OSSL_FUNC_digest_get_params() should return 1 for success or 2590 on error. 260 261OSSL_FUNC_digest_size() should return the digest size. 262 263OSSL_FUNC_digest_block_size() should return the block size of the underlying digest 264algorithm. 265 266=head1 BUGS 267 268The EVP_Q_digest(), EVP_Digest() and EVP_DigestFinal_ex() API calls do not 269expect the digest size to be larger than EVP_MAX_MD_SIZE. Any algorithm which 270produces larger digests is unusable with those API calls. 271 272=head1 SEE ALSO 273 274L<provider(7)>, L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-default(7)>, 275L<OSSL_PROVIDER-legacy(7)>, 276L<EVP_MD-common(7)>, L<EVP_MD-BLAKE2(7)>, L<EVP_MD-MD2(7)>, 277L<EVP_MD-MD4(7)>, L<EVP_MD-MD5(7)>, L<EVP_MD-MD5-SHA1(7)>, 278L<EVP_MD-MDC2(7)>, L<EVP_MD-RIPEMD160(7)>, L<EVP_MD-SHA1(7)>, 279L<EVP_MD-SHA2(7)>, L<EVP_MD-SHA3(7)>, L<EVP_MD-KECCAK(7)> 280L<EVP_MD-SHAKE(7)>, L<EVP_MD-SM3(7)>, L<EVP_MD-WHIRLPOOL(7)>, 281L<EVP_MD-NULL(7)>, 282L<life_cycle-digest(7)>, L<EVP_DigestInit(3)> 283 284=head1 HISTORY 285 286The provider DIGEST interface was introduced in OpenSSL 3.0. 287OSSL_FUNC_digest_copyctx() was added in 3.5 version. 288 289=head1 COPYRIGHT 290 291Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 292 293Licensed under the Apache License 2.0 (the "License"). You may not use 294this file except in compliance with the License. You can obtain a copy 295in the file LICENSE in the source distribution or at 296L<https://www.openssl.org/source/license.html>. 297 298=cut 299