]>
Commit | Line | Data |
---|---|---|
5ce60a20 | 1 | =pod |
625c781d | 2 | {- OpenSSL::safe::output_do_not_edit_headers(); -} |
9fcb9702 | 3 | |
5ce60a20 DSH |
4 | =head1 NAME |
5 | ||
4b537191 | 6 | openssl-pkeyutl - public key algorithm command |
5ce60a20 DSH |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<pkeyutl> | |
169394d4 | 11 | [B<-help>] |
e8769719 | 12 | [B<-in> I<file>] |
a7cef52f | 13 | [B<-rawin>] |
e8769719 RS |
14 | [B<-digest> I<algorithm>] |
15 | [B<-out> I<file>] | |
16 | [B<-sigfile> I<file>] | |
17 | [B<-inkey> I<file>] | |
6d382c74 | 18 | [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>] |
e8769719 RS |
19 | [B<-passin> I<arg>] |
20 | [B<-peerkey> I<file>] | |
6d382c74 | 21 | [B<-peerform> B<DER>|B<PEM>|B<P12>|B<ENGINE>] |
5ce60a20 DSH |
22 | [B<-pubin>] |
23 | [B<-certin>] | |
24 | [B<-rev>] | |
25 | [B<-sign>] | |
26 | [B<-verify>] | |
27 | [B<-verifyrecover>] | |
28 | [B<-encrypt>] | |
29 | [B<-decrypt>] | |
30 | [B<-derive>] | |
e8769719 RS |
31 | [B<-kdf> I<algorithm>] |
32 | [B<-kdflen> I<length>] | |
2f0ea936 RL |
33 | [B<-pkeyopt> I<opt>:I<value>] |
34 | [B<-pkeyopt_passin> I<opt>[:I<passarg>]] | |
5ce60a20 DSH |
35 | [B<-hexdump>] |
36 | [B<-asn1parse>] | |
018aaeb4 | 37 | {- $OpenSSL::safe::opt_engine_synopsis -} |
a173a7ee | 38 | [B<-engine_impl>] |
9fcb9702 | 39 | {- $OpenSSL::safe::opt_r_synopsis -} |
6bd4e3f2 | 40 | {- $OpenSSL::safe::opt_provider_synopsis -} |
ae89578b | 41 | {- $OpenSSL::safe::opt_config_synopsis -} |
5ce60a20 | 42 | |
9f3c076b | 43 | =for openssl ifdef engine engine_impl |
1738c0ce | 44 | |
5ce60a20 DSH |
45 | =head1 DESCRIPTION |
46 | ||
8c1cbc72 | 47 | This command can be used to perform low-level public key |
35a810bb | 48 | operations using any supported algorithm. |
5ce60a20 | 49 | |
3dfda1a6 | 50 | =head1 OPTIONS |
5ce60a20 DSH |
51 | |
52 | =over 4 | |
53 | ||
169394d4 MR |
54 | =item B<-help> |
55 | ||
56 | Print out a usage message. | |
57 | ||
e8769719 | 58 | =item B<-in> I<filename> |
5ce60a20 DSH |
59 | |
60 | This specifies the input filename to read data from or standard input | |
61 | if this option is not specified. | |
62 | ||
a7cef52f PY |
63 | =item B<-rawin> |
64 | ||
65 | This indicates that the input data is raw data, which is not hashed by any | |
66 | message digest algorithm. The user can specify a digest algorithm by using | |
67 | the B<-digest> option. This option can only be used with B<-sign> and | |
ee633ace | 68 | B<-verify> and must be used with the Ed25519 and Ed448 algorithms. |
a7cef52f | 69 | |
e8769719 | 70 | =item B<-digest> I<algorithm> |
a7cef52f PY |
71 | |
72 | This specifies the digest algorithm which is used to hash the input data before | |
73 | signing or verifying it with the input key. This option could be omitted if the | |
74 | signature algorithm does not require one (for instance, EdDSA). If this option | |
75 | is omitted but the signature algorithm requires one, a default value will be | |
76 | used. For signature algorithms like RSA, DSA and ECDSA, SHA-256 will be the | |
77 | default digest algorithm. For SM2, it will be SM3. If this option is present, | |
35a810bb | 78 | then the B<-rawin> option must be also specified. |
a7cef52f | 79 | |
e8769719 | 80 | =item B<-out> I<filename> |
5ce60a20 | 81 | |
c4de074e | 82 | Specifies the output filename to write to or standard output by |
5ce60a20 DSH |
83 | default. |
84 | ||
e8769719 | 85 | =item B<-sigfile> I<file> |
a173a7ee | 86 | |
2f0ea936 | 87 | Signature file, required for B<-verify> operations only |
a173a7ee | 88 | |
e8769719 | 89 | =item B<-inkey> I<file> |
5ce60a20 | 90 | |
c4de074e | 91 | The input key file, by default it should be a private key. |
5ce60a20 | 92 | |
6d382c74 | 93 | =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE> |
5ce60a20 | 94 | |
777182a0 | 95 | The key format; the default is B<PEM>. |
6d382c74 | 96 | The only value with effect is B<ENGINE>; all others have become obsolete. |
777182a0 | 97 | See L<openssl(1)/Format Options> for details. |
e5fa864f | 98 | |
e8769719 | 99 | =item B<-passin> I<arg> |
e5fa864f | 100 | |
2f0ea936 | 101 | The input key password source. For more information about the format of I<arg> |
3a4e43de | 102 | see L<openssl(1)/Pass Phrase Options>. |
e5fa864f | 103 | |
e8769719 | 104 | =item B<-peerkey> I<file> |
5ce60a20 | 105 | |
c4de074e | 106 | The peer key file, used by key derivation (agreement) operations. |
5ce60a20 | 107 | |
6d382c74 | 108 | =item B<-peerform> B<DER>|B<PEM>|B<P12>|B<ENGINE> |
5ce60a20 | 109 | |
777182a0 | 110 | The peer key format; the default is B<PEM>. |
6d382c74 | 111 | The only value with effect is B<ENGINE>; all others have become obsolete. |
777182a0 | 112 | See L<openssl(1)/Format Options> for details. |
5ce60a20 DSH |
113 | |
114 | =item B<-pubin> | |
115 | ||
c4de074e | 116 | The input file is a public key. |
5ce60a20 DSH |
117 | |
118 | =item B<-certin> | |
119 | ||
c4de074e | 120 | The input is a certificate containing a public key. |
5ce60a20 | 121 | |
8d970ca7 DSH |
122 | =item B<-rev> |
123 | ||
c4de074e | 124 | Reverse the order of the input buffer. This is useful for some libraries |
8d970ca7 DSH |
125 | (such as CryptoAPI) which represent the buffer in little endian format. |
126 | ||
5ce60a20 DSH |
127 | =item B<-sign> |
128 | ||
a0abb6a1 MC |
129 | Sign the input data (which must be a hash) and output the signed result. This |
130 | requires a private key. | |
5ce60a20 DSH |
131 | |
132 | =item B<-verify> | |
133 | ||
a0abb6a1 MC |
134 | Verify the input data (which must be a hash) against the signature file and |
135 | indicate if the verification succeeded or failed. | |
5ce60a20 DSH |
136 | |
137 | =item B<-verifyrecover> | |
138 | ||
a0abb6a1 | 139 | Verify the input data (which must be a hash) and output the recovered data. |
5ce60a20 DSH |
140 | |
141 | =item B<-encrypt> | |
142 | ||
c4de074e | 143 | Encrypt the input data using a public key. |
5ce60a20 DSH |
144 | |
145 | =item B<-decrypt> | |
146 | ||
c4de074e | 147 | Decrypt the input data using a private key. |
5ce60a20 DSH |
148 | |
149 | =item B<-derive> | |
150 | ||
c4de074e | 151 | Derive a shared secret using the peer key. |
5ce60a20 | 152 | |
e8769719 | 153 | =item B<-kdf> I<algorithm> |
924ec89a | 154 | |
2f0ea936 | 155 | Use key derivation function I<algorithm>. The supported algorithms are |
f04abe7d | 156 | at present B<TLS1-PRF> and B<HKDF>. |
77a795e4 | 157 | Note: additional parameters and the KDF output length will normally have to be |
b275f3b6 RL |
158 | set for this to work. |
159 | See L<EVP_PKEY_CTX_set_hkdf_md(3)> and L<EVP_PKEY_CTX_set_tls1_prf_md(3)> | |
f04abe7d | 160 | for the supported string parameters of each algorithm. |
924ec89a | 161 | |
e8769719 | 162 | =item B<-kdflen> I<length> |
924ec89a | 163 | |
f04abe7d | 164 | Set the output length for KDF. |
924ec89a | 165 | |
2f0ea936 | 166 | =item B<-pkeyopt> I<opt>:I<value> |
a173a7ee RS |
167 | |
168 | Public key options specified as opt:value. See NOTES below for more details. | |
169 | ||
2f0ea936 | 170 | =item B<-pkeyopt_passin> I<opt>[:I<passarg>] |
6dfcea3d | 171 | |
2f0ea936 RL |
172 | Allows reading a public key option I<opt> from stdin or a password source. |
173 | If only I<opt> is specified, the user will be prompted to enter a password on | |
174 | stdin. Alternatively, I<passarg> can be specified which can be any value | |
f5c14c63 | 175 | supported by L<openssl(1)/Pass phrase options>. |
6dfcea3d | 176 | |
5ce60a20 DSH |
177 | =item B<-hexdump> |
178 | ||
179 | hex dump the output data. | |
180 | ||
181 | =item B<-asn1parse> | |
182 | ||
c4de074e | 183 | Parse the ASN.1 output data, this is useful when combined with the |
5ce60a20 DSH |
184 | B<-verifyrecover> option when an ASN1 structure is signed. |
185 | ||
018aaeb4 | 186 | {- $OpenSSL::safe::opt_engine_item -} |
a173a7ee RS |
187 | |
188 | =item B<-engine_impl> | |
189 | ||
190 | When used with the B<-engine> option, it specifies to also use | |
2f0ea936 | 191 | engine I<id> for crypto operations. |
a173a7ee | 192 | |
9fcb9702 | 193 | {- $OpenSSL::safe::opt_r_item -} |
6bd4e3f2 P |
194 | |
195 | {- $OpenSSL::safe::opt_provider_item -} | |
9fcb9702 | 196 | |
ae89578b SL |
197 | {- $OpenSSL::safe::opt_config_item -} |
198 | ||
5ce60a20 DSH |
199 | =back |
200 | ||
201 | =head1 NOTES | |
202 | ||
203 | The operations and options supported vary according to the key algorithm | |
204 | and its implementation. The OpenSSL operations and options are indicated below. | |
205 | ||
2f0ea936 | 206 | Unless otherwise mentioned all algorithms support the B<digest:>I<alg> option |
8d970ca7 | 207 | which specifies the digest in use for sign, verify and verifyrecover operations. |
2f0ea936 | 208 | The value I<alg> should represent a digest name as used in the |
a0abb6a1 MC |
209 | EVP_get_digestbyname() function for example B<sha1>. This value is not used to |
210 | hash the input data. It is used (by some algorithms) for sanity-checking the | |
35a810bb RL |
211 | lengths of data passed in and for creating the structures that make up the |
212 | signature (e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures). | |
a0abb6a1 | 213 | |
35a810bb | 214 | This command does not hash the input data (except where -rawin is used) but |
ee633ace MC |
215 | rather it will use the data directly as input to the signature algorithm. |
216 | Depending on the key type, signature type, and mode of padding, the maximum | |
217 | acceptable lengths of input data differ. The signed data can't be longer than | |
218 | the key modulus with RSA. In case of ECDSA and DSA the data shouldn't be longer | |
219 | than the field size, otherwise it will be silently truncated to the field size. | |
220 | In any event the input size must not be larger than the largest supported digest | |
221 | size. | |
a0abb6a1 MC |
222 | |
223 | In other words, if the value of digest is B<sha1> the input should be the 20 | |
224 | bytes long binary encoding of the SHA-1 hash function output. | |
225 | ||
5ce60a20 DSH |
226 | =head1 RSA ALGORITHM |
227 | ||
d231a401 VD |
228 | The RSA algorithm generally supports the encrypt, decrypt, sign, |
229 | verify and verifyrecover operations. However, some padding modes | |
230 | support only a subset of these operations. The following additional | |
231 | B<pkeyopt> values are supported: | |
5ce60a20 | 232 | |
8d970ca7 DSH |
233 | =over 4 |
234 | ||
2f0ea936 | 235 | =item B<rsa_padding_mode:>I<mode> |
8d970ca7 | 236 | |
2f0ea936 | 237 | This sets the RSA padding mode. Acceptable values for I<mode> are B<pkcs1> for |
8d970ca7 DSH |
238 | PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep> |
239 | for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS. | |
5ce60a20 | 240 | |
1bc74519 | 241 | In PKCS#1 padding if the message digest is not set then the supplied data is |
8d970ca7 DSH |
242 | signed or verified directly instead of using a B<DigestInfo> structure. If a |
243 | digest is set then the a B<DigestInfo> structure is used and its the length | |
244 | must correspond to the digest type. | |
245 | ||
7b1d9460 | 246 | For B<oaep> mode only encryption and decryption is supported. |
8d970ca7 DSH |
247 | |
248 | For B<x931> if the digest type is set it is used to format the block data | |
249 | otherwise the first byte is used to specify the X9.31 digest ID. Sign, | |
250 | verify and verifyrecover are can be performed in this mode. | |
251 | ||
252 | For B<pss> mode only sign and verify are supported and the digest type must be | |
253 | specified. | |
254 | ||
2f0ea936 | 255 | =item B<rsa_pss_saltlen:>I<len> |
8d970ca7 | 256 | |
137096a7 | 257 | For B<pss> mode only this option specifies the salt length. Three special |
2f0ea936 RL |
258 | values are supported: B<digest> sets the salt length to the digest length, |
259 | B<max> sets the salt length to the maximum permissible value. When verifying | |
260 | B<auto> causes the salt length to be automatically determined based on the | |
137096a7 | 261 | B<PSS> block structure. |
8d970ca7 | 262 | |
2f0ea936 | 263 | =item B<rsa_mgf1_md:>I<digest> |
7751098e DSH |
264 | |
265 | For PSS and OAEP padding sets the MGF1 digest. If the MGF1 digest is not | |
266 | explicitly set in PSS mode then the signing digest is used. | |
267 | ||
268 | =back | |
269 | ||
270 | =head1 RSA-PSS ALGORITHM | |
271 | ||
272 | The RSA-PSS algorithm is a restricted version of the RSA algorithm which only | |
273 | supports the sign and verify operations with PSS padding. The following | |
2f0ea936 | 274 | additional B<-pkeyopt> values are supported: |
7751098e DSH |
275 | |
276 | =over 4 | |
277 | ||
2f0ea936 RL |
278 | =item B<rsa_padding_mode:>I<mode>, B<rsa_pss_saltlen:>I<len>, |
279 | B<rsa_mgf1_md:>I<digest> | |
7751098e DSH |
280 | |
281 | These have the same meaning as the B<RSA> algorithm with some additional | |
282 | restrictions. The padding mode can only be set to B<pss> which is the | |
283 | default value. | |
284 | ||
285 | If the key has parameter restrictions than the digest, MGF1 | |
286 | digest and salt length are set to the values specified in the parameters. | |
287 | The digest and MG cannot be changed and the salt length cannot be set to a | |
288 | value less than the minimum restriction. | |
289 | ||
8d970ca7 DSH |
290 | =back |
291 | ||
292 | =head1 DSA ALGORITHM | |
293 | ||
294 | The DSA algorithm supports signing and verification operations only. Currently | |
6a6d9ecd MC |
295 | there are no additional B<-pkeyopt> options other than B<digest>. The SHA1 |
296 | digest is assumed by default. | |
8d970ca7 DSH |
297 | |
298 | =head1 DH ALGORITHM | |
299 | ||
300 | The DH algorithm only supports the derivation operation and no additional | |
6a6d9ecd | 301 | B<-pkeyopt> options. |
8d970ca7 DSH |
302 | |
303 | =head1 EC ALGORITHM | |
304 | ||
305 | The EC algorithm supports sign, verify and derive operations. The sign and | |
6a6d9ecd MC |
306 | verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for |
307 | the B<-pkeyopt> B<digest> option. | |
5ce60a20 | 308 | |
485d3361 | 309 | =head1 X25519 AND X448 ALGORITHMS |
c082201a | 310 | |
a2eecb5d MC |
311 | The X25519 and X448 algorithms support key derivation only. Currently there are |
312 | no additional options. | |
c082201a | 313 | |
485d3361 | 314 | =head1 ED25519 AND ED448 ALGORITHMS |
ee633ace MC |
315 | |
316 | These algorithms only support signing and verifying. OpenSSL only implements the | |
317 | "pure" variants of these algorithms so raw data can be passed directly to them | |
2f0ea936 RL |
318 | without hashing them first. The option B<-rawin> must be used with these |
319 | algorithms with no B<-digest> specified. Additionally OpenSSL only supports | |
ee633ace MC |
320 | "oneshot" operation with these algorithms. This means that the entire file to |
321 | be signed/verified must be read into memory before processing it. Signing or | |
322 | Verifying very large files should be avoided. Additionally the size of the file | |
323 | must be known for this to work. If the size of the file cannot be determined | |
324 | (for example if the input is stdin) then the sign or verify operation will fail. | |
325 | ||
a7cef52f PY |
326 | =head1 SM2 |
327 | ||
328 | The SM2 algorithm supports sign, verify, encrypt and decrypt operations. For | |
2292c8e1 RL |
329 | the sign and verify operations, SM2 requires an Distinguishing ID string to |
330 | be passed in. The following B<-pkeyopt> value is supported: | |
a7cef52f PY |
331 | |
332 | =over 4 | |
333 | ||
2292c8e1 | 334 | =item B<distid:>I<string> |
a7cef52f PY |
335 | |
336 | This sets the ID string used in SM2 sign or verify operations. While verifying | |
337 | an SM2 signature, the ID string must be the same one used when signing the data. | |
338 | Otherwise the verification will fail. | |
339 | ||
2292c8e1 | 340 | =item B<hexdistid:>I<hex_string> |
a45eb7e8 PY |
341 | |
342 | This sets the ID string used in SM2 sign or verify operations. While verifying | |
343 | an SM2 signature, the ID string must be the same one used when signing the data. | |
344 | Otherwise the verification will fail. The ID string provided with this option | |
345 | should be a valid hexadecimal value. | |
346 | ||
a7cef52f PY |
347 | =back |
348 | ||
5ce60a20 DSH |
349 | =head1 EXAMPLES |
350 | ||
351 | Sign some data using a private key: | |
352 | ||
353 | openssl pkeyutl -sign -in file -inkey key.pem -out sig | |
354 | ||
355 | Recover the signed data (e.g. if an RSA key is used): | |
356 | ||
357 | openssl pkeyutl -verifyrecover -in sig -inkey key.pem | |
358 | ||
359 | Verify the signature (e.g. a DSA key): | |
360 | ||
383b8b8c | 361 | openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem |
5ce60a20 | 362 | |
8d970ca7 DSH |
363 | Sign data using a message digest value (this is currently only valid for RSA): |
364 | ||
365 | openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256 | |
366 | ||
367 | Derive a shared secret value: | |
368 | ||
369 | openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret | |
370 | ||
924ec89a | 371 | Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and |
95e040bb | 372 | seed consisting of the single byte 0xFF: |
924ec89a DSH |
373 | |
374 | openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \ | |
375 | -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump | |
376 | ||
6dfcea3d JB |
377 | Derive a key using B<scrypt> where the password is read from command line: |
378 | ||
379 | openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass \ | |
380 | -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1 | |
381 | ||
382 | Derive using the same algorithm, but read key from environment variable MYPASS: | |
383 | ||
384 | openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass:env:MYPASS \ | |
385 | -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1 | |
386 | ||
a7cef52f PY |
387 | Sign some data using an L<SM2(7)> private key and a specific ID: |
388 | ||
389 | openssl pkeyutl -sign -in file -inkey sm2.key -out sig -rawin -digest sm3 \ | |
2292c8e1 | 390 | -pkeyopt distid:someid |
a7cef52f PY |
391 | |
392 | Verify some data using an L<SM2(7)> certificate and a specific ID: | |
393 | ||
394 | openssl pkeyutl -verify -certin -in file -inkey sm2.cert -sigfile sig \ | |
2292c8e1 | 395 | -rawin -digest sm3 -pkeyopt distid:someid |
a7cef52f | 396 | |
5ce60a20 | 397 | =head1 SEE ALSO |
383b8b8c | 398 | |
b6b66573 DMSP |
399 | L<openssl(1)>, |
400 | L<openssl-genpkey(1)>, | |
401 | L<openssl-pkey(1)>, | |
402 | L<openssl-rsautl(1)> | |
403 | L<openssl-dgst(1)>, | |
404 | L<openssl-rsa(1)>, | |
405 | L<openssl-genrsa(1)>, | |
406 | L<openssl-kdf(1)> | |
407 | L<EVP_PKEY_CTX_set_hkdf_md(3)>, | |
408 | L<EVP_PKEY_CTX_set_tls1_prf_md(3)>, | |
409 | ||
6d382c74 DDO |
410 | =head1 HISTORY |
411 | ||
412 | All B<-keyform> values except B<ENGINE> have become obsolete in OpenSSL 3.0.0 | |
413 | and have no effect. | |
99ec4fdb | 414 | |
0f221d9c P |
415 | The B<-engine> option was deprecated in OpenSSL 3.0. |
416 | ||
e2f92610 RS |
417 | =head1 COPYRIGHT |
418 | ||
33388b44 | 419 | Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 420 | |
449040b4 | 421 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
422 | this file except in compliance with the License. You can obtain a copy |
423 | in the file LICENSE in the source distribution or at | |
424 | L<https://www.openssl.org/source/license.html>. | |
425 | ||
426 | =cut |