EVP_DigestSignInit.pod revision 312826 
1=pod
2
3=head1 NAME
4
5EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing functions
6
7=head1 SYNOPSIS
8
9 #include <openssl/evp.h>
10
11 int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
12			const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
13 int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
14 int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen);
15
16=head1 DESCRIPTION
17
18The EVP signature routines are a high level interface to digital signatures.
19
20EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from
21ENGINE B<impl> and private key B<pkey>. B<ctx> must be initialized with
22EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the
23EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can
24be used to set alternative signing options.
25
26EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
27signature context B<ctx>. This function can be called several times on the
28same B<ctx> to include additional data. This function is currently implemented
29usig a macro.
30
31EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>.
32If B<sig> is B<NULL> then the maximum size of the output buffer is written to
33the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the
34B<siglen> parameter should contain the length of the B<sig> buffer, if the
35call is successful the signature is written to B<sig> and the amount of data
36written to B<siglen>.
37
38=head1 RETURN VALUES
39
40EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return
411 for success and 0 or a negative value for failure. In particular a return
42value of -2 indicates the operation is not supported by the public key
43algorithm.
44
45The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
46
47=head1 NOTES
48
49The B<EVP> interface to digital signatures should almost always be used in
50preference to the low level interfaces. This is because the code then becomes
51transparent to the algorithm used and much more flexible.
52
53In previous versions of OpenSSL there was a link between message digest types
54and public key algorithms. This meant that "clone" digests such as EVP_dss1()
55needed to be used to sign using SHA1 and DSA. This is no longer necessary and
56the use of clone digest is now discouraged.
57
58For some key types and parameters the random number generator must be seeded
59or the operation will fail. 
60
61The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
62context. This means that calls to EVP_DigestSignUpdate() and
63EVP_DigestSignFinal() can be called later to digest and sign additional data.
64
65Since only a copy of the digest context is ever finalized the context must
66be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
67will occur.
68
69The use of EVP_PKEY_size() with these functions is discouraged because some
70signature operations may have a signature length which depends on the
71parameters set. As a result EVP_PKEY_size() would have to return a value
72which indicates the maximum possible signature for any set of parameters.
73
74=head1 SEE ALSO
75
76L<EVP_DigestVerifyInit(3)|EVP_DigestVerifyInit(3)>,
77L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
78L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
79L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
80L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
81
82=head1 HISTORY
83
84EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() 
85were first added to OpenSSL 1.0.0.
86
87=cut
88