diff options
author | Antoine Salon <asalon@vmware.com> | 2018-12-14 12:47:07 -0800 |
---|---|---|
committer | Dr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> | 2019-10-15 16:04:46 +0200 |
commit | 0388d212af3e3798724cff3b2a5036f17faf41fb (patch) | |
tree | e6817c7cb6617b84a43b17b6b0ff7d52fba3a99a /doc | |
parent | 3fb4bdabc2cb23eeff8309b5abdc61bbedbc6bea (diff) |
Add missing EVP_MD documentation
Signed-off-by: Antoine Salon <asalon@vmware.com>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(cherry picked from commit 37842dfaebcf28b4ca452c6abd93ebde1b4aa6dc)
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/10094)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EVP_DigestInit.pod | 88 | ||||
-rw-r--r-- | 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<ctx> and frees up the space allocated to it. =item EVP_MD_CTX_ctrl() -Performs digest-specific control actions on context B<ctx>. +Performs digest-specific control actions on context B<ctx>. The control command +is indicated in B<cmd> and any additional arguments in B<p1> and B<p2>. +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</CONTROLS> 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<ctx> flags. See L</FLAGS> below for more information. +=item EVP_Digest() + +A wrapper around the Digest Init_ex, Update and Final_ex functions. +Hashes B<count> bytes of data at B<data> using a digest B<type> from ENGINE +B<impl>. The digest value is placed in B<md> and its length is written at B<size> +if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written. +If B<impl> is NULL the default implementation of digest B<type> is used. + =item EVP_DigestInit_ex() Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>. @@ -163,6 +184,21 @@ EVP_MD_meth_set_app_datasize(). Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>. +=item EVP_MD_CTX_set_update_fn() + +Sets the update function for B<ctx> to B<update>. +This is the function that is called by EVP_DigestUpdate. If not set, the +update function from the B<EVP_MD> type specified at initialization is used. + +=item EVP_MD_CTX_update_fn() + +Returns the update function for B<ctx>. + +=item EVP_MD_flags() + +Returns the B<md> flags. Note that these are different from the B<EVP_MD_CTX> +ones. See L<EVP_MD_meth_set_flags(3)> 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<EVP_MD> structure when passed a digest name, a digest B<NID> or an B<ASN1_OBJECT> structure respectively. +=item EVP_MD_CTX_pkey_ctx() + +Returns the B<EVP_PKEY_CTX> assigned to B<ctx>. The returned pointer should not +be freed by the caller. + =item EVP_MD_CTX_set_pkey_ctx() Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide -a customzied B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or +a customized B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or L<EVP_DigestVerifyInit(3)>. The B<pctx> passed to this function should be freed by the caller. A NULL B<pctx> pointer is also allowed to clear the B<EVP_PKEY_CTX> assigned to B<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not @@ -193,6 +234,27 @@ depends on how the B<EVP_PKEY_CTX> 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<p2>. + +=item EVP_MD_CTRL_XOF_LEN + +This control sets the digest length for extendable output functions to B<p1>. +Sending this control directly should not be necessary, the use of +C<EVP_DigestFinalXOF()> 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<EVP_MD_meth_new(3)>, L<dgst(1)>, L<evp(7)> 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<EVP_MD_CTRL_XOF_LEN> control. =item EVP_MD_FLAG_DIGALGID_NULL @@ -105,19 +110,24 @@ B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> 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<md>. -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<md>. -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<md>. -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<md> 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<md>. +See L<EVP_MD_CTX_ctrl(3)> 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<EVP_MD> 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 |