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