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