From a0b6c1ffd0261152c523c5c000e9c025b39fd630 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Mon, 23 Sep 2019 16:43:08 +0100 Subject: [PATCH] Update documentation Add documentation for EVP_DigestSignInit_ex() and EVP_DigestVerifyInit_ex(), and add an appropriate CHANGES entry. Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/10013) --- CHANGES | 6 ++ doc/man3/EVP_DigestSignInit.pod | 73 ++++++++++++++------ doc/man3/EVP_DigestVerifyInit.pod | 106 +++++++++++++++++++++++++----- 3 files changed, 149 insertions(+), 36 deletions(-) diff --git a/CHANGES b/CHANGES index a4672fa21a..db1dc416e8 100644 --- a/CHANGES +++ b/CHANGES @@ -9,6 +9,12 @@ Changes between 1.1.1 and 3.0.0 [xx XXX xxxx] + *) Introduced the new functions EVP_DigestSignInit_ex() and + EVP_DigestVerifyInit_ex(). The macros EVP_DigestSignUpdate() and + EVP_DigestVerifyUpdate() have been converted to functions. See the man + pages for further details. + [Matt Caswell] + *) s390x assembly pack: add hardware-support for P-256, P-384, P-521, X25519, X448, Ed25519 and Ed448. [Patrick Steuer] diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod index 0f9c952303..f730ba7b03 100644 --- a/doc/man3/EVP_DigestSignInit.pod +++ b/doc/man3/EVP_DigestSignInit.pod @@ -2,13 +2,16 @@ =head1 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 =head1 SYNOPSIS #include + int EVP_DigestSignInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, + const char *mdname, const char *props, + EVP_PKEY *pkey, EVP_SIGNATURE *signature); 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); @@ -21,22 +24,44 @@ EVP_DigestSign - EVP signing functions =head1 DESCRIPTION The EVP signature routines are a high level interface to digital signatures. - -EVP_DigestSignInit() sets up signing context B to use digest B from -ENGINE B and private 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 signing operation will be written to B<*pctx>: this can -be used to set alternative signing 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_DigestSignInit() (which means the EVP_PKEY_CTX is created -inside EVP_DigestSignInit() and it will be freed automatically when the -EVP_MD_CTX is freed). - -The digest B may be NULL if the signing algorithm supports it. - -No B will be created by EVP_DigestSignInit() if the passed B -has already been assigned one via L. See also L. +Input data is digested first before the signing takes place. + +EVP_DigestSignInit_ex() sets up signing context B to use a digest with the +name B and private key B. The signature algorithm B +will be used for the actual signing which must be compatible with the private +key. 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. + +The B parameter may be NULL in which case a suitable signature +algorithm implementation will be implicitly fetched based on the type of key in +use. See L for further information about providers and fetching +algorithms. + +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 signing operation will be written +to B<*pctx>: this can be used to set alternative signing 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_DigestSignInit_ex() (which means +the EVP_PKEY_CTX is created inside EVP_DigestSignInit_ex() and it will be freed +automatically when the EVP_MD_CTX is freed). + +The digest B may be NULL if the signing algorithm supports it. The +B argument can always be NULL. + +No B will be created by EVP_DigestSignInit_ex() if the passed +B has already been assigned one via L. See also +L. Only EVP_PKEY types that support signing can be used with these functions. This includes MAC algorithms where the MAC generation is considered as a form of @@ -84,10 +109,14 @@ Will ignore any digest provided. If RSA-PSS is used and restrictions apply then the digest must match. +EVP_DigestSignInit() works in the same way as EVP_DigestSignInit_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 +signing and digest algorithm implementations. B may be NULL. + EVP_DigestSignUpdate() hashes B bytes of data at B into the signature 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_DigestSignFinal() signs the data in B and places the signature in B. If B is B then the maximum size of the output buffer is written to @@ -156,6 +185,10 @@ L EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() were added in OpenSSL 1.0.0. +EVP_DigestSignInit_ex() was added in OpenSSL 3.0. + +EVP_DigestSignUpdate() was converted from a macro to a function in OpenSSL 3.0. + =head1 COPYRIGHT Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod index 97bb773722..480c6cb72a 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, EVP_SIGNATURE *signature); 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,91 @@ 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 signature algorithm +B will be used for the actual signature verification which must be +compatible with the public key. 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 B parameter may be NULL in which case a suitable signature +algorithm implementation will be implicitly fetched based on the type of key in +use. See L for further information about providers and fetching +algorithms. + +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). + +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. @@ -102,6 +171,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. -- 2.25.1