QuasarApp/openssl
4
0
Fork 0
mirror of https://github.com/QuasarApp/openssl.git synced 2025-05-11 17:09:40 +00:00
Code Issues Projects Releases Wiki Activity

DOCS: Clean up doc/man3/EVP_DigestInit.pod

Browse Source 
We touch it, we clean it up!
Accordding to common man-pages(7) guidelines.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11270)
This commit is contained in:
Richard Levitte 2020-03-07 08:00:51 +01:00
parent b5b91a7963
commit 041a96e7ac
1 changed files with 36 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
doc/man3/EVP_DigestInit.pod
View File

@ -110,8 +110,8 @@ The B<EVP_MD> type is a structure for digest method implementation.
=item EVP_MD_fetch() =item EVP_MD_fetch()
Fetches the digest implementation for the given B<algorithm> from any Fetches the digest implementation for the given I<algorithm> from any
provider offering it, within the criteria given by the B<properties>. provider offering it, within the criteria given by the I<properties>.
See L<provider(7)/Fetching algorithms> for further information. See L<provider(7)/Fetching algorithms> for further information.
The returned value must eventually be freed with EVP_MD_free(). The returned value must eventually be freed with EVP_MD_free().
@ -133,12 +133,12 @@ Allocates and returns a digest context.
=item EVP_MD_CTX_reset() =item EVP_MD_CTX_reset()
Resets the digest context B<ctx>. This can be used to reuse an already Resets the digest context I<ctx>. This can be used to reuse an already
existing context. existing context.
=item EVP_MD_CTX_free() =item EVP_MD_CTX_free()
Cleans up digest context B<ctx> and frees up the space allocated to it. Cleans up digest context I<ctx> and frees up the space allocated to it.
=item EVP_MD_CTX_ctrl() =item EVP_MD_CTX_ctrl()
@ -146,8 +146,8 @@ I<This is a legacy method. EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params()
is the mechanism that should be used to set and get parameters that are used by is the mechanism that should be used to set and get parameters that are used by
providers.> providers.>
Performs digest-specific control actions on context B<ctx>. The control command Performs digest-specific control actions on context I<ctx>. The control command
is indicated in B<cmd> and any additional arguments in B<p1> and B<p2>. is indicated in I<cmd> and any additional arguments in I<p1> and I<p2>.
EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions
may apply depending on the control type and digest implementation. may apply depending on the control type and digest implementation.
@ -161,17 +161,17 @@ being done.
=item EVP_MD_get_params() =item EVP_MD_get_params()
Retrieves the requested list of B<params> from a MD B<md>. Retrieves the requested list of I<params> from a MD I<md>.
See L</PARAMETERS> below for more information. See L</PARAMETERS> below for more information.
=item EVP_MD_CTX_get_params() =item EVP_MD_CTX_get_params()
Retrieves the requested list of B<params> from a MD context B<ctx>. Retrieves the requested list of I<params> from a MD context I<ctx>.
See L</PARAMETERS> below for more information. See L</PARAMETERS> below for more information.
=item EVP_MD_CTX_set_params() =item EVP_MD_CTX_set_params()
Sets the list of B<params> into a MD context B<ctx>. Sets the list of I<params> into a MD context I<ctx>.
See L</PARAMETERS> below for more information. See L</PARAMETERS> below for more information.
=item EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(), =item EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(),
@ -189,36 +189,36 @@ See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
=item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags() =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. Sets, clears and tests I<ctx> flags. See L</FLAGS> below for more information.
=item EVP_Digest() =item EVP_Digest()
A wrapper around the Digest Init_ex, Update and Final_ex functions. 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 Hashes I<count> bytes of data at I<data> using a digest I<type> from ENGINE
B<impl>. The digest value is placed in B<md> and its length is written at B<size> I<impl>. The digest value is placed in I<md> and its length is written at I<size>
if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written. 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. If I<impl> is NULL the default implementation of digest I<type> is used.
=item EVP_DigestInit_ex() =item EVP_DigestInit_ex()
Sets up digest context B<ctx> to use a digest B<type>. Sets up digest context I<ctx> to use a digest I<type>.
B<type> is typically supplied by a function such as EVP_sha1(), or a I<type> is typically supplied by a function such as EVP_sha1(), or a
value explicitly fetched with EVP_MD_fetch(). value explicitly fetched with EVP_MD_fetch().
If B<impl> is non-NULL, its implementation of the digest B<type> is used if If I<impl> is non-NULL, its implementation of the digest I<type> is used if
there is one, and if not, the default implementation is used. there is one, and if not, the default implementation is used.
=item EVP_DigestUpdate() =item EVP_DigestUpdate()
Hashes B<cnt> bytes of data at B<d> into the digest context B<ctx>. This Hashes I<cnt> bytes of data at I<d> into the digest context I<ctx>. This
function can be called several times on the same B<ctx> to hash additional function can be called several times on the same I<ctx> to hash additional
data. data.
=item EVP_DigestFinal_ex() =item EVP_DigestFinal_ex()
Retrieves the digest value from B<ctx> and places it in B<md>. If the B<s> Retrieves the digest value from I<ctx> and places it in I<md>. If the I<s>
parameter is not NULL then the number of bytes of data written (i.e. the 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 B<s>, at most length of the digest) will be written to the integer at I<s>, at most
B<EVP_MAX_MD_SIZE> bytes will be written. After calling EVP_DigestFinal_ex() B<EVP_MAX_MD_SIZE> bytes will be written. After calling EVP_DigestFinal_ex()
no additional calls to EVP_DigestUpdate() can be made, but no additional calls to EVP_DigestUpdate() can be made, but
EVP_DigestInit_ex() can be called to initialize a new digest operation. EVP_DigestInit_ex() can be called to initialize a new digest operation.
@ -226,13 +226,13 @@ EVP_DigestInit_ex() can be called to initialize a new digest operation.
=item EVP_DigestFinalXOF() =item EVP_DigestFinalXOF()
Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256. Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256.
It retrieves the digest value from B<ctx> and places it in B<len>-sized <B>md. It retrieves the digest value from I<ctx> and places it in I<len>-sized <B>md.
After calling this function no additional calls to EVP_DigestUpdate() can be 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_ex() can be called to initialize a new operation.
=item EVP_MD_CTX_copy_ex() =item EVP_MD_CTX_copy_ex()
Can be used to copy the message digest state from B<in> to B<out>. This is Can be used to copy the message digest state from I<in> to I<out>. This is
useful if large amounts of data are to be hashed which only differ in the last useful if large amounts of data are to be hashed which only differ in the last
few bytes. few bytes.
@ -243,12 +243,12 @@ default digest implementation and calls EVP_MD_CTX_reset().
=item EVP_DigestFinal() =item EVP_DigestFinal()
Similar to EVP_DigestFinal_ex() except the digest context B<ctx> is Similar to EVP_DigestFinal_ex() except the digest context I<ctx> is
automatically cleaned up. automatically cleaned up.
=item EVP_MD_CTX_copy() =item EVP_MD_CTX_copy()
Similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to Similar to EVP_MD_CTX_copy_ex() except the destination I<out> does not have to
be initialized. be initialized.
=item EVP_MD_is_a() =item EVP_MD_is_a()
@ -319,17 +319,17 @@ should not be used after the EVP_MD_CTX is freed.
=item EVP_MD_CTX_set_update_fn() =item EVP_MD_CTX_set_update_fn()
Sets the update function for B<ctx> to B<update>. Sets the update function for I<ctx> to I<update>.
This is the function that is called by EVP_DigestUpdate. If not set, the 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. update function from the B<EVP_MD> type specified at initialization is used.
=item EVP_MD_CTX_update_fn() =item EVP_MD_CTX_update_fn()
Returns the update function for B<ctx>. Returns the update function for I<ctx>.
=item EVP_MD_flags() =item EVP_MD_flags()
Returns the B<md> flags. Note that these are different from the B<EVP_MD_CTX> Returns the I<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. ones. See L<EVP_MD_meth_set_flags(3)> for more information.
=item EVP_MD_pkey_type() =item EVP_MD_pkey_type()
@ -353,16 +353,16 @@ B<ASN1_OBJECT> structure respectively.
=item EVP_MD_CTX_pkey_ctx() =item EVP_MD_CTX_pkey_ctx()
Returns the B<EVP_PKEY_CTX> assigned to B<ctx>. The returned pointer should not Returns the B<EVP_PKEY_CTX> assigned to I<ctx>. The returned pointer should not
be freed by the caller. be freed by the caller.
=item EVP_MD_CTX_set_pkey_ctx() =item EVP_MD_CTX_set_pkey_ctx()
Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide
a customized 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 L<EVP_DigestVerifyInit(3)>. The I<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> by the caller. A NULL I<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 assigned to I<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not
depends on how the B<EVP_PKEY_CTX> is created. depends on how the B<EVP_PKEY_CTX> is created.
=item EVP_MD_do_all_provided() =item EVP_MD_do_all_provided()
@ -390,7 +390,7 @@ using a B<size_t>.
=item "pad_type" (B<OSSL_PARAM_DIGEST_KEY_PAD_TYPE>) <integer> =item "pad_type" (B<OSSL_PARAM_DIGEST_KEY_PAD_TYPE>) <integer>
Sets the pad type. Sets the padding type.
It is used by the MDC2 algorithm. It is used by the MDC2 algorithm.
=back =back
@ -417,16 +417,16 @@ EVP_MD_CTX_ctrl() can be used to send the following standard controls:
Gets the digest Message Integrity Check algorithm string. This is used when Gets the digest Message Integrity Check algorithm string. This is used when
creating S/MIME multipart/signed messages, as specified in RFC 3851. creating S/MIME multipart/signed messages, as specified in RFC 3851.
The string value is written to B<p2>. The string value is written to I<p2>.
When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with
an L<OSSL_PARAM(3)> item with the key "micalg" (B<OSSL_DIGEST_PARAM_MICALG>). an L<OSSL_PARAM(3)> item with the key "micalg" (B<OSSL_DIGEST_PARAM_MICALG>).
=item EVP_MD_CTRL_XOF_LEN =item EVP_MD_CTRL_XOF_LEN
This control sets the digest length for extendable output functions to B<p1>. This control sets the digest length for extendable output functions to I<p1>.
Sending this control directly should not be necessary, the use of Sending this control directly should not be necessary, the use of
C<EVP_DigestFinalXOF()> is preferred. EVP_DigestFinalXOF() is preferred.
Currently used by SHAKE. Currently used by SHAKE.
When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with
@ -543,7 +543,7 @@ New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3
digest algorithms (such as L<EVP_sha3_512(3)>). The other digest algorithms digest algorithms (such as L<EVP_sha3_512(3)>). The other digest algorithms
are still in common use. are still in common use.
For most applications the B<impl> parameter to EVP_DigestInit_ex() will be For most applications the I<impl> parameter to EVP_DigestInit_ex() will be
set to NULL to use the default digest implementation. set to NULL to use the default digest implementation.
The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are