From 0388d212af3e3798724cff3b2a5036f17faf41fb Mon Sep 17 00:00:00 2001 From: Antoine Salon Date: Fri, 14 Dec 2018 12:47:07 -0800 Subject: [PATCH] Add missing EVP_MD documentation Signed-off-by: Antoine Salon Reviewed-by: Paul Dale Reviewed-by: Matt Caswell (cherry picked from commit 37842dfaebcf28b4ca452c6abd93ebde1b4aa6dc) Reviewed-by: Tomas Mraz Reviewed-by: Matthias St. Pierre (Merged from https://github.com/openssl/openssl/pull/10094) --- doc/man3/EVP_DigestInit.pod | 88 ++++++++++++++++++++++++++++++------ doc/man3/EVP_MD_meth_new.pod | 21 +++++++-- 2 files changed, 91 insertions(+), 18 deletions(-) diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index d5cbee45ca..434e22030f 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -2,17 +2,17 @@ =head1 NAME -EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex, -EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, -EVP_MD_CTX_test_flags, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, +EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy, +EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, 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_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, -EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, -EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_md_data, +EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags, +EVP_MD_CTX_md, EVP_MD_CTX_type, EVP_MD_CTX_size, EVP_MD_CTX_block_size, +EVP_MD_CTX_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn, EVP_md_null, -EVP_get_digestbyname, EVP_get_digestbynid, -EVP_get_digestbyobj, -EVP_MD_CTX_set_pkey_ctx - EVP digest routines +EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj, +EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_set_pkey_ctx - EVP digest routines =head1 SYNOPSIS @@ -26,6 +26,8 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags); int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags); + int EVP_Digest(const void *data, size_t count, unsigned char *md, + unsigned int *size, const EVP_MD *type, ENGINE *impl); 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); @@ -42,12 +44,18 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines int EVP_MD_pkey_type(const EVP_MD *md); int EVP_MD_size(const EVP_MD *md); int EVP_MD_block_size(const EVP_MD *md); + unsigned long EVP_MD_flags(const EVP_MD *md); const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); int EVP_MD_CTX_size(const EVP_MD_CTX *ctx); int EVP_MD_CTX_block_size(const EVP_MD_CTX *ctx); int EVP_MD_CTX_type(const EVP_MD_CTX *ctx); void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx); + int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx, + const void *data, size_t count); + void EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx, + int (*update)(EVP_MD_CTX *ctx, + const void *data, size_t count)); const EVP_MD *EVP_md_null(void); @@ -55,6 +63,7 @@ EVP_MD_CTX_set_pkey_ctx - EVP digest routines const EVP_MD *EVP_get_digestbynid(int type); const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); + EVP_PKEY_CTX *EVP_MD_CTX_pkey_ctx(const EVP_MD_CTX *ctx); void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx); =head1 DESCRIPTION @@ -79,12 +88,24 @@ Cleans up digest context B and frees up the space allocated to it. =item EVP_MD_CTX_ctrl() -Performs digest-specific control actions on context B. +Performs digest-specific control actions on context B. The control command +is indicated in B and any additional arguments in B and B. +EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions +may apply depending on the control type and digest implementation. +See L below for more information. =item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags() Sets, clears and tests B flags. See L below for more information. +=item EVP_Digest() + +A wrapper around the Digest Init_ex, Update and Final_ex functions. +Hashes B bytes of data at B using a digest B from ENGINE +B. The digest value is placed in B and its length is written at B +if the pointer is not NULL. At most B bytes will be written. +If B is NULL the default implementation of digest B is used. + =item EVP_DigestInit_ex() Sets up digest context B to use a digest B from ENGINE B. @@ -163,6 +184,21 @@ EVP_MD_meth_set_app_datasize(). Returns the B structure corresponding to the passed B. +=item EVP_MD_CTX_set_update_fn() + +Sets the update function for B to B. +This is the function that is called by EVP_DigestUpdate. If not set, the +update function from the B type specified at initialization is used. + +=item EVP_MD_CTX_update_fn() + +Returns the update function for B. + +=item EVP_MD_flags() + +Returns the B flags. Note that these are different from the B +ones. See L for more information. + =item EVP_MD_pkey_type() Returns the NID of the public key signing algorithm associated with this @@ -182,10 +218,15 @@ EVP_get_digestbyobj() Returns an B structure when passed a digest name, a digest B or an B structure respectively. +=item EVP_MD_CTX_pkey_ctx() + +Returns the B assigned to B. The returned pointer should not +be freed by the caller. + =item EVP_MD_CTX_set_pkey_ctx() Assigns an B to B. This is usually used to provide -a customzied B to L or +a customized B to L or L. The B passed to this function should be freed by the caller. A NULL B pointer is also allowed to clear the B assigned to B. In such case, freeing the cleared B or not @@ -193,6 +234,27 @@ depends on how the B is created. =back +=head1 CONTROLS + +EVP_MD_CTX_ctrl() can be used to send the following standard controls: + +=over 4 + +=item EVP_MD_CTRL_MICALG + +Gets the digest Message Integrity Check algorithm string. This is used when +creating S/MIME multipart/signed messages, as specified in RFC 3851. +The string value is written to B. + +=item EVP_MD_CTRL_XOF_LEN + +This control sets the digest length for extendable output functions to B. +Sending this control directly should not be necessary, the use of +C is preferred. +Currently used by SHAKE. + +=back + =head1 FLAGS EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags() @@ -245,8 +307,7 @@ Returns 1 if successful or 0 for failure. Returns 1 if successful or 0 for failure. =item EVP_MD_type(), -EVP_MD_pkey_type(), -EVP_MD_type() +EVP_MD_pkey_type() Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none exists. @@ -350,6 +411,7 @@ digest name passed on the command line. =head1 SEE ALSO +L, L, L diff --git a/doc/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod index 0265c7d504..e17a4cd519 100644 --- a/doc/man3/EVP_MD_meth_new.pod +++ b/doc/man3/EVP_MD_meth_new.pod @@ -84,7 +84,12 @@ together. The available flags are: =item EVP_MD_FLAG_ONESHOT -This digest method can only handles one block of input. +This digest method can only handle one block of input. + +=item EVP_MD_FLAG_XOF + +This digest method is an extensible-output function (XOF) and supports +the B control. =item EVP_MD_FLAG_DIGALGID_NULL @@ -105,19 +110,24 @@ B as default. I Currently unused. +=item EVP_MD_FLAG_FIPS + +This digest method is suitable for use in FIPS mode. +Currently unused. + =back EVP_MD_meth_set_init() sets the digest init function for B. -The digest init function is called by EVP_DigestInit(), +The digest init function is called by EVP_Digest(), EVP_DigestInit(), EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit() and EVP_VerifyInit_ex(). EVP_MD_meth_set_update() sets the digest update function for B. -The digest update function is called by EVP_DigestUpdate(), +The digest update function is called by EVP_Digest(), EVP_DigestUpdate() and EVP_SignUpdate(). EVP_MD_meth_set_final() sets the digest final function for B. -The digest final function is called by EVP_DigestFinal(), +The digest final function is called by EVP_Digest(), EVP_DigestFinal(), EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal(). EVP_MD_meth_set_copy() sets the function for B to do extra @@ -138,6 +148,7 @@ This cleanup function is called by EVP_MD_CTX_reset() and EVP_MD_CTX_free(). EVP_MD_meth_set_ctrl() sets the control function for B. +See L for the available controls. EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(), EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(), @@ -169,7 +180,7 @@ The B structure was openly available in OpenSSL before version =head1 COPYRIGHT -Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy -- 2.25.1