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 and OSSL_FUNC_digest_final should be implemented. 98All other functions are optional. 99 100=head2 Context Management Functions 101 102OSSL_FUNC_digest_newctx() should create and return a pointer to a provider side 103structure for holding context information during a digest operation. 104A pointer to this context will be passed back in a number of the other digest 105operation function calls. 106The parameter I<provctx> is the provider context generated during provider 107initialisation (see L<provider(7)>). 108 109OSSL_FUNC_digest_freectx() is passed a pointer to the provider side digest context in 110the I<dctx> parameter. 111This function should free any resources associated with that context. 112 113OSSL_FUNC_digest_dupctx() should duplicate the provider side digest context in the 114I<dctx> parameter and return the duplicate copy. 115 116OSSL_FUNC_digest_copyctx() should copy the provider side digest context in the 117I<vinctx> parameter to the I<voutctx> parameter which is the another provider side 118context. 119The OSSL_FUNC_digest_copyctx function is used in the EVP_MD_CTX_copy_ex function to 120speed up HMAC operations in the PBKDF2. 121This function is optional, and dupctx will be used if there is no EVP_MD_CTX_copy_ex 122function. 123 124=head2 Digest Generation Functions 125 126OSSL_FUNC_digest_init() initialises a digest operation given a newly created 127provider side digest context in the I<dctx> parameter. 128The I<params>, if not NULL, should be set on the context in a manner similar to 129using OSSL_FUNC_digest_set_ctx_params(). 130 131OSSL_FUNC_digest_update() is called to supply data to be digested as part of a 132previously initialised digest operation. 133The I<dctx> parameter contains a pointer to a previously initialised provider 134side context. 135OSSL_FUNC_digest_update() should digest I<inl> bytes of data at the location pointed to 136by I<in>. 137OSSL_FUNC_digest_update() may be called multiple times for a single digest operation. 138 139OSSL_FUNC_digest_final() generates a digest started through previous OSSL_FUNC_digest_init() 140and OSSL_FUNC_digest_update() calls. 141The I<dctx> parameter contains a pointer to the provider side context. 142The digest should be written to I<*out> and the length of the digest to 143I<*outl>. 144The digest should not exceed I<outsz> bytes. 145 146OSSL_FUNC_digest_digest() is a "oneshot" digest function. 147No provider side digest context is used. 148Instead the provider context that was created during provider initialisation is 149passed in the I<provctx> parameter (see L<provider(7)>). 150I<inl> bytes at I<in> should be digested and the result should be stored at 151I<out>. The length of the digest should be stored in I<*outl> which should not 152exceed I<outsz> bytes. 153 154=head2 Digest Parameters 155 156See L<OSSL_PARAM(3)> for further details on the parameters structure used by 157these functions. 158 159OSSL_FUNC_digest_get_params() gets details of the algorithm implementation 160and stores them in I<params>. 161 162OSSL_FUNC_digest_set_ctx_params() sets digest operation parameters for the 163provider side digest context I<dctx> to I<params>. 164Any parameter settings are additional to any that were previously set. 165Passing NULL for I<params> should return true. 166 167OSSL_FUNC_digest_get_ctx_params() gets digest operation details details from 168the given provider side digest context I<dctx> and stores them in I<params>. 169Passing NULL for I<params> should return true. 170 171OSSL_FUNC_digest_gettable_params() returns a constant L<OSSL_PARAM(3)> array 172containing descriptors of the parameters that OSSL_FUNC_digest_get_params() 173can handle. 174 175OSSL_FUNC_digest_gettable_ctx_params() and 176OSSL_FUNC_digest_settable_ctx_params() both return constant 177L<OSSL_PARAM(3)> arrays as descriptors of the parameters that 178OSSL_FUNC_digest_get_ctx_params() and OSSL_FUNC_digest_set_ctx_params() 179can handle, respectively. The array is based on the current state of 180the provider side context if I<dctx> is not NULL and on the provider 181side algorithm I<provctx> otherwise. 182 183Parameters currently recognised by built-in digests with this function 184are as follows. Not all parameters are relevant to, or are understood 185by all digests: 186 187=over 4 188 189=item "blocksize" (B<OSSL_DIGEST_PARAM_BLOCK_SIZE>) <unsigned integer> 190 191The digest block size. 192The length of the "blocksize" parameter should not exceed that of a B<size_t>. 193 194=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer> 195 196The digest output size. 197The length of the "size" parameter should not exceed that of a B<size_t>. 198 199=item "flags" (B<OSSL_DIGEST_PARAM_FLAGS>) <unsigned integer> 200 201Diverse flags that describe exceptional behaviour for the digest: 202 203=over 4 204 205=item B<EVP_MD_FLAG_ONESHOT> 206 207This digest method can only handle one block of input. 208 209=item B<EVP_MD_FLAG_XOF> 210 211This digest method is an extensible-output function (XOF). 212 213=item B<EVP_MD_FLAG_DIGALGID_NULL> 214 215When setting up a DigestAlgorithmIdentifier, this flag will have the 216parameter set to NULL by default. Use this for PKCS#1. I<Note: if 217combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.> 218 219=item B<EVP_MD_FLAG_DIGALGID_ABSENT> 220 221When setting up a DigestAlgorithmIdentifier, this flag will have the 222parameter be left absent by default. I<Note: if combined with 223EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> 224 225=item B<EVP_MD_FLAG_DIGALGID_CUSTOM> 226 227Custom DigestAlgorithmIdentifier handling via ctrl, with 228B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with 229EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> 230Currently unused. 231 232=back 233 234The length of the "flags" parameter should equal that of an 235B<unsigned long int>. 236 237=back 238 239=head2 Digest Context Parameters 240 241OSSL_FUNC_digest_set_ctx_params() sets digest parameters associated with the 242given provider side digest context I<dctx> to I<params>. 243Any parameter settings are additional to any that were previously set. 244See L<OSSL_PARAM(3)> for further details on the parameters structure. 245 246OSSL_FUNC_digest_get_ctx_params() gets details of currently set parameters 247values associated with the give provider side digest context I<dctx> 248and stores them in I<params>. 249See L<OSSL_PARAM(3)> for further details on the parameters structure. 250 251=head1 RETURN VALUES 252 253OSSL_FUNC_digest_newctx() and OSSL_FUNC_digest_dupctx() should return the newly created 254provider side digest context, or NULL on failure. 255 256OSSL_FUNC_digest_init(), OSSL_FUNC_digest_update(), OSSL_FUNC_digest_final(), OSSL_FUNC_digest_digest(), 257OSSL_FUNC_digest_set_params() and OSSL_FUNC_digest_get_params() should return 1 for success or 2580 on error. 259 260OSSL_FUNC_digest_size() should return the digest size. 261 262OSSL_FUNC_digest_block_size() should return the block size of the underlying digest 263algorithm. 264 265=head1 BUGS 266 267The EVP_Q_digest(), EVP_Digest() and EVP_DigestFinal_ex() API calls do not 268expect the digest size to be larger than EVP_MAX_MD_SIZE. Any algorithm which 269produces larger digests is unusable with those API calls. 270 271=head1 SEE ALSO 272 273L<provider(7)>, L<OSSL_PROVIDER-FIPS(7)>, L<OSSL_PROVIDER-default(7)>, 274L<OSSL_PROVIDER-legacy(7)>, 275L<EVP_MD-common(7)>, L<EVP_MD-BLAKE2(7)>, L<EVP_MD-MD2(7)>, 276L<EVP_MD-MD4(7)>, L<EVP_MD-MD5(7)>, L<EVP_MD-MD5-SHA1(7)>, 277L<EVP_MD-MDC2(7)>, L<EVP_MD-RIPEMD160(7)>, L<EVP_MD-SHA1(7)>, 278L<EVP_MD-SHA2(7)>, L<EVP_MD-SHA3(7)>, L<EVP_MD-KECCAK(7)> 279L<EVP_MD-SHAKE(7)>, L<EVP_MD-SM3(7)>, L<EVP_MD-WHIRLPOOL(7)>, 280L<EVP_MD-NULL(7)>, 281L<life_cycle-digest(7)>, L<EVP_DigestInit(3)> 282 283=head1 HISTORY 284 285The provider DIGEST interface was introduced in OpenSSL 3.0. 286OSSL_FUNC_digest_copyctx() was added in 3.5 version. 287 288=head1 COPYRIGHT 289 290Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 291 292Licensed under the Apache License 2.0 (the "License"). You may not use 293this file except in compliance with the License. You can obtain a copy 294in the file LICENSE in the source distribution or at 295L<https://www.openssl.org/source/license.html>. 296 297=cut 298
