]>
Commit | Line | Data |
---|---|---|
29cf84c6 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
a0b6c1ff MC |
5 | EVP_DigestSignInit_ex, EVP_DigestSignInit, EVP_DigestSignUpdate, |
6 | EVP_DigestSignFinal, EVP_DigestSign - EVP signing functions | |
29cf84c6 DSH |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/evp.h> | |
11 | ||
a0b6c1ff MC |
12 | int EVP_DigestSignInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, |
13 | const char *mdname, const char *props, | |
0e521004 | 14 | EVP_PKEY *pkey); |
29cf84c6 | 15 | int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, |
1bc74519 | 16 | const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); |
8bdce8d1 | 17 | int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); |
29cf84c6 DSH |
18 | int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); |
19 | ||
75394189 DSH |
20 | int EVP_DigestSign(EVP_MD_CTX *ctx, unsigned char *sigret, |
21 | size_t *siglen, const unsigned char *tbs, | |
22 | size_t tbslen); | |
23 | ||
29cf84c6 DSH |
24 | =head1 DESCRIPTION |
25 | ||
26 | The EVP signature routines are a high level interface to digital signatures. | |
a0b6c1ff MC |
27 | Input data is digested first before the signing takes place. |
28 | ||
0e521004 RL |
29 | EVP_DigestSignInit_ex() sets up signing context I<ctx> to use a digest with the |
30 | name I<mdname> and private key I<pkey>. The name of the digest to be used is | |
31 | passed to the provider of the signature algorithm in use. How that provider | |
32 | interprets the digest name is provider specific. The provider may implement | |
33 | that digest directly itself or it may (optionally) choose to fetch it (which | |
34 | could result in a digest from a different provider being selected). If the | |
35 | provider supports fetching the digest then it may use the I<props> argument for | |
36 | the properties to be used during the fetch. | |
37 | ||
38 | The I<pkey> algorithm is used to fetch a B<EVP_SIGNATURE> method implicitly, to | |
39 | be used for the actual signing. See L<provider(7)/Implicit fetch> for | |
40 | more information about implict fetches. | |
a0b6c1ff MC |
41 | |
42 | The OpenSSL default and legacy providers support fetching digests and can fetch | |
43 | those digests from any available provider. The OpenSSL fips provider also | |
44 | supports fetching digests but will only fetch digests that are themselves | |
45 | implemented inside the fips provider. | |
46 | ||
0e521004 RL |
47 | I<ctx> must be created with EVP_MD_CTX_new() before calling this function. If |
48 | I<pctx> is not NULL, the EVP_PKEY_CTX of the signing operation will be written | |
49 | to I<*pctx>: this can be used to set alternative signing options. Note that any | |
50 | existing value in I<*pctx> is overwritten. The EVP_PKEY_CTX value returned must | |
51 | not be freed directly by the application if I<ctx> is not assigned an | |
a0b6c1ff MC |
52 | EVP_PKEY_CTX value before being passed to EVP_DigestSignInit_ex() (which means |
53 | the EVP_PKEY_CTX is created inside EVP_DigestSignInit_ex() and it will be freed | |
54 | automatically when the EVP_MD_CTX is freed). | |
55 | ||
0e521004 RL |
56 | The digest I<mdname> may be NULL if the signing algorithm supports it. The |
57 | I<props> argument can always be NULL. | |
a0b6c1ff MC |
58 | |
59 | No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit_ex() if the passed | |
3c86a2b5 | 60 | I<ctx> has already been assigned one via L<EVP_MD_CTX_set_pkey_ctx(3)>. See also |
a0b6c1ff | 61 | L<SM2(7)>. |
be93b0e8 MC |
62 | |
63 | Only EVP_PKEY types that support signing can be used with these functions. This | |
64 | includes MAC algorithms where the MAC generation is considered as a form of | |
fa332bba | 65 | "signing". Built-in EVP_PKEY types supported by these functions are CMAC, |
c6378913 | 66 | Poly1305, DSA, ECDSA, HMAC, RSA, SipHash, Ed25519 and Ed448. |
be93b0e8 MC |
67 | |
68 | Not all digests can be used for all key types. The following combinations apply. | |
69 | ||
70 | =over 4 | |
71 | ||
72 | =item DSA | |
73 | ||
74 | Supports SHA1, SHA224, SHA256, SHA384 and SHA512 | |
75 | ||
76 | =item ECDSA | |
77 | ||
78 | Supports SHA1, SHA224, SHA256, SHA384, SHA512 and SM3 | |
79 | ||
80 | =item RSA with no padding | |
81 | ||
0e521004 | 82 | Supports no digests (the digest I<type> must be NULL) |
be93b0e8 MC |
83 | |
84 | =item RSA with X931 padding | |
85 | ||
86 | Supports SHA1, SHA256, SHA384 and SHA512 | |
87 | ||
88 | =item All other RSA padding types | |
89 | ||
90 | Support SHA1, SHA224, SHA256, SHA384, SHA512, MD5, MD5_SHA1, MD2, MD4, MDC2, | |
91 | SHA3-224, SHA3-256, SHA3-384, SHA3-512 | |
92 | ||
93 | =item Ed25519 and Ed448 | |
94 | ||
0e521004 | 95 | Support no digests (the digest I<type> must be NULL) |
be93b0e8 MC |
96 | |
97 | =item HMAC | |
98 | ||
99 | Supports any digest | |
100 | ||
101 | =item CMAC, Poly1305 and SipHash | |
102 | ||
103 | Will ignore any digest provided. | |
104 | ||
105 | =back | |
106 | ||
107 | If RSA-PSS is used and restrictions apply then the digest must match. | |
29cf84c6 | 108 | |
a0b6c1ff | 109 | EVP_DigestSignInit() works in the same way as EVP_DigestSignInit_ex() except |
0e521004 RL |
110 | that the I<mdname> parameter will be inferred from the supplied digest I<type>, |
111 | and I<props> will be NULL. Where supplied the ENGINE I<e> will be used for the | |
112 | signing and digest algorithm implementations. I<e> may be NULL. | |
113 | ||
114 | EVP_DigestSignUpdate() hashes I<cnt> bytes of data at I<d> into the | |
115 | signature context I<ctx>. This function can be called several times on the | |
116 | same I<ctx> to include additional data. | |
117 | ||
118 | EVP_DigestSignFinal() signs the data in I<ctx> and places the signature in I<sig>. | |
119 | If I<sig> is NULL then the maximum size of the output buffer is written to | |
120 | the I<siglen> parameter. If I<sig> is not NULL then before the call the | |
121 | I<siglen> parameter should contain the length of the I<sig> buffer. If the | |
122 | call is successful the signature is written to I<sig> and the amount of data | |
123 | written to I<siglen>. | |
124 | ||
125 | EVP_DigestSign() signs I<tbslen> bytes of data at I<tbs> and places the | |
126 | signature in I<sig> and its length in I<siglen> in a similar way to | |
75394189 DSH |
127 | EVP_DigestSignFinal(). |
128 | ||
29cf84c6 DSH |
129 | =head1 RETURN VALUES |
130 | ||
099a3982 | 131 | EVP_DigestSignInit(), EVP_DigestSignUpdate(), EVP_DigestSignFinal() and |
76123661 | 132 | EVP_DigestSign() return 1 for success and 0 for failure. |
29cf84c6 | 133 | |
9b86974e | 134 | The error codes can be obtained from L<ERR_get_error(3)>. |
29cf84c6 DSH |
135 | |
136 | =head1 NOTES | |
137 | ||
138 | The B<EVP> interface to digital signatures should almost always be used in | |
139 | preference to the low level interfaces. This is because the code then becomes | |
140 | transparent to the algorithm used and much more flexible. | |
141 | ||
74e78361 DSH |
142 | EVP_DigestSign() is a one shot operation which signs a single block of data |
143 | in one function. For algorithms that support streaming it is equivalent to | |
144 | calling EVP_DigestSignUpdate() and EVP_DigestSignFinal(). For algorithms which | |
145 | do not support streaming (e.g. PureEdDSA) it is the only way to sign data. | |
75394189 | 146 | |
29cf84c6 DSH |
147 | In previous versions of OpenSSL there was a link between message digest types |
148 | and public key algorithms. This meant that "clone" digests such as EVP_dss1() | |
149 | needed to be used to sign using SHA1 and DSA. This is no longer necessary and | |
150 | the use of clone digest is now discouraged. | |
151 | ||
262c0088 DMSP |
152 | For some key types and parameters the random number generator must be seeded. |
153 | If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to | |
154 | external circumstances (see L<RAND(7)>), the operation will fail. | |
29cf84c6 DSH |
155 | |
156 | The call to EVP_DigestSignFinal() internally finalizes a copy of the digest | |
157 | context. This means that calls to EVP_DigestSignUpdate() and | |
158 | EVP_DigestSignFinal() can be called later to digest and sign additional data. | |
159 | ||
fa332bba | 160 | Since only a copy of the digest context is ever finalized, the context must |
c12a2d27 | 161 | be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak |
29cf84c6 DSH |
162 | will occur. |
163 | ||
164 | The use of EVP_PKEY_size() with these functions is discouraged because some | |
165 | signature operations may have a signature length which depends on the | |
166 | parameters set. As a result EVP_PKEY_size() would have to return a value | |
167 | which indicates the maximum possible signature for any set of parameters. | |
168 | ||
169 | =head1 SEE ALSO | |
170 | ||
9b86974e | 171 | L<EVP_DigestVerifyInit(3)>, |
73fb82b7 | 172 | L<EVP_DigestInit(3)>, |
b97fdb57 RL |
173 | L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, |
174 | L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, | |
1903a9b7 | 175 | L<SHA1(3)>, L<openssl-dgst(1)>, |
262c0088 | 176 | L<RAND(7)> |
29cf84c6 DSH |
177 | |
178 | =head1 HISTORY | |
179 | ||
1bc74519 | 180 | EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() |
fc5ecadd | 181 | were added in OpenSSL 1.0.0. |
29cf84c6 | 182 | |
a0b6c1ff MC |
183 | EVP_DigestSignInit_ex() was added in OpenSSL 3.0. |
184 | ||
185 | EVP_DigestSignUpdate() was converted from a macro to a function in OpenSSL 3.0. | |
186 | ||
e2f92610 RS |
187 | =head1 COPYRIGHT |
188 | ||
28428130 | 189 | Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 190 | |
4746f25a | 191 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
192 | this file except in compliance with the License. You can obtain a copy |
193 | in the file LICENSE in the source distribution or at | |
194 | L<https://www.openssl.org/source/license.html>. | |
195 | ||
196 | =cut |