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