Commit a9cf71a3 authored by Richard Levitte's avatar Richard Levitte
Browse files

Document more EVP_MD_CTX functions 



Fixes #6644

Reviewed-by: default avatarRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6645)
parent de72274d

doc/man3/EVP_DigestInit.pod

+50 −2
Original line number Diff line number Diff line
@@ -3,11 +3,13 @@ 
=head1 NAME



EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex,

EVP_MD_CTX_ctrl, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,

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_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_null,

EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_md_data,

EVP_md_null,

EVP_get_digestbyname, EVP_get_digestbynid,

EVP_get_digestbyobj - EVP digest routines
@@ -19,6 +21,9 @@ EVP_get_digestbyobj - EVP digest routines 
 int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);

 void EVP_MD_CTX_free(EVP_MD_CTX *ctx);

 void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2);

 void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);

 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_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);
@@ -41,6 +46,7 @@ EVP_get_digestbyobj - EVP digest routines 
 int EVP_MD_CTX_size(const EVP_MD *ctx);

 int EVP_MD_CTX_block_size(const EVP_MD *ctx);

 int EVP_MD_CTX_type(const EVP_MD *ctx);

 void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);



 const EVP_MD *EVP_md_null(void);
@@ -72,6 +78,10 @@ Cleans up digest context B<ctx> and frees up the space allocated to it. 


Performs digest-specific control actions on context B<ctx>.



=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_DigestInit_ex()



Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
@@ -140,6 +150,12 @@ Return the NID of the OBJECT IDENTIFIER representing the given message digest 
when passed an B<EVP_MD> structure.  For example, C<EVP_MD_type(EVP_sha1())>

returns B<NID_sha1>. This function is normally used when setting ASN1 OIDs.



=item EVP_MD_CTX_md_data()



Return the digest method private data for the passed B<EVP_MD_CTX>.

The space is allocated by OpenSSL and has the size originally set with

EVP_MD_meth_set_app_datasize().



=item EVP_MD_CTX_md()



Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>.
@@ -165,6 +181,38 @@ B<ASN1_OBJECT> structure respectively. 


=back



=head1 FLAGS



EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags()

can be used the manipulate and test these B<EVP_MD_CTX> flags:



=over 4



=item EVP_MD_CTX_FLAG_ONESHOT



This flag instructs the digest to optimize for one update only, if possible.



=for comment EVP_MD_CTX_FLAG_CLEANED is internal, don't mention it



=for comment EVP_MD_CTX_FLAG_REUSE is internal, don't mention it



=for comment We currently avoid documenting flags that are only bit holder:

EVP_MD_CTX_FLAG_NON_FIPS_ALLOW, EVP_MD_CTX_FLAGS_PAD_*



=item EVP_MD_CTX_FLAG_NO_INIT



This flag instructs EVP_DigestInit() and similar not to initialise the

implementation specific data.



=item EVP_MD_CTX_FLAG_FINALISE



Some functions such as EVP_DigestSign only finalise copies of internal

contexts so additional data can be included after the finalisation call.

This is inefficient if this functionality is not required, and can be

disabled with this flag.



=back



=head1 RETURN VALUES



=over 4