Lines Matching +full:mu +full:- +full:side +full:- +full:b
2 {- OpenSSL::safe::output_do_not_edit_headers(); -}
6 openssl-pkeyutl - asymmetric key command
10 B<openssl> B<pkeyutl>
11 [B<-help>]
12 [B<-in> I<file>]
13 [B<-rawin>]
14 [B<-digest> I<algorithm>]
15 [B<-out> I<file>]
16 [B<-secret> I<file>]
17 [B<-sigfile> I<file>]
18 [B<-inkey> I<filename>|I<uri>]
19 [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
20 [B<-passin> I<arg>]
21 [B<-pubin>]
22 [B<-certin>]
23 [B<-rev>]
24 [B<-sign>]
25 [B<-verify>]
26 [B<-verifyrecover>]
27 [B<-encrypt>]
28 [B<-decrypt>]
29 [B<-derive>]
30 [B<-peerkey> I<file>]
31 [B<-peerform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
32 [B<-encap>]
33 [B<-decap>]
34 [B<-kdf> I<algorithm>]
35 [B<-kdflen> I<length>]
36 [B<-kemop> I<mode>]
37 [B<-pkeyopt> I<opt>:I<value>]
38 [B<-pkeyopt_passin> I<opt>[:I<passarg>]]
39 [B<-hexdump>]
40 [B<-asn1parse>]
41 {- $OpenSSL::safe::opt_engine_synopsis -}[B<-engine_impl>]
42 {- $OpenSSL::safe::opt_r_synopsis -}
43 {- $OpenSSL::safe::opt_provider_synopsis -}
44 {- $OpenSSL::safe::opt_config_synopsis -}
48 This command can be used to perform low-level operations
51 By default the signing operation (see B<-sign> option) is assumed.
57 =item B<-help>
61 =item B<-in> I<filename>
66 =item B<-rawin>
71 the user can specify a digest algorithm by using the B<-digest> option.
75 This option can only be used with B<-sign> and B<-verify>.
79 The B<-digest> option implies B<-rawin> since OpenSSL 3.5.
81 =item B<-digest> I<algorithm>
83 This option can only be used with B<-sign> and B<-verify>.
88 is omitted but the signature algorithm requires one and the B<-rawin> option
89 is given, a default value will be used (see B<-rawin> for details).
90 If this option is present, then the B<-rawin> option
94 so the B<-digest> option cannot be used with EdDSA.
96 =item B<-out> I<filename>
100 =item B<-secret> I<filename>
102 Specifies the shared-secret output filename for when performing encapsulation
103 via the B<-encap> option or decapsulation via the B<-decap> option.
104 The B<-encap> option also produces a separate (public) ciphertext output which
105 is by default written to standard output, but being I<binary> non-text data,
106 is typically also redirected to a file selected via the I<-out> option.
108 =item B<-sigfile> I<file>
110 Signature file, required and allowed for B<-verify> operations only.
112 =item B<-inkey> I<filename>|I<uri>
116 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
119 See L<openssl-format-options(1)> for details.
121 =item B<-passin> I<arg>
124 see L<openssl-passphrase-options(1)>.
126 =item B<-pubin>
132 =item B<-certin>
136 =item B<-rev>
139 (such as CryptoAPI) which represent the buffer in little-endian format.
140 This cannot be used in conjunction with B<-rawin>.
142 =item B<-sign>
146 when applicable, see the B<-rawin> and B<-digest> options for details.
147 Otherwise, the input data given with the B<-in> option is assumed to already
148 be a digest, but this may then require an additional B<-pkeyopt> C<digest:>I<md>
150 Even for other algorithms like ECDSA, where the additional B<-pkeyopt> option
154 =item B<-verify>
156 Verify the input data against the signature given with the B<-sigfile> option
158 The input data given with the B<-in> option is assumed to be a hash value
159 unless the B<-rawin> option is specified or implied.
163 =item B<-verifyrecover>
166 For example, in case of RSA PKCS#1 the recovered data is the B<EMSA-PKCS-v1_5>
168 L<RFC8017 Section 9.2|https://datatracker.ietf.org/doc/html/rfc8017#section-9.2>.
170 Note that here the input given with the B<-in> option is not a signature input
171 (as with the B<-sign> and B<-verify> options) but a signature output value,
172 typically produced using the B<-sign> option.
176 =item B<-encrypt>
180 =item B<-decrypt>
184 =item B<-derive>
188 =item B<-peerkey> I<file>
192 Its type must match the type of the own private key given with B<-inkey>.
194 =item B<-peerform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
197 See L<openssl-format-options(1)> for details.
199 =item B<-encap>
201 Use a Key Encapsulation Mechanism (B<KEM>) to B<encapsulate> a shared-secret to
202 a peer's B<public> key.
203 The encapsulated result (or ciphertext, non-text binary data) is written to
204 standard output by default, or else to the file specified with I<-out>.
205 The I<-secret> option must also be provided to specify the output file for the
206 derived shared-secret value generated in the encapsulation process.
208 L<ML-KEM|EVP_PKEY-ML-KEM(7)>,
209 L<X25519|EVP_KEM-X25519(7)>,
210 L<X449|EVP_KEM-X448(7)>,
212 L<EC|EVP_KEM-EC(7)>.
214 L<RFC9180|https://www.rfc-editor.org/rfc/rfc9180> DHKEM construction.
215 Encapsulation is also supported with L<RSA|EVP_KEM-RSA(7)> keys via the
216 B<RSASVE> construction.
219 hybrid ECDHE (no DHKEM) plus B<ML-KEM> algorithms, but these are intended
224 =item B<-decap>
226 Decode an encapsulated secret, with the use of a B<-private> key, to derive the
227 same shared-secret as that obtained when the secret was encapsulated to the
230 from the file specified with B<-in>.
231 The derived shared-secret is written to the file specified with the B<-secret>
234 L<ML-KEM|EVP_PKEY-ML-KEM(7)>,
235 L<X25519|EVP_KEM-X25519(7)>,
236 L<X448|EVP_KEM-X448(7)>,
238 L<EC|EVP_KEM-EC(7)>.
240 L<RFC9180|https://www.rfc-editor.org/rfc/rfc9180> DHKEM construction.
241 Decapsulation is also supported with L<RSA|EVP_KEM-RSA(7)> keys via the
242 B<RSASVE> construction.
244 =item B<-kemop> I<mode>
246 This option is used with the I<-encap>/I<-decap> commands and specifies the KEM
252 =item B<-kdf> I<algorithm>
255 at present B<TLS1-PRF> and B<HKDF>.
261 =item B<-kdflen> I<length>
265 =item B<-pkeyopt> I<opt>:I<value>
269 =item B<-pkeyopt_passin> I<opt>[:I<passarg>]
274 supported by L<openssl-passphrase-options(1)>.
276 =item B<-hexdump>
280 =item B<-asn1parse>
283 When combined with the B<-verifyrecover> option, this may be useful in case
284 an ASN.1 DER-encoded structure had been signed directly (without hashing it)
287 {- $OpenSSL::safe::opt_engine_item -}
289 {- output_off() if $disabled{"deprecated-3.0"}; "" -}
290 =item B<-engine_impl>
292 When used with the B<-engine> option, it specifies to also use
294 {- output_on() if $disabled{"deprecated-3.0"}; "" -}
296 {- $OpenSSL::safe::opt_r_item -}
298 {- $OpenSSL::safe::opt_provider_item -}
300 {- $OpenSSL::safe::opt_config_item -}
309 Unless otherwise mentioned, the B<-pkeyopt> option supports
310 for all public-key types the C<digest:>I<alg> argument,
313 EVP_get_digestbyname() function for example B<sha256>. This value is not used to
314 hash the input data. It is used (by some algorithms) for sanity-checking the
316 signature (e.g., B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures).
319 if the value of the B<-pkeyopt> option C<digest> argument is B<sha256>,
323 Unless B<-rawin> is used or implied, this command does not hash the input data
330 output size B<EVP_MAX_MD_SIZE>, which currently is 64 bytes.
337 B<pkeyopt> values are supported:
341 =item B<rsa_padding_mode:>I<mode>
343 This sets the RSA padding mode. Acceptable values for I<mode> are B<pkcs1> for
344 PKCS#1 padding, B<none> for no padding, B<oaep>
345 for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS.
348 signed or verified directly instead of using a B<DigestInfo> structure. If a
349 digest is set, then the B<DigestInfo> structure is used and its length
352 Note, for B<pkcs1> padding, as a protection against the Bleichenbacher attack,
353 the decryption will not fail in case of padding check failures. Use B<none>
357 For B<oaep> mode only encryption and decryption is supported.
359 For B<x931> if the digest type is set it is used to format the block data
363 For B<pss> mode only sign and verify are supported and the digest type must be
366 =item B<rsa_pss_saltlen:>I<len>
368 For B<pss> mode only this option specifies the salt length. Three special
369 values are supported: B<digest> sets the salt length to the digest length,
370 B<max> sets the salt length to the maximum permissible value. When verifying
371 B<auto> causes the salt length to be automatically determined based on the
372 B<PSS> block structure.
374 =item B<rsa_mgf1_md:>I<digest>
379 =item B<rsa_oaep_md:>I<digest>
384 =item B<rsa_pkcs1_implicit_rejection:>I<flag>
392 errors in a side-channel free manner.
396 =head1 RSA-PSS ALGORITHM
398 The RSA-PSS algorithm is a restricted version of the RSA algorithm which only
400 additional B<-pkeyopt> values are supported:
404 =item B<rsa_padding_mode:>I<mode>, B<rsa_pss_saltlen:>I<len>,
405 B<rsa_mgf1_md:>I<digest>
407 These have the same meaning as the B<RSA> algorithm with some additional
408 restrictions. The padding mode can only be set to B<pss> which is the
421 there are no additional B<-pkeyopt> options other than B<digest>. The SHA256
427 B<-pkeyopt> options.
433 for the B<-pkeyopt> B<digest> option.
440 =head2 SLH-DSA ALGORITHMS
442 …-DSA algorithms (SLH-DSA-SHA2-128s, SLH-DSA-SHA2-128f, SLH-DSA-SHA2-192s, SLH-DSA-SHA2-192f, SLH-D…
446 =item B<-sign>
448 Sign the input data using an SLH-DSA private key. For example:
450 $ openssl pkeyutl -sign -in file.txt -inkey slhdsa.pem -out sig
452 =item B<-verify>
454 Verify the signature using an SLH-DSA public key. For example:
456 $ openssl pkeyutl -verify -in file.txt -inkey slhdsa.pem -sigfile sig
460 See L<EVP_PKEY-SLH-DSA(7)> and L<EVP_SIGNATURE-SLH-DSA(7)> for additional details about the SLH-DSA…
462 =head1 ML-DSA-44, ML-DSA-65 AND ML-DSA-87 ALGORITHMS
464 The ML-DSA algorithms are post-quantum signature algorithms that support signing and verification o…
465 No preliminary hashing is performed. When using ML-DSA with pkeyutl, the following options are avai…
469 =item B<-sign>
471 Sign the input data using an ML-DSA private key. For example:
473 $ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig
475 =item B<-verify>
477 Verify the signature using an ML-DSA public key. For example:
479 $ openssl pkeyutl -verify -in file.txt -inkey mldsa65.pem -sigfile sig
481 =item B<-pkeyopt> I<opt>:I<value>
483 Additional options for ML-DSA signing and verification:
487 =item B<message-encoding>:I<value>
489 …is processed before signing. Valid values are described in L<EVP_SIGNATURE-ML-DSA(7)>. For example:
491 $ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt message-encoding:1
493 =item B<test-entropy>:I<value>
497 …$ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt test-entropy:abcdefghijk…
499 =item B<hextest-entropy>:I<value>
503 …$ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt hextest-entropy:00010203…
505 =item B<deterministic>:I<value>
509 $ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt deterministic:1
511 =item B<mu>:I<value>
513 Specifies the mu parameter. For example:
515 $ echo -n "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" >file.txt
516 $ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt mu:1
520 =item B<context-string>:I<string>
524 $ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt context-string:mycontext
525 …$ openssl pkeyutl -verify -in file.txt -inkey mldsa65.pem -sigfile sig -pkeyopt context-string:myc…
527 =item B<hexcontext-string>:I<string>
531 …$ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt hexcontext-string:6d7963…
535 The signing operation supports a B<deterministic>:I<bool> option,
540 entropy value via the B<hextest-entropy>:I<value> parameter.
541 Deterministic B<ML-DSA> signing should only be used in tests.
543 See L<EVP_SIGNATURE-ML-DSA(7)> for additional details about the ML-DSA algorithms and their impleme…
545 =head1 ML-KEM-512, ML-KEM-768 AND ML-KEM-1024 ALGORITHMS
547 The ML-KEM algorithms support encapsulation and decapsulation only.
548 The encapsulation operation supports a B<hexikme>:I<entropy> option,
549 with I<entropy> the 64 hexadecimal digit encoding of a 32-byte value.
553 See L<EVP_KEM-ML-KEM(7)> for additional detail.
570 be passed in. The following B<-pkeyopt> value is supported:
574 =item B<distid:>I<string>
580 =item B<hexdistid:>I<hex_string>
593 openssl pkeyutl -sign -in file -inkey key.pem -out sig
597 openssl pkeyutl -verifyrecover -in sig -inkey key.pem
601 openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
605 openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
609 openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
611 Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and
614 openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
615 -pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
617 Derive a key using B<scrypt> where the password is read from command line:
619 openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass \
620 -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1
624 openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass:env:MYPASS \
625 -pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1
629 openssl pkeyutl -sign -in file -inkey sm2.key -out sig -rawin -digest sm3 \
630 -pkeyopt distid:someid
634 openssl pkeyutl -verify -certin -in file -inkey sm2.cert -sigfile sig \
635 -rawin -digest sm3 -pkeyopt distid:someid
639 openssl pkeyutl -decrypt -in file -inkey key.pem -out secret \
640 -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
642 Create an ML-DSA key pair and sign data with a specific context string:
644 $ openssl genpkey -algorithm ML-DSA-65 -out mldsa65.pem
645 $ openssl pkeyutl -sign -in file.txt -inkey mldsa65.pem -out sig -pkeyopt context-string:example
647 Verify a signature using ML-DSA with the same context string:
649 …$ openssl pkeyutl -verify -in file.txt -inkey mldsa65.pem -sigfile sig -pkeyopt context-string:exa…
651 Generate an ML-KEM key pair and use it for encapsulation:
653 $ openssl genpkey -algorithm ML-KEM-768 -out mlkem768.pem
654 $ openssl pkey -in mlkem768.pem -pubout -out mlkem768_pub.pem
655 $ openssl pkeyutl -encap -inkey mlkem768_pub.pem -pubin -out ciphertext -secret shared_secret.bin
657 Decapsulate a shared secret using an ML-KEM private key:
659 $ openssl pkeyutl -decap -inkey mlkem768.pem -in ciphertext -secret decapsulated_secret.bin
661 Create an SLH-DSA key pair and sign data:
663 $ openssl genpkey -algorithm SLH-DSA-SHA2-128s -out slh-dsa.pem
664 $ openssl pkeyutl -sign -in file.txt -inkey slh-dsa.pem -out sig
666 Verify a signature using SLH-DSA:
668 $ openssl pkeyutl -verify -in file.txt -inkey slh-dsa.pem -sigfile sig
673 L<openssl-genpkey(1)>,
674 L<openssl-pkey(1)>,
675 L<openssl-rsautl(1)>
676 L<openssl-dgst(1)>,
677 L<openssl-rsa(1)>,
678 L<openssl-genrsa(1)>,
679 L<openssl-kdf(1)>
686 the B<-digest> option implies B<-rawin>, and these two options are
689 Also since OpenSSL 3.5, the B<-kemop> option is no longer required for any of
690 the supported algorithms, the only supported B<mode> is now the default.
692 The B<-engine> option was deprecated in OpenSSL 3.0.
696 Copyright 2006-2025 The OpenSSL Project Authors. All Rights Reserved.