EVP_DigestSignInit.pod revision 340704 
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. Note that any existing value in
25B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed
26directly by the application (it will be freed automatically when the EVP_MD_CTX
27is freed). The digest B<type> may be NULL if the signing algorithm supports it.
28
29EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the
30signature context B<ctx>. This function can be called several times on the
31same B<ctx> to include additional data. This function is currently implemented
32usig a macro.
33
34EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>.
35If B<sig> is B<NULL> then the maximum size of the output buffer is written to
36the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the
37B<siglen> parameter should contain the length of the B<sig> buffer, if the
38call is successful the signature is written to B<sig> and the amount of data
39written to B<siglen>.
40
41=head1 RETURN VALUES
42
43EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return
441 for success and 0 or a negative value for failure. In particular a return
45value of -2 indicates the operation is not supported by the public key
46algorithm.
47
48The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
49
50=head1 NOTES
51
52The B<EVP> interface to digital signatures should almost always be used in
53preference to the low level interfaces. This is because the code then becomes
54transparent to the algorithm used and much more flexible.
55
56In previous versions of OpenSSL there was a link between message digest types
57and public key algorithms. This meant that "clone" digests such as EVP_dss1()
58needed to be used to sign using SHA1 and DSA. This is no longer necessary and
59the use of clone digest is now discouraged.
60
61For some key types and parameters the random number generator must be seeded
62or the operation will fail. 
63
64The call to EVP_DigestSignFinal() internally finalizes a copy of the digest
65context. This means that calls to EVP_DigestSignUpdate() and
66EVP_DigestSignFinal() can be called later to digest and sign additional data.
67
68Since only a copy of the digest context is ever finalized the context must
69be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
70will occur.
71
72The use of EVP_PKEY_size() with these functions is discouraged because some
73signature operations may have a signature length which depends on the
74parameters set. As a result EVP_PKEY_size() would have to return a value
75which indicates the maximum possible signature for any set of parameters.
76
77=head1 SEE ALSO
78
79L<EVP_DigestVerifyInit(3)|EVP_DigestVerifyInit(3)>,
80L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
81L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
82L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
83L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
84
85=head1 HISTORY
86
87EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() 
88were first added to OpenSSL 1.0.0.
89
90=cut
91