From: Pauli Date: Wed, 3 Mar 2021 00:59:01 +0000 (+1000) Subject: doc: update digest documentation to include the new init functions with params X-Git-Tag: openssl-3.0.0-alpha14~317 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5a7e999114562e5d9b696effac550d9d141ff087;p=thirdparty%2Fopenssl.git doc: update digest documentation to include the new init functions with params Reviewed-by: Shane Lontis (Merged from https://github.com/openssl/openssl/pull/14383) --- diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index ac527e407e4..043717758e4 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -10,8 +10,8 @@ EVP_MD_CTX_set_params, EVP_MD_CTX_get_params, EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params, EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, -EVP_Digest, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, -EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, +EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, +EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, EVP_MD_is_a, EVP_MD_name, EVP_MD_number, EVP_MD_names_do_all, EVP_MD_provider, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags, EVP_MD_CTX_name, @@ -49,6 +49,8 @@ EVP_MD_do_all_provided int EVP_Digest(const void *data, size_t count, unsigned char *md, unsigned int *size, const EVP_MD *type, ENGINE *impl); + int EVP_DigestInit_ex2(EVP_MD_CTX *ctx, const EVP_MD *type, + const OSSL_PARAM params[]); int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); @@ -154,7 +156,7 @@ providers.> Performs digest-specific control actions on context I. The control command is indicated in I and any additional arguments in I and I. -EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions +EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex2(). Other restrictions may apply depending on the control type and digest implementation. If this function happens to be used with a fetched B, it will @@ -216,6 +218,18 @@ I. The digest value is placed in I and its length is written at I bytes will be written. If I is NULL the default implementation of digest I is used. +=item EVP_DigestInit_ex2() + +Sets up digest context I to use a digest I. +I is typically supplied by a function such as EVP_sha1(), or a +value explicitly fetched with EVP_MD_fetch(). + +The parameters B are set on the context after initialisation. + +The I parameter can be NULL if I has been already initialized +with another EVP_DigestInit_ex() call and has not been reset with +EVP_MD_CTX_reset(). + =item EVP_DigestInit_ex() Sets up digest context I to use a digest I. @@ -242,14 +256,14 @@ parameter is not NULL then the number of bytes of data written (i.e. the length of the digest) will be written to the integer at I, at most B bytes will be written. After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() can be made, but -EVP_DigestInit_ex() can be called to initialize a new digest operation. +EVP_DigestInit_ex2() can be called to initialize a new digest operation. =item EVP_DigestFinalXOF() Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256. It retrieves the digest value from I and places it in I-sized I. After calling this function no additional calls to EVP_DigestUpdate() can be -made, but EVP_DigestInit_ex() can be called to initialize a new operation. +made, but EVP_DigestInit_ex2() can be called to initialize a new operation. =item EVP_MD_CTX_copy_ex() @@ -259,9 +273,9 @@ few bytes. =item EVP_DigestInit() -Behaves in the same way as EVP_DigestInit_ex() except it always uses the -default digest implementation and calls EVP_MD_CTX_reset() so it cannot -be used with an I of NULL. +Behaves in the same way as EVP_DigestInit_ex2() except it doesn't set any +parameters and calls EVP_MD_CTX_reset() so it cannot be used with an I +of NULL. =item EVP_DigestFinal() @@ -333,7 +347,7 @@ EVP_MD_meth_set_app_datasize(). =item EVP_MD_CTX_md() Returns the B structure corresponding to the passed B. This -will be the same B object originally passed to EVP_DigestInit_ex() (or +will be the same B object originally passed to EVP_DigestInit_ex2() (or other similar function) when the EVP_MD_CTX was first initialised. Note that where explicit fetch is in use (see L) the value returned from this function will not have its reference count incremented and therefore it @@ -500,7 +514,8 @@ Returns a pointer to a B for success or NULL for failure. Returns 1 for success or 0 for failure. -=item EVP_DigestInit_ex(), +=item EVP_DigestInit_ex2(), +EVP_DigestInit_ex(), EVP_DigestUpdate(), EVP_DigestFinal_ex() @@ -620,7 +635,7 @@ digest name passed on the command line. } mdctx = EVP_MD_CTX_new(); - EVP_DigestInit_ex(mdctx, md, NULL); + EVP_DigestInit_ex2(mdctx, md, NULL); EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); EVP_DigestFinal_ex(mdctx, md_value, &md_len); @@ -669,7 +684,7 @@ The EVP_dss1() function was removed in OpenSSL 1.1.0. The EVP_MD_CTX_set_pkey_ctx() function was added in OpenSSL 1.1.1. -The EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), +The EVP_DigestInit_ex2(), EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), EVP_MD_get_params(), EVP_MD_CTX_set_params(), EVP_MD_CTX_get_params(), EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(), EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() and