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