EVP_SignInit.pod revision 238405
159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 559191SkrisEVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions 659191Skris 759191Skris=head1 SYNOPSIS 859191Skris 959191Skris #include <openssl/evp.h> 1059191Skris 11109998Smarkm int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); 12109998Smarkm int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); 1359191Skris int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey); 1459191Skris 15109998Smarkm void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); 16109998Smarkm 1759191Skris int EVP_PKEY_size(EVP_PKEY *pkey); 1859191Skris 1959191Skris=head1 DESCRIPTION 2059191Skris 2159191SkrisThe EVP signature routines are a high level interface to digital 2259191Skrissignatures. 2359191Skris 24109998SmarkmEVP_SignInit_ex() sets up signing context B<ctx> to use digest 25109998SmarkmB<type> from ENGINE B<impl>. B<ctx> must be initialized with 26109998SmarkmEVP_MD_CTX_init() before calling this function. 2759191Skris 2859191SkrisEVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the 2968651Skrissignature context B<ctx>. This function can be called several times on the 3059191Skrissame B<ctx> to include additional data. 3159191Skris 32160814SsimonEVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and 33160814Ssimonplaces the signature in B<sig>. The number of bytes of data written (i.e. the 34160814Ssimonlength of the signature) will be written to the integer at B<s>, at most 35160814SsimonEVP_PKEY_size(pkey) bytes will be written. 3659191Skris 37109998SmarkmEVP_SignInit() initializes a signing context B<ctx> to use the default 38109998Smarkmimplementation of digest B<type>. 39109998Smarkm 4059191SkrisEVP_PKEY_size() returns the maximum size of a signature in bytes. The actual 4159191Skrissignature returned by EVP_SignFinal() may be smaller. 4259191Skris 4359191Skris=head1 RETURN VALUES 4459191Skris 45109998SmarkmEVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1 46109998Smarkmfor success and 0 for failure. 4759191Skris 4859191SkrisEVP_PKEY_size() returns the maximum size of a signature in bytes. 4959191Skris 5059191SkrisThe error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 5159191Skris 5259191Skris=head1 NOTES 5359191Skris 5459191SkrisThe B<EVP> interface to digital signatures should almost always be used in 5559191Skrispreference to the low level interfaces. This is because the code then becomes 5659191Skristransparent to the algorithm used and much more flexible. 5759191Skris 5859191SkrisDue to the link between message digests and public key algorithms the correct 5959191Skrisdigest algorithm must be used with the correct public key type. A list of 6059191Skrisalgorithms and associated public key algorithms appears in 6159191SkrisL<EVP_DigestInit(3)|EVP_DigestInit(3)>. 6259191Skris 6359191SkrisWhen signing with DSA private keys the random number generator must be seeded 6459191Skrisor the operation will fail. The random number generator does not need to be 6559191Skrisseeded for RSA signatures. 6659191Skris 67109998SmarkmThe call to EVP_SignFinal() internally finalizes a copy of the digest context. 68109998SmarkmThis means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called 69109998Smarkmlater to digest and sign additional data. 70109998Smarkm 71109998SmarkmSince only a copy of the digest context is ever finalized the context must 72109998Smarkmbe cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak 73109998Smarkmwill occur. 74109998Smarkm 7559191Skris=head1 BUGS 7659191Skris 77109998SmarkmOlder versions of this documentation wrongly stated that calls to 78109998SmarkmEVP_SignUpdate() could not be made after calling EVP_SignFinal(). 7959191Skris 80238405SjkimSince the private key is passed in the call to EVP_SignFinal() any error 81238405Sjkimrelating to the private key (for example an unsuitable key and digest 82238405Sjkimcombination) will not be indicated until after potentially large amounts of 83238405Sjkimdata have been passed through EVP_SignUpdate(). 84238405Sjkim 85238405SjkimIt is not possible to change the signing parameters using these function. 86238405Sjkim 87238405SjkimThe previous two bugs are fixed in the newer EVP_SignDigest*() function. 88238405Sjkim 8959191Skris=head1 SEE ALSO 9059191Skris 9159191SkrisL<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, 9259191SkrisL<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, 9359191SkrisL<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, 9459191SkrisL<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, 95100936SnectarL<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> 9659191Skris 9759191Skris=head1 HISTORY 9859191Skris 9959191SkrisEVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are 10059191Skrisavailable in all versions of SSLeay and OpenSSL. 10159191Skris 102109998SmarkmEVP_SignInit_ex() was added in OpenSSL 0.9.7. 103109998Smarkm 10459191Skris=cut 105