159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 5291721SjkimEVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal - EVP signing 6291721Sjkimfunctions 759191Skris 859191Skris=head1 SYNOPSIS 959191Skris 1059191Skris #include <openssl/evp.h> 1159191Skris 12109998Smarkm int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); 13109998Smarkm int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); 1459191Skris int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey); 1559191Skris 16109998Smarkm void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); 17109998Smarkm 1859191Skris int EVP_PKEY_size(EVP_PKEY *pkey); 1959191Skris 2059191Skris=head1 DESCRIPTION 2159191Skris 2259191SkrisThe EVP signature routines are a high level interface to digital 2359191Skrissignatures. 2459191Skris 25109998SmarkmEVP_SignInit_ex() sets up signing context B<ctx> to use digest 26109998SmarkmB<type> from ENGINE B<impl>. B<ctx> must be initialized with 27109998SmarkmEVP_MD_CTX_init() before calling this function. 2859191Skris 2959191SkrisEVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the 3068651Skrissignature context B<ctx>. This function can be called several times on the 3159191Skrissame B<ctx> to include additional data. 3259191Skris 33160814SsimonEVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and 34269686Sjkimplaces the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey) 35269686Sjkimbytes in size. B<s> is an OUT paramter, and not used as an IN parameter. 36269686SjkimThe number of bytes of data written (i.e. the length of the signature) 37269686Sjkimwill be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes 38269686Sjkimwill be written. 3959191Skris 40109998SmarkmEVP_SignInit() initializes a signing context B<ctx> to use the default 41109998Smarkmimplementation of digest B<type>. 42109998Smarkm 4359191SkrisEVP_PKEY_size() returns the maximum size of a signature in bytes. The actual 4459191Skrissignature returned by EVP_SignFinal() may be smaller. 4559191Skris 4659191Skris=head1 RETURN VALUES 4759191Skris 48109998SmarkmEVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1 49109998Smarkmfor success and 0 for failure. 5059191Skris 5159191SkrisEVP_PKEY_size() returns the maximum size of a signature in bytes. 5259191Skris 5359191SkrisThe error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 5459191Skris 5559191Skris=head1 NOTES 5659191Skris 5759191SkrisThe B<EVP> interface to digital signatures should almost always be used in 5859191Skrispreference to the low level interfaces. This is because the code then becomes 5959191Skristransparent to the algorithm used and much more flexible. 6059191Skris 6159191SkrisDue to the link between message digests and public key algorithms the correct 6259191Skrisdigest algorithm must be used with the correct public key type. A list of 6359191Skrisalgorithms and associated public key algorithms appears in 6459191SkrisL<EVP_DigestInit(3)|EVP_DigestInit(3)>. 6559191Skris 6659191SkrisWhen signing with DSA private keys the random number generator must be seeded 6759191Skrisor the operation will fail. The random number generator does not need to be 6859191Skrisseeded for RSA signatures. 6959191Skris 70109998SmarkmThe call to EVP_SignFinal() internally finalizes a copy of the digest context. 71109998SmarkmThis means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called 72109998Smarkmlater to digest and sign additional data. 73109998Smarkm 74109998SmarkmSince only a copy of the digest context is ever finalized the context must 75109998Smarkmbe cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak 76109998Smarkmwill occur. 77109998Smarkm 7859191Skris=head1 BUGS 7959191Skris 80109998SmarkmOlder versions of this documentation wrongly stated that calls to 81109998SmarkmEVP_SignUpdate() could not be made after calling EVP_SignFinal(). 8259191Skris 83238405SjkimSince the private key is passed in the call to EVP_SignFinal() any error 84238405Sjkimrelating to the private key (for example an unsuitable key and digest 85238405Sjkimcombination) will not be indicated until after potentially large amounts of 86238405Sjkimdata have been passed through EVP_SignUpdate(). 87238405Sjkim 88238405SjkimIt is not possible to change the signing parameters using these function. 89238405Sjkim 90238405SjkimThe previous two bugs are fixed in the newer EVP_SignDigest*() function. 91238405Sjkim 9259191Skris=head1 SEE ALSO 9359191Skris 9459191SkrisL<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, 9559191SkrisL<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, 9659191SkrisL<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, 9759191SkrisL<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, 98100936SnectarL<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> 9959191Skris 10059191Skris=head1 HISTORY 10159191Skris 10259191SkrisEVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are 10359191Skrisavailable in all versions of SSLeay and OpenSSL. 10459191Skris 105109998SmarkmEVP_SignInit_ex() was added in OpenSSL 0.9.7. 106109998Smarkm 10759191Skris=cut 108