]>
Commit | Line | Data |
---|---|---|
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. Note that any existing value in | |
30 | B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed | |
31 | directly by the application if B<ctx> is not assigned an EVP_PKEY_CTX value before | |
32 | being passed to EVP_DigestSignInit() (which means the EVP_PKEY_CTX is created | |
33 | inside EVP_DigestSignInit() and it will be freed automatically when the | |
34 | EVP_MD_CTX is freed). | |
35 | ||
36 | The digest B<type> may be NULL if the signing algorithm supports it. | |
37 | ||
38 | No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx> | |
39 | has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>. | |
40 | ||
41 | Only EVP_PKEY types that support signing can be used with these functions. This | |
42 | includes MAC algorithms where the MAC generation is considered as a form of | |
43 | "signing". Built-in EVP_PKEY types supported by these functions are CMAC, | |
44 | Poly1305, DSA, ECDSA, HMAC, RSA, SipHash, Ed25519 and Ed448. | |
45 | ||
46 | Not all digests can be used for all key types. The following combinations apply. | |
47 | ||
48 | =over 4 | |
49 | ||
50 | =item DSA | |
51 | ||
52 | Supports SHA1, SHA224, SHA256, SHA384 and SHA512 | |
53 | ||
54 | =item ECDSA | |
55 | ||
56 | Supports SHA1, SHA224, SHA256, SHA384, SHA512 and SM3 | |
57 | ||
58 | =item RSA with no padding | |
59 | ||
60 | Supports no digests (the digest B<type> must be NULL) | |
61 | ||
62 | =item RSA with X931 padding | |
63 | ||
64 | Supports SHA1, SHA256, SHA384 and SHA512 | |
65 | ||
66 | =item All other RSA padding types | |
67 | ||
68 | Support SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2, | |
69 | SHA3-224, SHA3-256, SHA3-384, SHA3-512 | |
70 | ||
71 | =item Ed25519 and Ed448 | |
72 | ||
73 | Support no digests (the digest B<type> must be NULL) | |
74 | ||
75 | =item HMAC | |
76 | ||
77 | Supports any digest | |
78 | ||
79 | =item CMAC, Poly1305 and SipHash | |
80 | ||
81 | Will ignore any digest provided. | |
82 | ||
83 | =back | |
84 | ||
85 | If RSA-PSS is used and restrictions apply then the digest must match. | |
86 | ||
87 | EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the | |
88 | signature context B<ctx>. This function can be called several times on the | |
89 | same B<ctx> to include additional data. This function is currently implemented | |
90 | using a macro. | |
91 | ||
92 | EVP_DigestSignFinal() signs the data in B<ctx> and places the signature in B<sig>. | |
93 | If B<sig> is B<NULL> then the maximum size of the output buffer is written to | |
94 | the B<siglen> parameter. If B<sig> is not B<NULL> then before the call the | |
95 | B<siglen> parameter should contain the length of the B<sig> buffer. If the | |
96 | call is successful the signature is written to B<sig> and the amount of data | |
97 | written to B<siglen>. | |
98 | ||
99 | EVP_DigestSign() signs B<tbslen> bytes of data at B<tbs> and places the | |
100 | signature in B<sig> and its length in B<siglen> in a similar way to | |
101 | EVP_DigestSignFinal(). | |
102 | ||
103 | =head1 RETURN VALUES | |
104 | ||
105 | EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignaFinal() and | |
106 | EVP_DigestSign() return 1 for success and 0 or a negative value for failure. In | |
107 | particular, a return value of -2 indicates the operation is not supported by the | |
108 | public key algorithm. | |
109 | ||
110 | The error codes can be obtained from L<ERR_get_error(3)>. | |
111 | ||
112 | =head1 NOTES | |
113 | ||
114 | The B<EVP> interface to digital signatures should almost always be used in | |
115 | preference to the low level interfaces. This is because the code then becomes | |
116 | transparent to the algorithm used and much more flexible. | |
117 | ||
118 | EVP_DigestSign() is a one shot operation which signs a single block of data | |
119 | in one function. For algorithms that support streaming it is equivalent to | |
120 | calling EVP_DigestSignUpdate() and EVP_DigestSignFinal(). For algorithms which | |
121 | do not support streaming (e.g. PureEdDSA) it is the only way to sign data. | |
122 | ||
123 | In previous versions of OpenSSL there was a link between message digest types | |
124 | and public key algorithms. This meant that "clone" digests such as EVP_dss1() | |
125 | needed to be used to sign using SHA1 and DSA. This is no longer necessary and | |
126 | the use of clone digest is now discouraged. | |
127 | ||
128 | For some key types and parameters the random number generator must be seeded. | |
129 | If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to | |
130 | external circumstances (see L<RAND(7)>), the operation will fail. | |
131 | ||
132 | The call to EVP_DigestSignFinal() internally finalizes a copy of the digest | |
133 | context. This means that calls to EVP_DigestSignUpdate() and | |
134 | EVP_DigestSignFinal() can be called later to digest and sign additional data. | |
135 | ||
136 | Since only a copy of the digest context is ever finalized, the context must | |
137 | be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak | |
138 | will occur. | |
139 | ||
140 | The use of EVP_PKEY_size() with these functions is discouraged because some | |
141 | signature operations may have a signature length which depends on the | |
142 | parameters set. As a result EVP_PKEY_size() would have to return a value | |
143 | which indicates the maximum possible signature for any set of parameters. | |
144 | ||
145 | =head1 SEE ALSO | |
146 | ||
147 | L<EVP_DigestVerifyInit(3)>, | |
148 | L<EVP_DigestInit(3)>, | |
149 | L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, | |
150 | L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, | |
151 | L<SHA1(3)>, L<dgst(1)>, | |
152 | L<RAND(7)> | |
153 | ||
154 | =head1 HISTORY | |
155 | ||
156 | EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() | |
157 | were added in OpenSSL 1.0.0. | |
158 | ||
159 | =head1 COPYRIGHT | |
160 | ||
161 | Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. | |
162 | ||
163 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
164 | this file except in compliance with the License. You can obtain a copy | |
165 | in the file LICENSE in the source distribution or at | |
166 | L<https://www.openssl.org/source/license.html>. | |
167 | ||
168 | =cut |