]>
Commit | Line | Data |
---|---|---|
29cf84c6 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_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, | |
1bc74519 | 12 | const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); |
8bdce8d1 | 13 | int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); |
29cf84c6 DSH |
14 | int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); |
15 | ||
16 | =head1 DESCRIPTION | |
17 | ||
18 | The EVP signature routines are a high level interface to digital signatures. | |
19 | ||
20 | EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from | |
25191fff RL |
21 | ENGINE B<impl> and private key B<pkey>. B<ctx> must be created with |
22 | EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the | |
29cf84c6 DSH |
23 | EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can |
24 | be used to set alternative signing options. | |
25 | ||
26 | EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the | |
27 | signature context B<ctx>. This function can be called several times on the | |
28 | same B<ctx> to include additional data. This function is currently implemented | |
186bb907 | 29 | using a macro. |
29cf84c6 DSH |
30 | |
31 | EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>. | |
32 | If B<sig> is B<NULL> then the maximum size of the output buffer is written to | |
33 | the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the | |
34 | B<siglen> parameter should contain the length of the B<sig> buffer, if the | |
35 | call is successful the signature is written to B<sig> and the amount of data | |
36 | written to B<siglen>. | |
37 | ||
38 | =head1 RETURN VALUES | |
39 | ||
40 | EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return | |
41 | 1 for success and 0 or a negative value for failure. In particular a return | |
42 | value of -2 indicates the operation is not supported by the public key | |
43 | algorithm. | |
44 | ||
9b86974e | 45 | The error codes can be obtained from L<ERR_get_error(3)>. |
29cf84c6 DSH |
46 | |
47 | =head1 NOTES | |
48 | ||
49 | The B<EVP> interface to digital signatures should almost always be used in | |
50 | preference to the low level interfaces. This is because the code then becomes | |
51 | transparent to the algorithm used and much more flexible. | |
52 | ||
53 | In previous versions of OpenSSL there was a link between message digest types | |
54 | and public key algorithms. This meant that "clone" digests such as EVP_dss1() | |
55 | needed to be used to sign using SHA1 and DSA. This is no longer necessary and | |
56 | the use of clone digest is now discouraged. | |
57 | ||
58 | For some key types and parameters the random number generator must be seeded | |
1bc74519 | 59 | or the operation will fail. |
29cf84c6 DSH |
60 | |
61 | The call to EVP_DigestSignFinal() internally finalizes a copy of the digest | |
62 | context. This means that calls to EVP_DigestSignUpdate() and | |
63 | EVP_DigestSignFinal() can be called later to digest and sign additional data. | |
64 | ||
65 | Since only a copy of the digest context is ever finalized the context must | |
66 | be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak | |
67 | will occur. | |
68 | ||
69 | The use of EVP_PKEY_size() with these functions is discouraged because some | |
70 | signature operations may have a signature length which depends on the | |
71 | parameters set. As a result EVP_PKEY_size() would have to return a value | |
72 | which indicates the maximum possible signature for any set of parameters. | |
73 | ||
74 | =head1 SEE ALSO | |
75 | ||
9b86974e | 76 | L<EVP_DigestVerifyInit(3)>, |
b97fdb57 RL |
77 | L<EVP_DigestInit(3)>, L<err(7)>, |
78 | L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, | |
79 | L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, | |
80 | L<SHA1(3)>, L<dgst(1)> | |
29cf84c6 DSH |
81 | |
82 | =head1 HISTORY | |
83 | ||
1bc74519 | 84 | EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() |
fb552ac6 | 85 | were first added to OpenSSL 1.0.0. |
29cf84c6 | 86 | |
e2f92610 RS |
87 | =head1 COPYRIGHT |
88 | ||
89 | Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. | |
90 | ||
91 | Licensed under the OpenSSL license (the "License"). You may not use | |
92 | this file except in compliance with the License. You can obtain a copy | |
93 | in the file LICENSE in the source distribution or at | |
94 | L<https://www.openssl.org/source/license.html>. | |
95 | ||
96 | =cut |