X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FEVP_DigestVerifyInit.pod;h=9b5de646b0c6737e9995090c49fef7c56014151d;hp=97bb773722625be5ecdba4b49b2cee9e6b465f0e;hb=a45694a3567ce8de754cffa7b450c22578ebdd6c;hpb=c2969ff6e70b10f71fbd97c1d0b0cffc92bd69df;ds=sidebyside diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod index 97bb773722..9b5de646b0 100644 --- a/doc/man3/EVP_DigestVerifyInit.pod +++ b/doc/man3/EVP_DigestVerifyInit.pod @@ -2,13 +2,16 @@ =head1 NAME -EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal, -EVP_DigestVerify - EVP signature verification functions +EVP_DigestVerifyInit_ex, EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, +EVP_DigestVerifyFinal, EVP_DigestVerify - EVP signature verification functions =head1 SYNOPSIS #include + int EVP_DigestVerifyInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, + const char *mdname, const char *props, + EVP_PKEY *pkey, OPENSSL_CTX *libctx); int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); @@ -20,25 +23,90 @@ EVP_DigestVerify - EVP signature verification functions =head1 DESCRIPTION The EVP signature routines are a high level interface to digital signatures. +Input data is digested first before the signature verification takes place. -EVP_DigestVerifyInit() sets up verification context B to use digest -B from ENGINE B and public key B. B must be created -with EVP_MD_CTX_new() before calling this function. If B is not NULL, the -EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this -can be used to set alternative verification options. Note that any existing -value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed -directly by the application if B is not assigned an EVP_PKEY_CTX value before -being passed to EVP_DigestVerifyInit() (which means the EVP_PKEY_CTX is created -inside EVP_DigestVerifyInit() and it will be freed automatically when the -EVP_MD_CTX is freed). +EVP_DigestVerifyInit_ex() sets up verification context B to use a digest +with the name B and public key B. 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 B argument +for the properties to be used during the fetch. -No B will be created by EVP_DigestSignInit() if the passed B -has already been assigned one via L. See also L. +The I algorithm is used to fetch a B method implicitly, to +be used for the actual signing. See L for +more information about implict fetches. + +The OpenSSL default and legacy providers support fetching digests and can fetch +those digests from any available provider. The OpenSSL fips provider also +supports fetching digests but will only fetch digests that are themselves +implemented inside the fips provider. + +B must be created with EVP_MD_CTX_new() before calling this function. If +B is not NULL, the EVP_PKEY_CTX of the verification operation will be +written to B<*pctx>: this can be used to set alternative verification options. +Note that any existing value in B<*pctx> is overwritten. The EVP_PKEY_CTX value +returned must not be freed directly by the application if B is not assigned +an EVP_PKEY_CTX value before being passed to EVP_DigestVerifyInit_ex() (which +means the EVP_PKEY_CTX is created inside EVP_DigestVerifyInit_ex() and it will +be freed automatically when the EVP_MD_CTX is freed). If the EVP_PKEY_CTX to be +used is created by EVP_DigestVerifyInit_ex then it will use the B +specified in I and the property query string specified in I. + +No B will be created by EVP_DigestSignInit_ex() if the passed +B has already been assigned one via L. See also +L. + +Not all digests can be used for all key types. The following combinations apply. + +=over 4 + +=item DSA + +Supports SHA1, SHA224, SHA256, SHA384 and SHA512 + +=item ECDSA + +Supports SHA1, SHA224, SHA256, SHA384, SHA512 and SM3 + +=item RSA with no padding + +Supports no digests (the digest B must be NULL) + +=item RSA with X931 padding + +Supports SHA1, SHA256, SHA384 and SHA512 + +=item All other RSA padding types + +Support SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2, +SHA3-224, SHA3-256, SHA3-384, SHA3-512 + +=item Ed25519 and Ed448 + +Support no digests (the digest B must be NULL) + +=item HMAC + +Supports any digest + +=item CMAC, Poly1305 and SipHash + +Will ignore any digest provided. + +=back + +If RSA-PSS is used and restrictions apply then the digest must match. + +EVP_DigestVerifyInit() works in the same way as EVP_DigestVerifyInit_ex() except +that the B parameter will be inferred from the supplied digest B, +and B will be NULL. Where supplied the ENGINE B will be used for the +signature verification and digest algorithm implementations. B may be NULL. EVP_DigestVerifyUpdate() hashes B bytes of data at B into the verification context B. This function can be called several times on the -same B to include additional data. This function is currently implemented -using a macro. +same B to include additional data. EVP_DigestVerifyFinal() verifies the data in B against the signature in B of length B. @@ -94,7 +162,7 @@ L, L, L, L, L, L, L, L, -L, L, +L, L, L =head1 HISTORY @@ -102,6 +170,11 @@ L EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() were added in OpenSSL 1.0.0. +EVP_DigestVerifyInit_ex() was added in OpenSSL 3.0. + +EVP_DigestVerifyUpdate() was converted from a macro to a function in OpenSSL +3.0. + =head1 COPYRIGHT Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.