diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_DigestSignInit.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/EVP_DigestSignInit.3 | 128 |
1 files changed, 86 insertions, 42 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_DigestSignInit.3 b/secure/lib/libcrypto/man/man3/EVP_DigestSignInit.3 index 699d9114b1f1..7459317f1b3d 100644 --- a/secure/lib/libcrypto/man/man3/EVP_DigestSignInit.3 +++ b/secure/lib/libcrypto/man/man3/EVP_DigestSignInit.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .rr rF -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ @@ -132,19 +130,24 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "EVP_DIGESTSIGNINIT 3" -.TH EVP_DIGESTSIGNINIT 3 "2022-05-03" "1.1.1o" "OpenSSL" +.IX Title "EVP_DIGESTSIGNINIT 3ossl" +.TH EVP_DIGESTSIGNINIT 3ossl "2023-09-19" "3.0.11" "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" -EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal, EVP_DigestSign \- EVP signing functions +EVP_DigestSignInit_ex, EVP_DigestSignInit, EVP_DigestSignUpdate, +EVP_DigestSignFinal, EVP_DigestSign \- EVP signing functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/evp.h> \& +\& int EVP_DigestSignInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, +\& const char *mdname, OSSL_LIB_CTX *libctx, +\& const char *props, EVP_PKEY *pkey, +\& const OSSL_PARAM params[]); \& int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, \& const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); \& int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); @@ -157,22 +160,45 @@ EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal, EVP_DigestSign \- .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \s-1EVP\s0 signature routines are a high-level interface to digital signatures. +Input data is digested first before the signing takes place. +.PP +\&\fBEVP_DigestSignInit_ex()\fR sets up signing context \fIctx\fR to use a digest +with the name \fImdname\fR and private key \fIpkey\fR. The name of the digest to be +used is passed to the provider of the signature algorithm in use. How that +provider interprets the digest name is provider specific. The provider may +implement that digest directly itself or it may (optionally) choose to fetch it +(which could result in a digest from a different provider being selected). If the +provider supports fetching the digest then it may use the \fIprops\fR argument for +the properties to be used during the fetch. Finally, the passed parameters +\&\fIparams\fR, if not \s-1NULL,\s0 are set on the context before returning. +.PP +The \fIpkey\fR algorithm is used to fetch a \fB\s-1EVP_SIGNATURE\s0\fR method implicitly, to +be used for the actual signing. See \*(L"Implicit fetch\*(R" in \fBprovider\fR\|(7) for +more information about implicit fetches. +.PP +The OpenSSL default and legacy providers support fetching digests and can fetch +those digests from any available provider. The OpenSSL \s-1FIPS\s0 provider also +supports fetching digests but will only fetch digests that are themselves +implemented inside the \s-1FIPS\s0 provider. .PP -\&\fBEVP_DigestSignInit()\fR sets up signing context \fBctx\fR to use digest \fBtype\fR from -\&\s-1ENGINE\s0 \fBe\fR and private key \fBpkey\fR. \fBctx\fR must be created with -\&\fBEVP_MD_CTX_new()\fR before calling this function. If \fBpctx\fR is not \s-1NULL,\s0 the -\&\s-1EVP_PKEY_CTX\s0 of the signing operation will be written to \fB*pctx\fR: this can -be used to set alternative signing options. Note that any existing value in -\&\fB*pctx\fR is overwritten. The \s-1EVP_PKEY_CTX\s0 value returned must not be freed -directly by the application if \fBctx\fR is not assigned an \s-1EVP_PKEY_CTX\s0 value before -being passed to \fBEVP_DigestSignInit()\fR (which means the \s-1EVP_PKEY_CTX\s0 is created -inside \fBEVP_DigestSignInit()\fR and it will be freed automatically when the -\&\s-1EVP_MD_CTX\s0 is freed). +\&\fIctx\fR must be created with \fBEVP_MD_CTX_new()\fR before calling this function. If +\&\fIpctx\fR is not \s-1NULL,\s0 the \s-1EVP_PKEY_CTX\s0 of the signing operation will be written +to \fI*pctx\fR: this can be used to set alternative signing options. Note that any +existing value in \fI*pctx\fR is overwritten. The \s-1EVP_PKEY_CTX\s0 value returned must +not be freed directly by the application if \fIctx\fR is not assigned an +\&\s-1EVP_PKEY_CTX\s0 value before being passed to \fBEVP_DigestSignInit_ex()\fR +(which means the \s-1EVP_PKEY_CTX\s0 is created inside \fBEVP_DigestSignInit_ex()\fR +and it will be freed automatically when the \s-1EVP_MD_CTX\s0 is freed). If the +\&\s-1EVP_PKEY_CTX\s0 to be used is created by EVP_DigestSignInit_ex then it +will use the \fB\s-1OSSL_LIB_CTX\s0\fR specified in \fIlibctx\fR and the property query string +specified in \fIprops\fR. .PP -The digest \fBtype\fR may be \s-1NULL\s0 if the signing algorithm supports it. +The digest \fImdname\fR may be \s-1NULL\s0 if the signing algorithm supports it. The +\&\fIprops\fR argument can always be \s-1NULL.\s0 .PP -No \fB\s-1EVP_PKEY_CTX\s0\fR will be created by \fBEVP_DigestSignInit()\fR if the passed \fBctx\fR -has already been assigned one via \fBEVP_MD_CTX_set_pkey_ctx\fR\|(3). See also \s-1\fBSM2\s0\fR\|(7). +No \fB\s-1EVP_PKEY_CTX\s0\fR will be created by \fBEVP_DigestSignInit_ex()\fR if the +passed \fIctx\fR has already been assigned one via \fBEVP_MD_CTX_set_pkey_ctx\fR\|(3). +See also \s-1\fBSM2\s0\fR\|(7). .PP Only \s-1EVP_PKEY\s0 types that support signing can be used with these functions. This includes \s-1MAC\s0 algorithms where the \s-1MAC\s0 generation is considered as a form of @@ -188,7 +214,7 @@ Supports \s-1SHA1, SHA224, SHA256, SHA384\s0 and \s-1SHA512\s0 Supports \s-1SHA1, SHA224, SHA256, SHA384, SHA512\s0 and \s-1SM3\s0 .IP "\s-1RSA\s0 with no padding" 4 .IX Item "RSA with no padding" -Supports no digests (the digest \fBtype\fR must be \s-1NULL\s0) +Supports no digests (the digest \fItype\fR must be \s-1NULL\s0) .IP "\s-1RSA\s0 with X931 padding" 4 .IX Item "RSA with X931 padding" Supports \s-1SHA1, SHA256, SHA384\s0 and \s-1SHA512\s0 @@ -198,7 +224,7 @@ Support \s-1SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2, SHA3\-224, SHA3\-256, SHA3\-384, SHA3\-512\s0 .IP "Ed25519 and Ed448" 4 .IX Item "Ed25519 and Ed448" -Support no digests (the digest \fBtype\fR must be \s-1NULL\s0) +Support no digests (the digest \fItype\fR must be \s-1NULL\s0) .IP "\s-1HMAC\s0" 4 .IX Item "HMAC" Supports any digest @@ -208,21 +234,30 @@ Will ignore any digest provided. .PP If RSA-PSS is used and restrictions apply then the digest must match. .PP -\&\fBEVP_DigestSignUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the -signature context \fBctx\fR. This function can be called several times on the -same \fBctx\fR to include additional data. This function is currently implemented -using a macro. +\&\fBEVP_DigestSignInit()\fR works in the same way as \fBEVP_DigestSignInit_ex()\fR +except that the \fImdname\fR parameter will be inferred from the supplied +digest \fItype\fR, and \fIprops\fR will be \s-1NULL.\s0 Where supplied the \s-1ENGINE\s0 \fIe\fR will +be used for the signing and digest algorithm implementations. \fIe\fR may be \s-1NULL.\s0 .PP -\&\fBEVP_DigestSignFinal()\fR signs the data in \fBctx\fR and places the signature in \fBsig\fR. -If \fBsig\fR is \fB\s-1NULL\s0\fR then the maximum size of the output buffer is written to -the \fBsiglen\fR parameter. If \fBsig\fR is not \fB\s-1NULL\s0\fR then before the call the -\&\fBsiglen\fR parameter should contain the length of the \fBsig\fR buffer. If the -call is successful the signature is written to \fBsig\fR and the amount of data -written to \fBsiglen\fR. +\&\fBEVP_DigestSignUpdate()\fR hashes \fIcnt\fR bytes of data at \fId\fR into the +signature context \fIctx\fR. This function can be called several times on the +same \fIctx\fR to include additional data. .PP -\&\fBEVP_DigestSign()\fR signs \fBtbslen\fR bytes of data at \fBtbs\fR and places the -signature in \fBsig\fR and its length in \fBsiglen\fR in a similar way to -\&\fBEVP_DigestSignFinal()\fR. +Unless \fIsig\fR is \s-1NULL\s0 \fBEVP_DigestSignFinal()\fR signs the data in \fIctx\fR +and places the signature in \fIsig\fR. +Otherwise the maximum necessary size of the output buffer is written to +the \fIsiglen\fR parameter. If \fIsig\fR is not \s-1NULL\s0 then before the call the +\&\fIsiglen\fR parameter should contain the length of the \fIsig\fR buffer. If the +call is successful the signature is written to \fIsig\fR and the amount of data +written to \fIsiglen\fR. +.PP +\&\fBEVP_DigestSign()\fR signs \fItbslen\fR bytes of data at \fItbs\fR and places the +signature in \fIsig\fR and its length in \fIsiglen\fR in a similar way to +\&\fBEVP_DigestSignFinal()\fR. In the event of a failure \fBEVP_DigestSign()\fR cannot be +called again without reinitialising the \s-1EVP_MD_CTX.\s0 If \fIsig\fR is \s-1NULL\s0 before the +call then \fIsiglen\fR will be populated with the required size for the \fIsig\fR +buffer. If \fIsig\fR is non-NULL before the call then \fIsiglen\fR should contain the +length of the \fIsig\fR buffer. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR, \fBEVP_DigestSignFinal()\fR and @@ -253,13 +288,18 @@ The call to \fBEVP_DigestSignFinal()\fR internally finalizes a copy of the diges context. This means that calls to \fBEVP_DigestSignUpdate()\fR and \&\fBEVP_DigestSignFinal()\fR can be called later to digest and sign additional data. .PP -Since only a copy of the digest context is ever finalized, the context must -be cleaned up after use by calling \fBEVP_MD_CTX_free()\fR or a memory leak -will occur. +\&\fBEVP_DigestSignInit()\fR and \fBEVP_DigestSignInit_ex()\fR functions can be called +multiple times on a context and the parameters set by previous calls should be +preserved if the \fIpkey\fR parameter is \s-1NULL.\s0 The call then just resets the state +of the \fIctx\fR. +.PP +Ignoring failure returns of \fBEVP_DigestSignInit()\fR and \fBEVP_DigestSignInit_ex()\fR +functions can lead to subsequent undefined behavior when calling +\&\fBEVP_DigestSignUpdate()\fR, \fBEVP_DigestSignFinal()\fR, or \fBEVP_DigestSign()\fR. .PP -The use of \fBEVP_PKEY_size()\fR with these functions is discouraged because some +The use of \fBEVP_PKEY_get_size()\fR with these functions is discouraged because some signature operations may have a signature length which depends on the -parameters set. As a result \fBEVP_PKEY_size()\fR would have to return a value +parameters set. As a result \fBEVP_PKEY_get_size()\fR would have to return a value which indicates the maximum possible signature for any set of parameters. .SH "SEE ALSO" .IX Header "SEE ALSO" @@ -267,17 +307,21 @@ which indicates the maximum possible signature for any set of parameters. \&\fBEVP_DigestInit\fR\|(3), \&\fBevp\fR\|(7), \s-1\fBHMAC\s0\fR\|(3), \s-1\fBMD2\s0\fR\|(3), \&\s-1\fBMD5\s0\fR\|(3), \s-1\fBMDC2\s0\fR\|(3), \s-1\fBRIPEMD160\s0\fR\|(3), -\&\s-1\fBSHA1\s0\fR\|(3), \fBdgst\fR\|(1), +\&\s-1\fBSHA1\s0\fR\|(3), \fBopenssl\-dgst\fR\|(1), \&\s-1\fBRAND\s0\fR\|(7) .SH "HISTORY" .IX Header "HISTORY" \&\fBEVP_DigestSignInit()\fR, \fBEVP_DigestSignUpdate()\fR and \fBEVP_DigestSignFinal()\fR were added in OpenSSL 1.0.0. +.PP +\&\fBEVP_DigestSignInit_ex()\fR was added in OpenSSL 3.0. +.PP +\&\fBEVP_DigestSignUpdate()\fR was converted from a macro to a function in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2006\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2006\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). 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 <https://www.openssl.org/source/license.html>. |