X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FEVP_DigestSignInit.pod;h=d0c13bbc17732aba6de7b93c1a9fdb2b72893e90;hp=fc19c015dd86cf9a0f145cfe97ad41a77a11eb94;hb=6d4e6009d27712a405e1e3a4c33fb8a8566f134a;hpb=be93b0e8638287bfaa8239ef64ee1c4a7cd818cb diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod index fc19c015dd..d0c13bbc17 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, OPENSSL_CTX *libctx); 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,18 +24,48 @@ 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. The digest B may be NULL if -the signing algorithm supports it. +Input data is digested first before the signing takes place. + +EVP_DigestSignInit_ex() sets up signing context I to use a digest with the +name I and private key I. 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 I argument for +the properties to be used during the fetch. + +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. + +I must be created with EVP_MD_CTX_new() before calling this function. If +I is not NULL, the EVP_PKEY_CTX of the signing operation will be written +to I<*pctx>: this can be used to set alternative signing options. Note that any +existing value in I<*pctx> is overwritten. The EVP_PKEY_CTX value returned must +not be freed directly by the application if I 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). If the EVP_PKEY_CTX to be used is +created by EVP_DigestSignInit_ex then it will use the B specified +in I and the property query string specified in I. + +The digest I may be NULL if the signing algorithm supports it. The +I argument can always be NULL. + +No B will be created by EVP_DigestSignInit_ex() if the passed +I 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 -"signing." Built-in EVP_PKEY types supported by these functions are CMAC, -Poly1305, DSA, HMAC, RSA, SipHash, Ed25519 and Ed448. +"signing". Built-in EVP_PKEY types supported by these functions are CMAC, +Poly1305, DSA, ECDSA, HMAC, RSA, SipHash, Ed25519 and Ed448. Not all digests can be used for all key types. The following combinations apply. @@ -48,7 +81,7 @@ Supports SHA1, SHA224, SHA256, SHA384, SHA512 and SM3 =item RSA with no padding -Supports no digests (the digest B must be NULL) +Supports no digests (the digest I must be NULL) =item RSA with X931 padding @@ -61,7 +94,7 @@ SHA3-224, SHA3-256, SHA3-384, SHA3-512 =item Ed25519 and Ed448 -Support no digests (the digest B must be NULL) +Support no digests (the digest I must be NULL) =item HMAC @@ -75,28 +108,30 @@ Will ignore any digest provided. If RSA-PSS is used and restrictions apply then the digest must match. -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. +EVP_DigestSignInit() works in the same way as EVP_DigestSignInit_ex() except +that the I parameter will be inferred from the supplied digest I, +and I will be NULL. Where supplied the ENGINE I will be used for the +signing and digest algorithm implementations. I may be NULL. + +EVP_DigestSignUpdate() hashes I bytes of data at I into the +signature context I. This function can be called several times on the +same I to include additional data. -EVP_DigestSignFinal() signs the data in B places the signature in B. -If B is B then the maximum size of the output buffer is written to -the B parameter. If B is not B then before the call the -B parameter should contain the length of the B buffer, if the -call is successful the signature is written to B and the amount of data -written to B. +EVP_DigestSignFinal() signs the data in I and places the signature in I. +If I is NULL then the maximum size of the output buffer is written to +the I parameter. If I is not NULL then before the call the +I parameter should contain the length of the I buffer. If the +call is successful the signature is written to I and the amount of data +written to I. -EVP_DigestSign() signs B bytes of data at B and places the -signature in B and its length in B in a similar way to +EVP_DigestSign() signs I bytes of data at I and places the +signature in I and its length in I in a similar way to EVP_DigestSignFinal(). =head1 RETURN VALUES -EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignaFinal() and -EVP_DigestSign() return 1 for success and 0 or a negative value for failure. In -particular a return value of -2 indicates the operation is not supported by the -public key algorithm. +EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignFinal() and +EVP_DigestSign() return 1 for success and 0 for failure. The error codes can be obtained from L. @@ -116,14 +151,15 @@ and public key algorithms. This meant that "clone" digests such as EVP_dss1() needed to be used to sign using SHA1 and DSA. This is no longer necessary and the use of clone digest is now discouraged. -For some key types and parameters the random number generator must be seeded -or the operation will fail. +For some key types and parameters the random number generator must be seeded. +If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to +external circumstances (see L), the operation will fail. The call to EVP_DigestSignFinal() internally finalizes a copy of the digest context. This means that calls to EVP_DigestSignUpdate() and EVP_DigestSignFinal() can be called later to digest and sign additional data. -Since only a copy of the digest context is ever finalized the context must +Since only a copy of the digest context is ever finalized, the context must be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak will occur. @@ -138,18 +174,23 @@ L, L, L, L, L, L, L, L, -L, L +L, L, +L =head1 HISTORY EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() -were first added to OpenSSL 1.0.0. +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. -Licensed under the OpenSSL license (the "License"). 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 LICENSE in the source distribution or at L.