1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5238384SjkimEVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions 6238384Sjkim 7238384Sjkim=head1 SYNOPSIS 8238384Sjkim 9238384Sjkim #include <openssl/evp.h> 10238384Sjkim 11238384Sjkim int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, 12238384Sjkim const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); 13312826Sjkim int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); 14238384Sjkim int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); 15238384Sjkim 16238384Sjkim=head1 DESCRIPTION 17238384Sjkim 18238384SjkimThe EVP signature routines are a high level interface to digital signatures. 19238384Sjkim 20238384SjkimEVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from 21238384SjkimENGINE B<impl> and private key B<pkey>. B<ctx> must be initialized with 22340704SjkimEVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL, the 23238384SjkimEVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can 24340704Sjkimbe used to set alternative signing options. Note that any existing value in 25340704SjkimB<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed 26340704Sjkimdirectly by the application (it will be freed automatically when the EVP_MD_CTX 27340704Sjkimis freed). The digest B<type> may be NULL if the signing algorithm supports it. 28238384Sjkim 29238384SjkimEVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the 30238384Sjkimsignature context B<ctx>. This function can be called several times on the 31238384Sjkimsame B<ctx> to include additional data. This function is currently implemented 32238384Sjkimusig a macro. 33238384Sjkim 34238384SjkimEVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>. 35238384SjkimIf B<sig> is B<NULL> then the maximum size of the output buffer is written to 36238384Sjkimthe B<siglen> parameter. If B<sig> is not B<NULL> then before the call the 37238384SjkimB<siglen> parameter should contain the length of the B<sig> buffer, if the 38238384Sjkimcall is successful the signature is written to B<sig> and the amount of data 39238384Sjkimwritten to B<siglen>. 40238384Sjkim 41238384Sjkim=head1 RETURN VALUES 42238384Sjkim 43238384SjkimEVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return 44238384Sjkim1 for success and 0 or a negative value for failure. In particular a return 45238384Sjkimvalue of -2 indicates the operation is not supported by the public key 46238384Sjkimalgorithm. 47238384Sjkim 48238384SjkimThe error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. 49238384Sjkim 50238384Sjkim=head1 NOTES 51238384Sjkim 52238384SjkimThe B<EVP> interface to digital signatures should almost always be used in 53238384Sjkimpreference to the low level interfaces. This is because the code then becomes 54238384Sjkimtransparent to the algorithm used and much more flexible. 55238384Sjkim 56238384SjkimIn previous versions of OpenSSL there was a link between message digest types 57238384Sjkimand public key algorithms. This meant that "clone" digests such as EVP_dss1() 58238384Sjkimneeded to be used to sign using SHA1 and DSA. This is no longer necessary and 59238384Sjkimthe use of clone digest is now discouraged. 60238384Sjkim 61238384SjkimFor some key types and parameters the random number generator must be seeded 62238384Sjkimor the operation will fail. 63238384Sjkim 64238384SjkimThe call to EVP_DigestSignFinal() internally finalizes a copy of the digest 65238384Sjkimcontext. This means that calls to EVP_DigestSignUpdate() and 66238384SjkimEVP_DigestSignFinal() can be called later to digest and sign additional data. 67238384Sjkim 68238384SjkimSince only a copy of the digest context is ever finalized the context must 69238384Sjkimbe cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak 70238384Sjkimwill occur. 71238384Sjkim 72238384SjkimThe use of EVP_PKEY_size() with these functions is discouraged because some 73238384Sjkimsignature operations may have a signature length which depends on the 74238384Sjkimparameters set. As a result EVP_PKEY_size() would have to return a value 75238384Sjkimwhich indicates the maximum possible signature for any set of parameters. 76238384Sjkim 77238384Sjkim=head1 SEE ALSO 78238384Sjkim 79238384SjkimL<EVP_DigestVerifyInit(3)|EVP_DigestVerifyInit(3)>, 80238384SjkimL<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, 81238384SjkimL<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, 82238384SjkimL<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, 83238384SjkimL<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> 84238384Sjkim 85238384Sjkim=head1 HISTORY 86238384Sjkim 87238384SjkimEVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() 88238384Sjkimwere first added to OpenSSL 1.0.0. 89238384Sjkim 90238384Sjkim=cut 91