diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_DigestInit.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/EVP_DigestInit.3 | 506 |
1 files changed, 250 insertions, 256 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_DigestInit.3 b/secure/lib/libcrypto/man/man3/EVP_DigestInit.3 index 625abc8d58ed..f503de4abcea 100644 --- a/secure/lib/libcrypto/man/man3/EVP_DigestInit.3 +++ b/secure/lib/libcrypto/man/man3/EVP_DigestInit.3 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .ft R .fi .. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. \*(C+ will -.\" give a nicer C++. Capital omega is used to do unbreakable dashes and -.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, -.\" nothing in troff, for use with C<>. -.tr \(*W- -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' . ds C` . ds C' 'br\} @@ -68,100 +52,42 @@ . \} .\} .rr rF -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "EVP_DIGESTINIT 3ossl" -.TH EVP_DIGESTINIT 3ossl "2023-09-19" "3.0.11" "OpenSSL" +.TH EVP_DIGESTINIT 3ossl 2025-07-01 3.5.1 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh -.SH "NAME" +.SH NAME EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free, EVP_MD_get_params, EVP_MD_gettable_params, -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_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_dup, +EVP_MD_CTX_copy, EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, 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_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, +EVP_DigestSqueeze, EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type, EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags, EVP_MD_CTX_get0_name, EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md, -EVP_MD_CTX_get_type, EVP_MD_CTX_get_size, EVP_MD_CTX_get_block_size, +EVP_MD_CTX_get_type, EVP_MD_CTX_get_size_ex, EVP_MD_CTX_get_block_size, EVP_MD_CTX_get0_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_get_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, EVP_MD_do_all_provided, EVP_MD_type, EVP_MD_nid, EVP_MD_name, EVP_MD_pkey_type, EVP_MD_size, -EVP_MD_block_size, EVP_MD_flags, EVP_MD_CTX_size, EVP_MD_CTX_block_size, +EVP_MD_block_size, EVP_MD_flags, EVP_MD_xof, +EVP_MD_CTX_size, EVP_MD_CTX_get_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data \&\- EVP digest routines -.SH "SYNOPSIS" +.SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/evp.h> @@ -196,8 +122,10 @@ EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data \& 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); -\& int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *md, size_t len); +\& int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen); +\& int EVP_DigestSqueeze(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen); \& +\& EVP_MD_CTX *EVP_MD_CTX_dup(const EVP_MD_CTX *in); \& int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); \& \& int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); @@ -217,11 +145,12 @@ EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data \& int EVP_MD_get_size(const EVP_MD *md); \& int EVP_MD_get_block_size(const EVP_MD *md); \& unsigned long EVP_MD_get_flags(const EVP_MD *md); +\& int EVP_MD_xof(const EVP_MD *md); \& \& const EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx); \& EVP_MD *EVP_MD_CTX_get1_md(EVP_MD_CTX *ctx); \& const char *EVP_MD_CTX_get0_name(const EVP_MD_CTX *ctx); -\& int EVP_MD_CTX_get_size(const EVP_MD_CTX *ctx); +\& int EVP_MD_CTX_get_size_ex(const EVP_MD_CTX *ctx); \& int EVP_MD_CTX_get_block_size(const EVP_MD_CTX *ctx); \& int EVP_MD_CTX_get_type(const EVP_MD_CTX *ctx); \& void *EVP_MD_CTX_get0_md_data(const EVP_MD_CTX *ctx); @@ -246,7 +175,8 @@ EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data \& #define EVP_MD_size EVP_MD_get_size \& #define EVP_MD_block_size EVP_MD_get_block_size \& #define EVP_MD_flags EVP_MD_get_flags -\& #define EVP_MD_CTX_size EVP_MD_CTX_get_size +\& #define EVP_MD_CTX_get_size EVP_MD_CTX_get_size_ex +\& #define EVP_MD_CTX_size EVP_MD_CTX_get_size_ex \& #define EVP_MD_CTX_block_size EVP_MD_CTX_get_block_size \& #define EVP_MD_CTX_type EVP_MD_CTX_get_type \& #define EVP_MD_CTX_pkey_ctx EVP_MD_CTX_get_pkey_ctx @@ -254,7 +184,7 @@ EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data .Ve .PP The following functions have been deprecated since OpenSSL 3.0, and can be -hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, see \fBopenssl_user_macros\fR\|(7): .PP .Vb 1 @@ -267,41 +197,52 @@ see \fBopenssl_user_macros\fR\|(7): \& int (*update)(EVP_MD_CTX *ctx, \& const void *data, size_t count)); .Ve -.SH "DESCRIPTION" +.SH DESCRIPTION .IX Header "DESCRIPTION" -The \s-1EVP\s0 digest routines are a high-level interface to message digests, -and should be used instead of the digest-specific functions. +The EVP digest routines are a high-level interface to message digests, and +Extendable Output Functions (XOF). +.PP +The \fBEVP_MD\fR type is a structure for digest method implementation. .PP -The \fB\s-1EVP_MD\s0\fR type is a structure for digest method implementation. -.IP "\fBEVP_MD_fetch()\fR" 4 +Each Message digest algorithm (such as SHA256) produces a fixed size output +length which is returned when \fBEVP_DigestFinal_ex()\fR is called. +Extendable Output Functions (XOF) such as SHAKE256 have a variable sized output +length \fIoutlen\fR which can be used with either \fBEVP_DigestFinalXOF()\fR or +\&\fBEVP_DigestSqueeze()\fR. \fBEVP_DigestFinal_ex()\fR may also be used for an XOF, but the +"xoflen" must be set beforehand (See "PARAMETERS"). +Note that \fBEVP_MD_get_size()\fR and \fBEVP_MD_CTX_get_size_ex()\fR behave differently for +an XOF. +.IP \fBEVP_MD_fetch()\fR 4 .IX Item "EVP_MD_fetch()" Fetches the digest implementation for the given \fIalgorithm\fR from any provider offering it, within the criteria given by the \fIproperties\fR. -See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for further information. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information. .Sp The returned value must eventually be freed with \fBEVP_MD_free()\fR. .Sp -Fetched \fB\s-1EVP_MD\s0\fR structures are reference counted. -.IP "\fBEVP_MD_up_ref()\fR" 4 +Fetched \fBEVP_MD\fR structures are reference counted. +.IP \fBEVP_MD_up_ref()\fR 4 .IX Item "EVP_MD_up_ref()" -Increments the reference count for an \fB\s-1EVP_MD\s0\fR structure. -.IP "\fBEVP_MD_free()\fR" 4 +Increments the reference count for an \fBEVP_MD\fR structure. +.IP \fBEVP_MD_free()\fR 4 .IX Item "EVP_MD_free()" -Decrements the reference count for the fetched \fB\s-1EVP_MD\s0\fR structure. +Decrements the reference count for the fetched \fBEVP_MD\fR structure. If the reference count drops to 0 then the structure is freed. -.IP "\fBEVP_MD_CTX_new()\fR" 4 +If the argument is NULL, nothing is done. +.IP \fBEVP_MD_CTX_new()\fR 4 .IX Item "EVP_MD_CTX_new()" Allocates and returns a digest context. -.IP "\fBEVP_MD_CTX_reset()\fR" 4 +.IP \fBEVP_MD_CTX_reset()\fR 4 .IX Item "EVP_MD_CTX_reset()" Resets the digest context \fIctx\fR. This can be used to reuse an already existing context. -.IP "\fBEVP_MD_CTX_free()\fR" 4 +.IP \fBEVP_MD_CTX_free()\fR 4 .IX Item "EVP_MD_CTX_free()" Cleans up digest context \fIctx\fR and frees up the space allocated to it. -.IP "\fBEVP_MD_CTX_ctrl()\fR" 4 +If the argument is NULL, nothing is done. +.IP \fBEVP_MD_CTX_ctrl()\fR 4 .IX Item "EVP_MD_CTX_ctrl()" -\&\fIThis is a legacy method. \f(BIEVP_MD_CTX_set_params()\fI and \f(BIEVP_MD_CTX_get_params()\fI +\&\fIThis is a legacy method. \fR\f(BIEVP_MD_CTX_set_params()\fR\fI and \fR\f(BIEVP_MD_CTX_get_params()\fR\fI is the mechanism that should be used to set and get parameters that are used by providers.\fR .Sp @@ -310,71 +251,71 @@ is indicated in \fIcmd\fR and any additional arguments in \fIp1\fR and \fIp2\fR. \&\fBEVP_MD_CTX_ctrl()\fR must be called after \fBEVP_DigestInit_ex2()\fR. Other restrictions may apply depending on the control type and digest implementation. .Sp -If this function happens to be used with a fetched \fB\s-1EVP_MD\s0\fR, it will -translate the controls that are known to OpenSSL into \s-1\fBOSSL_PARAM\s0\fR\|(3) +If this function happens to be used with a fetched \fBEVP_MD\fR, it will +translate the controls that are known to OpenSSL into \fBOSSL_PARAM\fR\|(3) parameters with keys defined by OpenSSL and call \fBEVP_MD_CTX_get_params()\fR or \&\fBEVP_MD_CTX_set_params()\fR as is appropriate for each control command. .Sp -See \*(L"\s-1CONTROLS\*(R"\s0 below for more information, including what translations are +See "CONTROLS" below for more information, including what translations are being done. -.IP "\fBEVP_MD_get_params()\fR" 4 +.IP \fBEVP_MD_get_params()\fR 4 .IX Item "EVP_MD_get_params()" -Retrieves the requested list of \fIparams\fR from a \s-1MD\s0 \fImd\fR. -See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information. -.IP "\fBEVP_MD_CTX_get_params()\fR" 4 +Retrieves the requested list of \fIparams\fR from a MD \fImd\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_MD_CTX_get_params()\fR 4 .IX Item "EVP_MD_CTX_get_params()" -Retrieves the requested list of \fIparams\fR from a \s-1MD\s0 context \fIctx\fR. -See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information. -.IP "\fBEVP_MD_CTX_set_params()\fR" 4 +Retrieves the requested list of \fIparams\fR from a MD context \fIctx\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_MD_CTX_set_params()\fR 4 .IX Item "EVP_MD_CTX_set_params()" -Sets the list of \fIparams\fR into a \s-1MD\s0 context \fIctx\fR. -See \*(L"\s-1PARAMETERS\*(R"\s0 below for more information. -.IP "\fBEVP_MD_gettable_params()\fR" 4 +Sets the list of \fIparams\fR into a MD context \fIctx\fR. +See "PARAMETERS" below for more information. +.IP \fBEVP_MD_gettable_params()\fR 4 .IX Item "EVP_MD_gettable_params()" -Get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the retrievable parameters +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the retrievable parameters that can be used with \fBEVP_MD_get_params()\fR. .IP "\fBEVP_MD_gettable_ctx_params()\fR, \fBEVP_MD_CTX_gettable_params()\fR" 4 .IX Item "EVP_MD_gettable_ctx_params(), EVP_MD_CTX_gettable_params()" -Get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the retrievable parameters +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the retrievable parameters that can be used with \fBEVP_MD_CTX_get_params()\fR. \fBEVP_MD_gettable_ctx_params()\fR returns the parameters that can be retrieved from the algorithm, whereas \&\fBEVP_MD_CTX_gettable_params()\fR returns the parameters that can be retrieved in the context's current state. .IP "\fBEVP_MD_settable_ctx_params()\fR, \fBEVP_MD_CTX_settable_params()\fR" 4 .IX Item "EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params()" -Get a constant \s-1\fBOSSL_PARAM\s0\fR\|(3) array that describes the settable parameters +Get a constant \fBOSSL_PARAM\fR\|(3) array that describes the settable parameters that can be used with \fBEVP_MD_CTX_set_params()\fR. \fBEVP_MD_settable_ctx_params()\fR returns the parameters that can be set from the algorithm, whereas \&\fBEVP_MD_CTX_settable_params()\fR returns the parameters that can be set in the context's current state. .IP "\fBEVP_MD_CTX_set_flags()\fR, \fBEVP_MD_CTX_clear_flags()\fR, \fBEVP_MD_CTX_test_flags()\fR" 4 .IX Item "EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()" -Sets, clears and tests \fIctx\fR flags. See \*(L"\s-1FLAGS\*(R"\s0 below for more information. +Sets, clears and tests \fIctx\fR flags. See "FLAGS" below for more information. .IP "\fBEVP_Q_digest()\fR is a quick one-shot digest function." 4 .IX Item "EVP_Q_digest() is a quick one-shot digest function." It hashes \fIdatalen\fR bytes of data at \fIdata\fR using the digest algorithm \&\fIname\fR, which is fetched using the optional \fIlibctx\fR and \fIpropq\fR parameters. The digest value is placed in \fImd\fR and its length is written at \fImdlen\fR -if the pointer is not \s-1NULL.\s0 At most \fB\s-1EVP_MAX_MD_SIZE\s0\fR bytes will be written. -.IP "\fBEVP_Digest()\fR" 4 +if the pointer is not NULL. At most \fBEVP_MAX_MD_SIZE\fR bytes will be written. +.IP \fBEVP_Digest()\fR 4 .IX Item "EVP_Digest()" A wrapper around the Digest Init_ex, Update and Final_ex functions. -Hashes \fIcount\fR bytes of data at \fIdata\fR using a digest \fItype\fR from \s-1ENGINE\s0 +Hashes \fIcount\fR bytes of data at \fIdata\fR using a digest \fItype\fR from ENGINE \&\fIimpl\fR. The digest value is placed in \fImd\fR and its length is written at \fIsize\fR -if the pointer is not \s-1NULL.\s0 At most \fB\s-1EVP_MAX_MD_SIZE\s0\fR bytes will be written. -If \fIimpl\fR is \s-1NULL\s0 the default implementation of digest \fItype\fR is used. -.IP "\fBEVP_DigestInit_ex2()\fR" 4 +if the pointer is not NULL. At most \fBEVP_MAX_MD_SIZE\fR bytes will be written. +If \fIimpl\fR is NULL the default implementation of digest \fItype\fR is used. +.IP \fBEVP_DigestInit_ex2()\fR 4 .IX Item "EVP_DigestInit_ex2()" Sets up digest context \fIctx\fR to use a digest \fItype\fR. \&\fItype\fR is typically supplied by a function such as \fBEVP_sha1()\fR, or a -value explicitly fetched with \fBEVP_MD_fetch()\fR. +value explicitly fetched with \fBEVP_MD_fetch()\fR. \fIctx\fR \fBMUST NOT\fR be NULL. .Sp The parameters \fBparams\fR are set on the context after initialisation. .Sp -The \fItype\fR parameter can be \s-1NULL\s0 if \fIctx\fR has been already initialized +The \fItype\fR parameter can be NULL if \fIctx\fR has been already initialized with another \fBEVP_DigestInit_ex()\fR call and has not been reset with \&\fBEVP_MD_CTX_reset()\fR. -.IP "\fBEVP_DigestInit_ex()\fR" 4 +.IP \fBEVP_DigestInit_ex()\fR 4 .IX Item "EVP_DigestInit_ex()" Sets up digest context \fIctx\fR to use a digest \fItype\fR. \&\fItype\fR is typically supplied by a function such as \fBEVP_sha1()\fR, or a @@ -383,47 +324,60 @@ value explicitly fetched with \fBEVP_MD_fetch()\fR. If \fIimpl\fR is non-NULL, its implementation of the digest \fItype\fR is used if there is one, and if not, the default implementation is used. .Sp -The \fItype\fR parameter can be \s-1NULL\s0 if \fIctx\fR has been already initialized +The \fItype\fR parameter can be NULL if \fIctx\fR has been already initialized with another \fBEVP_DigestInit_ex()\fR call and has not been reset with \&\fBEVP_MD_CTX_reset()\fR. -.IP "\fBEVP_DigestUpdate()\fR" 4 +.IP \fBEVP_DigestUpdate()\fR 4 .IX Item "EVP_DigestUpdate()" Hashes \fIcnt\fR bytes of data at \fId\fR into the digest context \fIctx\fR. This function can be called several times on the same \fIctx\fR to hash additional data. -.IP "\fBEVP_DigestFinal_ex()\fR" 4 +.IP \fBEVP_DigestFinal_ex()\fR 4 .IX Item "EVP_DigestFinal_ex()" Retrieves the digest value from \fIctx\fR and places it in \fImd\fR. If the \fIs\fR -parameter is not \s-1NULL\s0 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 \fIs\fR, at most -\&\fB\s-1EVP_MAX_MD_SIZE\s0\fR bytes will be written. After calling \fBEVP_DigestFinal_ex()\fR -no additional calls to \fBEVP_DigestUpdate()\fR can be made, but -\&\fBEVP_DigestInit_ex2()\fR can be called to initialize a new digest operation. -.IP "\fBEVP_DigestFinalXOF()\fR" 4 +\&\fBEVP_MAX_MD_SIZE\fR bytes will be written unless the digest implementation +allows changing the digest size and it is set to a larger value by the +application. After calling \fBEVP_DigestFinal_ex()\fR no additional calls to +\&\fBEVP_DigestUpdate()\fR can be made, but \fBEVP_DigestInit_ex2()\fR can be called to +initialize a new digest operation. \fIctx\fR \fBMUST NOT\fR be NULL. +.IP \fBEVP_DigestFinalXOF()\fR 4 .IX Item "EVP_DigestFinalXOF()" -Interfaces to extendable-output functions, XOFs, such as \s-1SHAKE128\s0 and \s-1SHAKE256.\s0 -It retrieves the digest value from \fIctx\fR and places it in \fIlen\fR\-sized \fImd\fR. +Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256. +It retrieves the digest value from \fIctx\fR and places it in \fIoutlen\fR\-sized \fIout\fR. After calling this function no additional calls to \fBEVP_DigestUpdate()\fR can be made, but \fBEVP_DigestInit_ex2()\fR can be called to initialize a new operation. -.IP "\fBEVP_MD_CTX_copy_ex()\fR" 4 +\&\fBEVP_DigestFinalXOF()\fR may only be called once +.IP \fBEVP_DigestSqueeze()\fR 4 +.IX Item "EVP_DigestSqueeze()" +Similar to \fBEVP_DigestFinalXOF()\fR but allows multiple calls to be made to +squeeze variable length output data. +\&\fBEVP_DigestFinalXOF()\fR should not be called after this. +.IP \fBEVP_MD_CTX_dup()\fR 4 +.IX Item "EVP_MD_CTX_dup()" +Can be used to duplicate the message digest state from \fIin\fR. This is useful +to avoid multiple \fBEVP_MD_fetch()\fR calls or if large amounts of data are to be +hashed which only differ in the last few bytes. +.IP \fBEVP_MD_CTX_copy_ex()\fR 4 .IX Item "EVP_MD_CTX_copy_ex()" Can be used to copy the message digest state from \fIin\fR to \fIout\fR. This is useful if large amounts of data are to be hashed which only differ in the last few bytes. -.IP "\fBEVP_DigestInit()\fR" 4 +.IP \fBEVP_DigestInit()\fR 4 .IX Item "EVP_DigestInit()" Behaves in the same way as \fBEVP_DigestInit_ex2()\fR except it doesn't set any parameters and calls \fBEVP_MD_CTX_reset()\fR so it cannot be used with an \fItype\fR -of \s-1NULL.\s0 -.IP "\fBEVP_DigestFinal()\fR" 4 +of NULL. +.IP \fBEVP_DigestFinal()\fR 4 .IX Item "EVP_DigestFinal()" Similar to \fBEVP_DigestFinal_ex()\fR except after computing the digest the digest context \fIctx\fR is automatically cleaned up with \fBEVP_MD_CTX_reset()\fR. -.IP "\fBEVP_MD_CTX_copy()\fR" 4 +.IP \fBEVP_MD_CTX_copy()\fR 4 .IX Item "EVP_MD_CTX_copy()" Similar to \fBEVP_MD_CTX_copy_ex()\fR except the destination \fIout\fR does not have to be initialized. -.IP "\fBEVP_MD_is_a()\fR" 4 +.IP \fBEVP_MD_is_a()\fR 4 .IX Item "EVP_MD_is_a()" Returns 1 if \fImd\fR is an implementation of an algorithm that's identifiable with \fIname\fR, otherwise 0. @@ -431,85 +385,95 @@ identifiable with \fIname\fR, otherwise 0. If \fImd\fR is a legacy digest (it's the return value from the likes of \&\fBEVP_sha256()\fR rather than the result of an \fBEVP_MD_fetch()\fR), only cipher names registered with the default library context (see -\&\s-1\fBOSSL_LIB_CTX\s0\fR\|(3)) will be considered. +\&\fBOSSL_LIB_CTX\fR\|(3)) will be considered. +.IP \fBEVP_MD_xof()\fR 4 +.IX Item "EVP_MD_xof()" +Returns 1 if \fImd\fR is an Extendable-output Function (XOF) otherwise it returns +0. SHAKE128 and SHAKE256 are XOF functions. +It returns 0 for BLAKE2B algorithms. .IP "\fBEVP_MD_get0_name()\fR, \fBEVP_MD_CTX_get0_name()\fR" 4 .IX Item "EVP_MD_get0_name(), EVP_MD_CTX_get0_name()" Return the name of the given message digest. For fetched message digests with multiple names, only one of them is returned; it's recommended to use \fBEVP_MD_names_do_all()\fR instead. -.IP "\fBEVP_MD_names_do_all()\fR" 4 +.IP \fBEVP_MD_names_do_all()\fR 4 .IX Item "EVP_MD_names_do_all()" Traverses all names for the \fImd\fR, and calls \fIfn\fR with each name and -\&\fIdata\fR. This is only useful with fetched \fB\s-1EVP_MD\s0\fRs. -.IP "\fBEVP_MD_get0_description()\fR" 4 +\&\fIdata\fR. This is only useful with fetched \fBEVP_MD\fRs. +.IP \fBEVP_MD_get0_description()\fR 4 .IX Item "EVP_MD_get0_description()" Returns a description of the digest, meant for display and human consumption. The description is at the discretion of the digest implementation. -.IP "\fBEVP_MD_get0_provider()\fR" 4 +.IP \fBEVP_MD_get0_provider()\fR 4 .IX Item "EVP_MD_get0_provider()" -Returns an \fB\s-1OSSL_PROVIDER\s0\fR pointer to the provider that implements the given -\&\fB\s-1EVP_MD\s0\fR. -.IP "\fBEVP_MD_get_size()\fR, \fBEVP_MD_CTX_get_size()\fR" 4 -.IX Item "EVP_MD_get_size(), EVP_MD_CTX_get_size()" -Return the size of the message digest when passed an \fB\s-1EVP_MD\s0\fR or an -\&\fB\s-1EVP_MD_CTX\s0\fR structure, i.e. the size of the hash. +Returns an \fBOSSL_PROVIDER\fR pointer to the provider that implements the given +\&\fBEVP_MD\fR. +.IP \fBEVP_MD_get_size()\fR 4 +.IX Item "EVP_MD_get_size()" +Return the size of the message digest when passed an \fBEVP_MD\fR, i.e. the size of +the hash. A negative value or 0 can occur for invalid size. +For an XOF with no default size this returns 0. +.IP "\fBEVP_MD_CTX_get_size_ex()\fR, \fBEVP_MD_CTX_get_size()\fR" 4 +.IX Item "EVP_MD_CTX_get_size_ex(), EVP_MD_CTX_get_size()" +For a normal digest this is the same as \fBEVP_MD_get_size()\fR. +For an XOF this returns the "xoflen" if it has been set, otherwise it returns 0. .IP "\fBEVP_MD_get_block_size()\fR, \fBEVP_MD_CTX_get_block_size()\fR" 4 .IX Item "EVP_MD_get_block_size(), EVP_MD_CTX_get_block_size()" -Return the block size of the message digest when passed an \fB\s-1EVP_MD\s0\fR or an -\&\fB\s-1EVP_MD_CTX\s0\fR structure. +Return the block size of the message digest when passed an \fBEVP_MD\fR or an +\&\fBEVP_MD_CTX\fR structure. .IP "\fBEVP_MD_get_type()\fR, \fBEVP_MD_CTX_get_type()\fR" 4 .IX Item "EVP_MD_get_type(), EVP_MD_CTX_get_type()" -Return the \s-1NID\s0 of the \s-1OBJECT IDENTIFIER\s0 representing the given message digest -when passed an \fB\s-1EVP_MD\s0\fR structure. For example, \f(CW\*(C`EVP_MD_get_type(EVP_sha1())\*(C'\fR -returns \fBNID_sha1\fR. This function is normally used when setting \s-1ASN1\s0 OIDs. -.IP "\fBEVP_MD_CTX_get0_md_data()\fR" 4 +Return the NID of the OBJECT IDENTIFIER representing the given message digest +when passed an \fBEVP_MD\fR structure. For example, \f(CW\*(C`EVP_MD_get_type(EVP_sha1())\*(C'\fR +returns \fBNID_sha1\fR. This function is normally used when setting ASN1 OIDs. +.IP \fBEVP_MD_CTX_get0_md_data()\fR 4 .IX Item "EVP_MD_CTX_get0_md_data()" -Return the digest method private data for the passed \fB\s-1EVP_MD_CTX\s0\fR. +Return the digest method private data for the passed \fBEVP_MD_CTX\fR. The space is allocated by OpenSSL and has the size originally set with \&\fBEVP_MD_meth_set_app_datasize()\fR. .IP "\fBEVP_MD_CTX_get0_md()\fR, \fBEVP_MD_CTX_get1_md()\fR" 4 .IX Item "EVP_MD_CTX_get0_md(), EVP_MD_CTX_get1_md()" \&\fBEVP_MD_CTX_get0_md()\fR returns -the \fB\s-1EVP_MD\s0\fR structure corresponding to the passed \fB\s-1EVP_MD_CTX\s0\fR. This -will be the same \fB\s-1EVP_MD\s0\fR object originally passed to \fBEVP_DigestInit_ex2()\fR (or -other similar function) when the \s-1EVP_MD_CTX\s0 was first initialised. Note that +the \fBEVP_MD\fR structure corresponding to the passed \fBEVP_MD_CTX\fR. This +will be the same \fBEVP_MD\fR object originally passed to \fBEVP_DigestInit_ex2()\fR (or +other similar function) when the EVP_MD_CTX was first initialised. Note that where explicit fetch is in use (see \fBEVP_MD_fetch\fR\|(3)) the value returned from this function will not have its reference count incremented and therefore it -should not be used after the \s-1EVP_MD_CTX\s0 is freed. +should not be used after the EVP_MD_CTX is freed. \&\fBEVP_MD_CTX_get1_md()\fR is the same except the ownership is passed to the -caller and is from the passed \fB\s-1EVP_MD_CTX\s0\fR. -.IP "\fBEVP_MD_CTX_set_update_fn()\fR" 4 +caller and is from the passed \fBEVP_MD_CTX\fR. +.IP \fBEVP_MD_CTX_set_update_fn()\fR 4 .IX Item "EVP_MD_CTX_set_update_fn()" Sets the update function for \fIctx\fR to \fIupdate\fR. This is the function that is called by \fBEVP_DigestUpdate()\fR. If not set, the -update function from the \fB\s-1EVP_MD\s0\fR type specified at initialization is used. -.IP "\fBEVP_MD_CTX_update_fn()\fR" 4 +update function from the \fBEVP_MD\fR type specified at initialization is used. +.IP \fBEVP_MD_CTX_update_fn()\fR 4 .IX Item "EVP_MD_CTX_update_fn()" Returns the update function for \fIctx\fR. -.IP "\fBEVP_MD_get_flags()\fR" 4 +.IP \fBEVP_MD_get_flags()\fR 4 .IX Item "EVP_MD_get_flags()" -Returns the \fImd\fR flags. Note that these are different from the \fB\s-1EVP_MD_CTX\s0\fR +Returns the \fImd\fR flags. Note that these are different from the \fBEVP_MD_CTX\fR ones. See \fBEVP_MD_meth_set_flags\fR\|(3) for more information. -.IP "\fBEVP_MD_get_pkey_type()\fR" 4 +.IP \fBEVP_MD_get_pkey_type()\fR 4 .IX Item "EVP_MD_get_pkey_type()" -Returns the \s-1NID\s0 of the public key signing algorithm associated with this -digest. For example \fBEVP_sha1()\fR is associated with \s-1RSA\s0 so this will return +Returns the NID of the public key signing algorithm associated with this +digest. For example \fBEVP_sha1()\fR is associated with RSA so this will return \&\fBNID_sha1WithRSAEncryption\fR. Since digests and signature algorithms are no longer linked this function is only retained for compatibility reasons. -.IP "\fBEVP_md_null()\fR" 4 +.IP \fBEVP_md_null()\fR 4 .IX Item "EVP_md_null()" -A \*(L"null\*(R" message digest that does nothing: i.e. the hash it returns is of zero +A "null" message digest that does nothing: i.e. the hash it returns is of zero length. .IP "\fBEVP_get_digestbyname()\fR, \fBEVP_get_digestbynid()\fR, \fBEVP_get_digestbyobj()\fR" 4 .IX Item "EVP_get_digestbyname(), EVP_get_digestbynid(), EVP_get_digestbyobj()" -Returns an \fB\s-1EVP_MD\s0\fR structure when passed a digest name, a digest \fB\s-1NID\s0\fR or an -\&\fB\s-1ASN1_OBJECT\s0\fR structure respectively. +Returns an \fBEVP_MD\fR structure when passed a digest name, a digest \fBNID\fR or an +\&\fBASN1_OBJECT\fR structure respectively. .Sp The \fBEVP_get_digestbyname()\fR function is present for backwards compatibility with OpenSSL prior to version 3 and is different to the \fBEVP_MD_fetch()\fR function -since it does not attempt to \*(L"fetch\*(R" an implementation of the cipher. +since it does not attempt to "fetch" an implementation of the cipher. Additionally, it only knows about digests that are built-in to OpenSSL and have -an associated \s-1NID.\s0 Similarly \fBEVP_get_digestbynid()\fR and \fBEVP_get_digestbyobj()\fR +an associated NID. Similarly \fBEVP_get_digestbynid()\fR and \fBEVP_get_digestbyobj()\fR also return objects without an associated implementation. .Sp When the digest objects returned by these functions are used (such as in a call @@ -518,84 +482,97 @@ fetched from the loaded providers. This fetch could fail if no suitable implementation is available. Use \fBEVP_MD_fetch()\fR instead to explicitly fetch the algorithm and an associated implementation from a provider. .Sp -See \*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7) for more information about fetching. +See "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for more information about fetching. .Sp The digest objects returned from these functions do not need to be freed with \&\fBEVP_MD_free()\fR. -.IP "\fBEVP_MD_CTX_get_pkey_ctx()\fR" 4 +.IP \fBEVP_MD_CTX_get_pkey_ctx()\fR 4 .IX Item "EVP_MD_CTX_get_pkey_ctx()" -Returns the \fB\s-1EVP_PKEY_CTX\s0\fR assigned to \fIctx\fR. The returned pointer should not +Returns the \fBEVP_PKEY_CTX\fR assigned to \fIctx\fR. The returned pointer should not be freed by the caller. -.IP "\fBEVP_MD_CTX_set_pkey_ctx()\fR" 4 +.IP \fBEVP_MD_CTX_set_pkey_ctx()\fR 4 .IX Item "EVP_MD_CTX_set_pkey_ctx()" -Assigns an \fB\s-1EVP_PKEY_CTX\s0\fR to \fB\s-1EVP_MD_CTX\s0\fR. This is usually used to provide -a customized \fB\s-1EVP_PKEY_CTX\s0\fR to \fBEVP_DigestSignInit\fR\|(3) or +Assigns an \fBEVP_PKEY_CTX\fR to \fBEVP_MD_CTX\fR. This is usually used to provide +a customized \fBEVP_PKEY_CTX\fR to \fBEVP_DigestSignInit\fR\|(3) or \&\fBEVP_DigestVerifyInit\fR\|(3). The \fIpctx\fR passed to this function should be freed -by the caller. A \s-1NULL\s0 \fIpctx\fR pointer is also allowed to clear the \fB\s-1EVP_PKEY_CTX\s0\fR -assigned to \fIctx\fR. In such case, freeing the cleared \fB\s-1EVP_PKEY_CTX\s0\fR or not -depends on how the \fB\s-1EVP_PKEY_CTX\s0\fR is created. -.IP "\fBEVP_MD_do_all_provided()\fR" 4 +by the caller. A NULL \fIpctx\fR pointer is also allowed to clear the \fBEVP_PKEY_CTX\fR +assigned to \fIctx\fR. In such case, freeing the cleared \fBEVP_PKEY_CTX\fR or not +depends on how the \fBEVP_PKEY_CTX\fR is created. +.IP \fBEVP_MD_do_all_provided()\fR 4 .IX Item "EVP_MD_do_all_provided()" Traverses all messages digests implemented by all activated providers in the given library context \fIlibctx\fR, and for each of the implementations, calls the given function \fIfn\fR with the implementation method and the given \&\fIarg\fR as argument. -.SH "PARAMETERS" +.SH PARAMETERS .IX Header "PARAMETERS" -See \s-1\fBOSSL_PARAM\s0\fR\|(3) for information about passing parameters. +See \fBOSSL_PARAM\fR\|(3) for information about passing parameters. +.PP +\&\fBEVP_MD_CTX_set_params()\fR and \fBEVP_MD_CTX_get_params()\fR can be used with the +following OSSL_PARAM keys: +.IP """xoflen"" (\fBOSSL_DIGEST_PARAM_XOFLEN\fR) <unsigned integer>" 4 +.IX Item """xoflen"" (OSSL_DIGEST_PARAM_XOFLEN) <unsigned integer>" +Sets or gets the digest length for extendable output functions. +The value should not exceed what can be given using a \fBsize_t\fR. +It may be used by SHAKE\-128 and SHAKE\-256 to set the +output length used by \fBEVP_DigestFinal_ex()\fR and \fBEVP_DigestFinal()\fR. +.IP """size"" (\fBOSSL_DIGEST_PARAM_SIZE\fR) <unsigned integer>" 4 +.IX Item """size"" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>" +Sets or gets a fixed digest length. +The value should not exceed what can be given using a \fBsize_t\fR. +It may be used by BLAKE2B\-512 to set the output length used by +\&\fBEVP_DigestFinal_ex()\fR and \fBEVP_DigestFinal()\fR. .PP -\&\fBEVP_MD_CTX_set_params()\fR can be used with the following \s-1OSSL_PARAM\s0 keys: -.ie n .IP """xoflen"" (\fB\s-1OSSL_DIGEST_PARAM_XOFLEN\s0\fR) <unsigned integer>" 4 -.el .IP "``xoflen'' (\fB\s-1OSSL_DIGEST_PARAM_XOFLEN\s0\fR) <unsigned integer>" 4 -.IX Item "xoflen (OSSL_DIGEST_PARAM_XOFLEN) <unsigned integer>" -Sets the digest length for extendable output functions. -It is used by the \s-1SHAKE\s0 algorithm and should not exceed what can be given -using a \fBsize_t\fR. -.ie n .IP """pad-type"" (\fB\s-1OSSL_DIGEST_PARAM_PAD_TYPE\s0\fR) <unsigned integer>" 4 -.el .IP "``pad-type'' (\fB\s-1OSSL_DIGEST_PARAM_PAD_TYPE\s0\fR) <unsigned integer>" 4 -.IX Item "pad-type (OSSL_DIGEST_PARAM_PAD_TYPE) <unsigned integer>" +\&\fBEVP_MD_CTX_set_params()\fR can be used with the following OSSL_PARAM keys: +.IP """pad-type"" (\fBOSSL_DIGEST_PARAM_PAD_TYPE\fR) <unsigned integer>" 4 +.IX Item """pad-type"" (OSSL_DIGEST_PARAM_PAD_TYPE) <unsigned integer>" Sets the padding type. -It is used by the \s-1MDC2\s0 algorithm. +It is used by the MDC2 algorithm. .PP -\&\fBEVP_MD_CTX_get_params()\fR can be used with the following \s-1OSSL_PARAM\s0 keys: -.ie n .IP """micalg"" (\fB\s-1OSSL_PARAM_DIGEST_KEY_MICALG\s0\fR) <\s-1UTF8\s0 string>." 4 -.el .IP "``micalg'' (\fB\s-1OSSL_PARAM_DIGEST_KEY_MICALG\s0\fR) <\s-1UTF8\s0 string>." 4 -.IX Item "micalg (OSSL_PARAM_DIGEST_KEY_MICALG) <UTF8 string>." +\&\fBEVP_MD_CTX_get_params()\fR can be used with the following OSSL_PARAM keys: +.IP """micalg"" (\fBOSSL_DIGEST_PARAM_MICALG\fR) <UTF8 string>." 4 +.IX Item """micalg"" (OSSL_DIGEST_PARAM_MICALG) <UTF8 string>." Gets the digest Message Integrity Check algorithm string. This is used when -creating S/MIME multipart/signed messages, as specified in \s-1RFC 3851.\s0 +creating S/MIME multipart/signed messages, as specified in RFC 3851. It may be used by external engines or providers. -.SH "CONTROLS" +.SH CONTROLS .IX Header "CONTROLS" \&\fBEVP_MD_CTX_ctrl()\fR can be used to send the following standard controls: -.IP "\s-1EVP_MD_CTRL_MICALG\s0" 4 +.IP EVP_MD_CTRL_MICALG 4 .IX 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 \s-1RFC 3851.\s0 +creating S/MIME multipart/signed messages, as specified in RFC 3851. The string value is written to \fIp2\fR. .Sp -When used with a fetched \fB\s-1EVP_MD\s0\fR, \fBEVP_MD_CTX_get_params()\fR gets called with -an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"micalg\*(R" (\fB\s-1OSSL_DIGEST_PARAM_MICALG\s0\fR). -.IP "\s-1EVP_MD_CTRL_XOF_LEN\s0" 4 +When used with a fetched \fBEVP_MD\fR, \fBEVP_MD_CTX_get_params()\fR gets called with +an \fBOSSL_PARAM\fR\|(3) item with the key "micalg" (\fBOSSL_DIGEST_PARAM_MICALG\fR). +.IP EVP_MD_CTRL_XOF_LEN 4 .IX Item "EVP_MD_CTRL_XOF_LEN" This control sets the digest length for extendable output functions to \fIp1\fR. Sending this control directly should not be necessary, the use of \&\fBEVP_DigestFinalXOF()\fR is preferred. -Currently used by \s-1SHAKE.\s0 +Currently used by SHAKE algorithms. .Sp -When used with a fetched \fB\s-1EVP_MD\s0\fR, \fBEVP_MD_CTX_get_params()\fR gets called with -an \s-1\fBOSSL_PARAM\s0\fR\|(3) item with the key \*(L"xoflen\*(R" (\fB\s-1OSSL_DIGEST_PARAM_XOFLEN\s0\fR). -.SH "FLAGS" +When used with a fetched \fBEVP_MD\fR, \fBEVP_MD_CTX_get_params()\fR gets called with +an \fBOSSL_PARAM\fR\|(3) item with the key "xoflen" (\fBOSSL_DIGEST_PARAM_XOFLEN\fR). +.SH FLAGS .IX Header "FLAGS" \&\fBEVP_MD_CTX_set_flags()\fR, \fBEVP_MD_CTX_clear_flags()\fR and \fBEVP_MD_CTX_test_flags()\fR -can be used the manipulate and test these \fB\s-1EVP_MD_CTX\s0\fR flags: -.IP "\s-1EVP_MD_CTX_FLAG_ONESHOT\s0" 4 +can be used the manipulate and test these \fBEVP_MD_CTX\fR flags: +.IP EVP_MD_CTX_FLAG_ONESHOT 4 .IX Item "EVP_MD_CTX_FLAG_ONESHOT" This flag instructs the digest to optimize for one update only, if possible. -.IP "\s-1EVP_MD_CTX_FLAG_NO_INIT\s0" 4 +.IP EVP_MD_CTX_FLAG_CLEANED 4 +.IX Item "EVP_MD_CTX_FLAG_CLEANED" +This flag is for internal use only and \fImust not\fR be used in user code. +.IP EVP_MD_CTX_FLAG_REUSE 4 +.IX Item "EVP_MD_CTX_FLAG_REUSE" +This flag is for internal use only and \fImust not\fR be used in user code. +.IP EVP_MD_CTX_FLAG_NO_INIT 4 .IX Item "EVP_MD_CTX_FLAG_NO_INIT" This flag instructs \fBEVP_DigestInit()\fR and similar not to initialise the implementation specific data. -.IP "\s-1EVP_MD_CTX_FLAG_FINALISE\s0" 4 +.IP EVP_MD_CTX_FLAG_FINALISE 4 .IX 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. @@ -603,17 +580,17 @@ This is inefficient if this functionality is not required, and can be disabled with this flag. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -.IP "\fBEVP_MD_fetch()\fR" 4 +.IP \fBEVP_MD_fetch()\fR 4 .IX Item "EVP_MD_fetch()" -Returns a pointer to a \fB\s-1EVP_MD\s0\fR for success or \s-1NULL\s0 for failure. -.IP "\fBEVP_MD_up_ref()\fR" 4 +Returns a pointer to a \fBEVP_MD\fR for success or NULL for failure. +.IP \fBEVP_MD_up_ref()\fR 4 .IX Item "EVP_MD_up_ref()" Returns 1 for success or 0 for failure. .IP "\fBEVP_Q_digest()\fR, \fBEVP_Digest()\fR, \fBEVP_DigestInit_ex2()\fR, \fBEVP_DigestInit_ex()\fR, \fBEVP_DigestInit()\fR, \fBEVP_DigestUpdate()\fR, \fBEVP_DigestFinal_ex()\fR, \fBEVP_DigestFinalXOF()\fR, and \fBEVP_DigestFinal()\fR" 4 .IX Item "EVP_Q_digest(), EVP_Digest(), EVP_DigestInit_ex2(), EVP_DigestInit_ex(), EVP_DigestInit(), EVP_DigestUpdate(), EVP_DigestFinal_ex(), EVP_DigestFinalXOF(), and EVP_DigestFinal()" return 1 for success and 0 for failure. -.IP "\fBEVP_MD_CTX_ctrl()\fR" 4 +.IP \fBEVP_MD_CTX_ctrl()\fR 4 .IX Item "EVP_MD_CTX_ctrl()" Returns 1 if successful or 0 for failure. .IP "\fBEVP_MD_CTX_set_params()\fR, \fBEVP_MD_CTX_get_params()\fR" 4 @@ -621,48 +598,51 @@ Returns 1 if successful or 0 for failure. Returns 1 if successful or 0 for failure. .IP "\fBEVP_MD_CTX_settable_params()\fR, \fBEVP_MD_CTX_gettable_params()\fR" 4 .IX Item "EVP_MD_CTX_settable_params(), EVP_MD_CTX_gettable_params()" -Return an array of constant \s-1\fBOSSL_PARAM\s0\fR\|(3)s, or \s-1NULL\s0 if there is none +Return an array of constant \fBOSSL_PARAM\fR\|(3)s, or NULL if there is none to get. -.IP "\fBEVP_MD_CTX_copy_ex()\fR" 4 +.IP \fBEVP_MD_CTX_dup()\fR 4 +.IX Item "EVP_MD_CTX_dup()" +Returns a new EVP_MD_CTX if successful or NULL on failure. +.IP \fBEVP_MD_CTX_copy_ex()\fR 4 .IX Item "EVP_MD_CTX_copy_ex()" Returns 1 if successful or 0 for failure. .IP "\fBEVP_MD_get_type()\fR, \fBEVP_MD_get_pkey_type()\fR" 4 .IX Item "EVP_MD_get_type(), EVP_MD_get_pkey_type()" -Returns the \s-1NID\s0 of the corresponding \s-1OBJECT IDENTIFIER\s0 or NID_undef if none +Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none exists. .IP "\fBEVP_MD_get_size()\fR, \fBEVP_MD_get_block_size()\fR, \fBEVP_MD_CTX_get_size()\fR, \fBEVP_MD_CTX_get_block_size()\fR" 4 .IX Item "EVP_MD_get_size(), EVP_MD_get_block_size(), EVP_MD_CTX_get_size(), EVP_MD_CTX_get_block_size()" Returns the digest or block size in bytes or \-1 for failure. -.IP "\fBEVP_md_null()\fR" 4 +.IP \fBEVP_md_null()\fR 4 .IX Item "EVP_md_null()" -Returns a pointer to the \fB\s-1EVP_MD\s0\fR structure of the \*(L"null\*(R" message digest. +Returns a pointer to the \fBEVP_MD\fR structure of the "null" message digest. .IP "\fBEVP_get_digestbyname()\fR, \fBEVP_get_digestbynid()\fR, \fBEVP_get_digestbyobj()\fR" 4 .IX Item "EVP_get_digestbyname(), EVP_get_digestbynid(), EVP_get_digestbyobj()" -Returns either an \fB\s-1EVP_MD\s0\fR structure or \s-1NULL\s0 if an error occurs. -.IP "\fBEVP_MD_CTX_set_pkey_ctx()\fR" 4 +Returns either an \fBEVP_MD\fR structure or NULL if an error occurs. +.IP \fBEVP_MD_CTX_set_pkey_ctx()\fR 4 .IX Item "EVP_MD_CTX_set_pkey_ctx()" This function has no return value. -.IP "\fBEVP_MD_names_do_all()\fR" 4 +.IP \fBEVP_MD_names_do_all()\fR 4 .IX Item "EVP_MD_names_do_all()" Returns 1 if the callback was called for all names. A return value of 0 means that the callback was not called for any names. -.SH "NOTES" +.SH NOTES .IX Header "NOTES" -The \fB\s-1EVP\s0\fR interface to message digests should almost always be used in +The \fBEVP\fR interface to message digests should almost always be used in preference to the low-level interfaces. This is because the code then becomes transparent to the digest used and much more flexible. .PP -New applications should use the \s-1SHA\-2\s0 (such as \fBEVP_sha256\fR\|(3)) or the \s-1SHA\-3\s0 +New applications should use the SHA\-2 (such as \fBEVP_sha256\fR\|(3)) or the SHA\-3 digest algorithms (such as \fBEVP_sha3_512\fR\|(3)). The other digest algorithms are still in common use. .PP For most applications the \fIimpl\fR parameter to \fBEVP_DigestInit_ex()\fR will be -set to \s-1NULL\s0 to use the default digest implementation. +set to NULL to use the default digest implementation. .PP Ignoring failure returns of \fBEVP_DigestInit_ex()\fR, \fBEVP_DigestInit_ex2()\fR, or \&\fBEVP_DigestInit()\fR can lead to undefined behavior on subsequent calls -updating or finalizing the \fB\s-1EVP_MD_CTX\s0\fR such as the \fBEVP_DigestUpdate()\fR or -\&\fBEVP_DigestFinal()\fR functions. The only valid calls on the \fB\s-1EVP_MD_CTX\s0\fR +updating or finalizing the \fBEVP_MD_CTX\fR such as the \fBEVP_DigestUpdate()\fR or +\&\fBEVP_DigestFinal()\fR functions. The only valid calls on the \fBEVP_MD_CTX\fR when initialization fails are calls that attempt another initialization of the context or release the context. .PP @@ -682,9 +662,9 @@ defined as macros. .PP \&\fBEVP_MD_CTX_ctrl()\fR sends commands to message digests for additional configuration or control. -.SH "EXAMPLES" +.SH EXAMPLES .IX Header "EXAMPLES" -This example digests the data \*(L"Test Message\en\*(R" and \*(L"Hello World\en\*(R", using the +This example digests the data "Test Message\en" and "Hello World\en", using the digest name passed on the command line. .PP .Vb 3 @@ -713,6 +693,10 @@ digest name passed on the command line. \& } \& \& mdctx = EVP_MD_CTX_new(); +\& if (mdctx == NULL) { +\& printf("Message digest create failed.\en"); +\& exit(1); +\& } \& if (!EVP_DigestInit_ex2(mdctx, md, NULL)) { \& printf("Message digest initialization failed.\en"); \& EVP_MD_CTX_free(mdctx); @@ -748,10 +732,10 @@ digest name passed on the command line. \&\fBEVP_MD_meth_new\fR\|(3), \&\fBopenssl\-dgst\fR\|(1), \&\fBevp\fR\|(7), -\&\s-1\fBOSSL_PROVIDER\s0\fR\|(3), -\&\s-1\fBOSSL_PARAM\s0\fR\|(3), +\&\fBOSSL_PROVIDER\fR\|(3), +\&\fBOSSL_PARAM\fR\|(3), \&\fBproperty\fR\|(7), -\&\*(L"\s-1ALGORITHM FETCHING\*(R"\s0 in \fBcrypto\fR\|(7), +"ALGORITHM FETCHING" in \fBcrypto\fR\|(7), \&\fBprovider\-digest\fR\|(7), \&\fBlife_cycle\-digest\fR\|(7) .PP @@ -768,13 +752,13 @@ The full list of digest algorithms are provided below. \&\fBEVP_sha3_224\fR\|(3), \&\fBEVP_sm3\fR\|(3), \&\fBEVP_whirlpool\fR\|(3) -.SH "HISTORY" +.SH HISTORY .IX Header "HISTORY" The \fBEVP_MD_CTX_create()\fR and \fBEVP_MD_CTX_destroy()\fR functions were renamed to \&\fBEVP_MD_CTX_new()\fR and \fBEVP_MD_CTX_free()\fR in OpenSSL 1.1.0, respectively. .PP The link between digests and signing algorithms was fixed in OpenSSL 1.0 and -later, so now \fBEVP_sha1()\fR can be used with \s-1RSA\s0 and \s-1DSA.\s0 +later, so now \fBEVP_sha1()\fR can be used with RSA and DSA. .PP The \fBEVP_dss1()\fR function was removed in OpenSSL 1.1.0. .PP @@ -798,11 +782,21 @@ The \fBEVP_MD_CTX_md()\fR function was deprecated in OpenSSL 3.0; use \&\fBEVP_MD_CTX_get0_md()\fR instead. \&\fBEVP_MD_CTX_update_fn()\fR and \fBEVP_MD_CTX_set_update_fn()\fR were deprecated in OpenSSL 3.0. -.SH "COPYRIGHT" +.PP +The \fBEVP_MD_CTX_dup()\fR function was added in OpenSSL 3.1. +.PP +The \fBEVP_DigestSqueeze()\fR function was added in OpenSSL 3.3. +.PP +The \fBEVP_MD_CTX_get_size_ex()\fR and \fBEVP_xof()\fR functions were added in OpenSSL 3.4. +The macros \fBEVP_MD_CTX_get_size()\fR and EVP_MD_CTX_size were changed in OpenSSL 3.4 +to be aliases for \fBEVP_MD_CTX_get_size_ex()\fR, previously they were aliases for +EVP_MD_get_size which returned a constant value. This is required for XOF +digests since they do not have a fixed size. +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy -in the file \s-1LICENSE\s0 in the source distribution or at +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |