Lines Matching +full:key +full:- +full:value

1 .\" -*- mode: troff; coding: utf-8 -*-
57 .IX Title "OPENSSL-PKEYUTL 1ossl"
58 .TH OPENSSL-PKEYUTL 1ossl 2025-09-30 3.5.4 OpenSSL
64 openssl\-pkeyutl \- asymmetric key command
68 [\fB\-help\fR]
69 [\fB\-in\fR \fIfile\fR]
70 [\fB\-rawin\fR]
71 [\fB\-digest\fR \fIalgorithm\fR]
72 [\fB\-out\fR \fIfile\fR]
73 [\fB\-secret\fR \fIfile\fR]
74 [\fB\-sigfile\fR \fIfile\fR]
75 [\fB\-inkey\fR \fIfilename\fR|\fIuri\fR]
76 [\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR]
77 [\fB\-passin\fR \fIarg\fR]
78 [\fB\-pubin\fR]
79 [\fB\-certin\fR]
80 [\fB\-rev\fR]
81 [\fB\-sign\fR]
82 [\fB\-verify\fR]
83 [\fB\-verifyrecover\fR]
84 [\fB\-encrypt\fR]
85 [\fB\-decrypt\fR]
86 [\fB\-derive\fR]
87 [\fB\-peerkey\fR \fIfile\fR]
88 [\fB\-peerform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR]
89 [\fB\-encap\fR]
90 [\fB\-decap\fR]
91 [\fB\-kdf\fR \fIalgorithm\fR]
92 [\fB\-kdflen\fR \fIlength\fR]
93 [\fB\-kemop\fR \fImode\fR]
94 [\fB\-pkeyopt\fR \fIopt\fR:\fIvalue\fR]
95 [\fB\-pkeyopt_passin\fR \fIopt\fR[:\fIpassarg\fR]]
96 [\fB\-hexdump\fR]
97 [\fB\-asn1parse\fR]
98 [\fB\-engine\fR \fIid\fR]
99 [\fB\-engine_impl\fR]
100 [\fB\-rand\fR \fIfiles\fR]
101 [\fB\-writerand\fR \fIfile\fR]
102 [\fB\-provider\fR \fIname\fR]
103 [\fB\-provider\-path\fR \fIpath\fR]
104 [\fB\-provparam\fR \fI[name:]key=value\fR]
105 [\fB\-propquery\fR \fIpropq\fR]
106 [\fB\-config\fR \fIconfigfile\fR]
109 This command can be used to perform low-level operations
112 By default the signing operation (see \fB\-sign\fR option) is assumed.
115 .IP \fB\-help\fR 4
116 .IX Item "-help"
118 .IP "\fB\-in\fR \fIfilename\fR" 4
119 .IX Item "-in filename"
122 .IP \fB\-rawin\fR 4
123 .IX Item "-rawin"
127 the user can specify a digest algorithm by using the \fB\-digest\fR option.
131 This option can only be used with \fB\-sign\fR and \fB\-verify\fR.
135 The \fB\-digest\fR option implies \fB\-rawin\fR since OpenSSL 3.5.
136 .IP "\fB\-digest\fR \fIalgorithm\fR" 4
137 .IX Item "-digest algorithm"
138 This option can only be used with \fB\-sign\fR and \fB\-verify\fR.
140 before signing or verifying it with the input key. This option could be omitted
143 is omitted but the signature algorithm requires one and the \fB\-rawin\fR option
144 is given, a default value will be used (see \fB\-rawin\fR for details).
145 If this option is present, then the \fB\-rawin\fR option
149 so the \fB\-digest\fR option cannot be used with EdDSA.
150 .IP "\fB\-out\fR \fIfilename\fR" 4
151 .IX Item "-out filename"
153 .IP "\fB\-secret\fR \fIfilename\fR" 4
154 .IX Item "-secret filename"
155 Specifies the shared-secret output filename for when performing encapsulation
156 via the \fB\-encap\fR option or decapsulation via the \fB\-decap\fR option.
157 The \fB\-encap\fR option also produces a separate (public) ciphertext output which
158 is by default written to standard output, but being \fIbinary\fR non-text data,
159 is typically also redirected to a file selected via the \fI\-out\fR option.
160 .IP "\fB\-sigfile\fR \fIfile\fR" 4
161 .IX Item "-sigfile file"
162 Signature file, required and allowed for \fB\-verify\fR operations only.
163 .IP "\fB\-inkey\fR \fIfilename\fR|\fIuri\fR" 4
164 .IX Item "-inkey filename|uri"
165 The input key, by default it should be a private key.
166 .IP "\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR" 4
167 .IX Item "-keyform DER|PEM|P12|ENGINE"
168 The key format; unspecified by default.
169 See \fBopenssl\-format\-options\fR\|(1) for details.
170 .IP "\fB\-passin\fR \fIarg\fR" 4
171 .IX Item "-passin arg"
172 The input key password source. For more information about the format of \fIarg\fR
173 see \fBopenssl\-passphrase\-options\fR\|(1).
174 .IP \fB\-pubin\fR 4
175 .IX Item "-pubin"
176 By default a private key is read from the key input.
177 With this option a public key is read instead.
178 If the input contains no public key but a private key, its public part is used.
179 .IP \fB\-certin\fR 4
180 .IX Item "-certin"
181 The input is a certificate containing a public key.
182 .IP \fB\-rev\fR 4
183 .IX Item "-rev"
185 (such as CryptoAPI) which represent the buffer in little-endian format.
186 This cannot be used in conjunction with \fB\-rawin\fR.
187 .IP \fB\-sign\fR 4
188 .IX Item "-sign"
189 Sign the input data and output the signed result. This requires a private key.
191 when applicable, see the \fB\-rawin\fR and \fB\-digest\fR options for details.
192 Otherwise, the input data given with the \fB\-in\fR option is assumed to already
193 be a digest, but this may then require an additional \fB\-pkeyopt\fR \f(CW\*(C`digest:\*(C'\fR\fImd…
195 Even for other algorithms like ECDSA, where the additional \fB\-pkeyopt\fR option
198 .IP \fB\-verify\fR 4
199 .IX Item "-verify"
200 Verify the input data against the signature given with the \fB\-sigfile\fR option
202 The input data given with the \fB\-in\fR option is assumed to be a hash value
203 unless the \fB\-rawin\fR option is specified or implied.
205 from the signature or take a default value, it should also be specified.
206 .IP \fB\-verifyrecover\fR 4
207 .IX Item "-verifyrecover"
209 For example, in case of RSA PKCS#1 the recovered data is the \fBEMSA\-PKCS\-v1_5\fR
210 DER encoding of the digest algorithm OID and value as specified in
211 RFC8017 Section 9.2 <https://datatracker.ietf.org/doc/html/rfc8017#section-9.2>.
213 Note that here the input given with the \fB\-in\fR option is not a signature input
214 (as with the \fB\-sign\fR and \fB\-verify\fR options) but a signature output value,
215 typically produced using the \fB\-sign\fR option.
218 .IP \fB\-encrypt\fR 4
219 .IX Item "-encrypt"
220 Encrypt the input data using a public key.
221 .IP \fB\-decrypt\fR 4
222 .IX Item "-decrypt"
223 Decrypt the input data using a private key.
224 .IP \fB\-derive\fR 4
225 .IX Item "-derive"
226 Derive a shared secret using own private (EC)DH key and peer key.
227 .IP "\fB\-peerkey\fR \fIfile\fR" 4
228 .IX Item "-peerkey file"
229 File containing the peer public or private (EC)DH key
230 to use with the key derivation (agreement) operation.
231 Its type must match the type of the own private key given with \fB\-inkey\fR.
232 .IP "\fB\-peerform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR" 4
233 .IX Item "-peerform DER|PEM|P12|ENGINE"
234 The peer key format; unspecified by default.
235 See \fBopenssl\-format\-options\fR\|(1) for details.
236 .IP \fB\-encap\fR 4
237 .IX Item "-encap"
238 Use a Key Encapsulation Mechanism (\fBKEM\fR) to \fBencapsulate\fR a shared-secret to
239 a peer's \fBpublic\fR key.
240 The encapsulated result (or ciphertext, non-text binary data) is written to
241 standard output by default, or else to the file specified with \fI\-out\fR.
242 The \fI\-secret\fR option must also be provided to specify the output file for the
243 derived shared-secret value generated in the encapsulation process.
244 Encapsulation is supported with a number of public key algorithms, currently:
245 ML-KEM,
251 RFC9180 <https://www.rfc-editor.org/rfc/rfc9180> DHKEM construction.
256 hybrid ECDHE (no DHKEM) plus \fBML-KEM\fR algorithms, but these are intended
258 There are in any case no standard public and private key formats for the hybrid
259 algorithms, so it is not possible to provide the required key material.
260 .IP \fB\-decap\fR 4
261 .IX Item "-decap"
262 Decode an encapsulated secret, with the use of a \fB\-private\fR key, to derive the
263 same shared-secret as that obtained when the secret was encapsulated to the
264 corresponding public key.
266 from the file specified with \fB\-in\fR.
267 The derived shared-secret is written to the file specified with the \fB\-secret\fR
269 Decapsulation is supported with a number of public key algorithms, currently:
270 ML-KEM,
276 RFC9180 <https://www.rfc-editor.org/rfc/rfc9180> DHKEM construction.
279 .IP "\fB\-kemop\fR \fImode\fR" 4
280 .IX Item "-kemop mode"
281 This option is used with the \fI\-encap\fR/\fI\-decap\fR commands and specifies the KEM
282 \&\fImode\fR specific for the key algorithm when there is no default way to
283 encapsulate and decapsulate shared secrets with the chosen key type.
286 .IP "\fB\-kdf\fR \fIalgorithm\fR" 4
287 .IX Item "-kdf algorithm"
288 Use key derivation function \fIalgorithm\fR.  The supported algorithms are
289 at present \fBTLS1\-PRF\fR and \fBHKDF\fR.
294 .IP "\fB\-kdflen\fR \fIlength\fR" 4
295 .IX Item "-kdflen length"
297 .IP "\fB\-pkeyopt\fR \fIopt\fR:\fIvalue\fR" 4
298 .IX Item "-pkeyopt opt:value"
299 Public key options specified as opt:value. See NOTES below for more details.
300 .IP "\fB\-pkeyopt_passin\fR \fIopt\fR[:\fIpassarg\fR]" 4
301 .IX Item "-pkeyopt_passin opt[:passarg]"
302 Allows reading a public key option \fIopt\fR from stdin or a password source.
304 stdin.  Alternatively, \fIpassarg\fR can be specified which can be any value
305 supported by \fBopenssl\-passphrase\-options\fR\|(1).
306 .IP \fB\-hexdump\fR 4
307 .IX Item "-hexdump"
309 .IP \fB\-asn1parse\fR 4
310 .IX Item "-asn1parse"
312 When combined with the \fB\-verifyrecover\fR option, this may be useful in case
313 an ASN.1 DER-encoded structure had been signed directly (without hashing it)
315 .IP "\fB\-engine\fR \fIid\fR" 4
316 .IX Item "-engine id"
319 .IP \fB\-engine_impl\fR 4
320 .IX Item "-engine_impl"
321 When used with the \fB\-engine\fR option, it specifies to also use
323 .IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4
324 .IX Item "-rand files, -writerand file"
326 .IP "\fB\-provider\fR \fIname\fR" 4
327 .IX Item "-provider name"
329 .IP "\fB\-provider\-path\fR \fIpath\fR" 4
330 .IX Item "-provider-path path"
331 .IP "\fB\-provparam\fR \fI[name:]key=value\fR" 4
332 .IX Item "-provparam [name:]key=value"
333 .IP "\fB\-propquery\fR \fIpropq\fR" 4
334 .IX Item "-propquery propq"
337 .IP "\fB\-config\fR \fIconfigfile\fR" 4
338 .IX Item "-config configfile"
342 The operations and options supported vary according to the key algorithm
345 Unless otherwise mentioned, the \fB\-pkeyopt\fR option supports
346 for all public-key types the \f(CW\*(C`digest:\*(C'\fR\fIalg\fR argument,
348 The value \fIalg\fR should represent a digest name as used in the
349 \&\fBEVP_get_digestbyname()\fR function for example \fBsha256\fR. This value is not used to
350 hash the input data. It is used (by some algorithms) for sanity-checking the
355 if the value of the \fB\-pkeyopt\fR option \f(CW\*(C`digest\*(C'\fR argument is \fBsha256\fR,
356 the signature or verification input should be the 32 bytes long binary value
359 Unless \fB\-rawin\fR is used or implied, this command does not hash the input data
361 Depending on the key type, signature type, and mode of padding, the maximum
363 than the key modulus. In case of ECDSA and DSA the data should not be longer
387 value has correct PKCS#1 v1.5 padding.
401 \&\fBmax\fR sets the salt length to the maximum permissible value. When verifying
420 errors in a side-channel free manner.
421 .SH "RSA-PSS ALGORITHM"
422 .IX Header "RSA-PSS ALGORITHM"
423 The RSA-PSS algorithm is a restricted version of the RSA algorithm which only
425 additional \fB\-pkeyopt\fR values are supported:
430 default value.
432 If the key has parameter restrictions then the digest, MGF1
435 value less than the minimum restriction.
439 there are no additional \fB\-pkeyopt\fR options other than \fBdigest\fR. The SHA256
444 \&\fB\-pkeyopt\fR options.
449 for the \fB\-pkeyopt\fR \fBdigest\fR option.
452 The X25519 and X448 algorithms support key derivation only. Currently there are
454 .SS "SLH-DSA ALGORITHMS"
455 .IX Subsection "SLH-DSA ALGORITHMS"
456 …-DSA algorithms (SLH\-DSA\-SHA2\-128s, SLH\-DSA\-SHA2\-128f, SLH\-DSA\-SHA2\-192s, SLH\-DSA\-SHA2\…
457 .IP \fB\-sign\fR 4
458 .IX Item "-sign"
459 Sign the input data using an SLH-DSA private key. For example:
462 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey slhdsa.pem \-out sig
464 .IP \fB\-verify\fR 4
465 .IX Item "-verify"
466 Verify the signature using an SLH-DSA public key. For example:
469 \&  $ openssl pkeyutl \-verify \-in file.txt \-inkey slhdsa.pem \-sigfile sig
472 See \fBEVP_PKEY\-SLH\-DSA\fR\|(7) and \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7) for additional details abo…
473 .SH "ML\-DSA\-44, ML\-DSA\-65 AND ML\-DSA\-87 ALGORITHMS"
474 .IX Header "ML-DSA-44, ML-DSA-65 AND ML-DSA-87 ALGORITHMS"
475 The ML-DSA algorithms are post-quantum signature algorithms that support signing and verification o…
476 No preliminary hashing is performed. When using ML-DSA with pkeyutl, the following options are avai…
477 .IP \fB\-sign\fR 4
478 .IX Item "-sign"
479 Sign the input data using an ML-DSA private key. For example:
482 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig
484 .IP \fB\-verify\fR 4
485 .IX Item "-verify"
486 Verify the signature using an ML-DSA public key. For example:
489 \&  $ openssl pkeyutl \-verify \-in file.txt \-inkey mldsa65.pem \-sigfile sig
491 .IP "\fB\-pkeyopt\fR \fIopt\fR:\fIvalue\fR" 4
492 .IX Item "-pkeyopt opt:value"
493 Additional options for ML-DSA signing and verification:
495 .IP \fBmessage-encoding\fR:\fIvalue\fR 4
496 .IX Item "message-encoding:value"
497 … processed before signing. Valid values are described in \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7). For ex…
500 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt message\-encodin…
502 .IP \fBtest-entropy\fR:\fIvalue\fR 4
503 .IX Item "test-entropy:value"
504 Specifies a test entropy value for deterministic signing. For example:
507 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt test\-entropy:ab…
509 .IP \fBhextest-entropy\fR:\fIvalue\fR 4
510 .IX Item "hextest-entropy:value"
511 Specifies a test entropy value in hex format. For example:
514 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt hextest\-entropy…
516 .IP \fBdeterministic\fR:\fIvalue\fR 4
517 .IX Item "deterministic:value"
521 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt deterministic:1
523 .IP \fBmu\fR:\fIvalue\fR 4
524 .IX Item "mu:value"
528 \&  $ echo \-n "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" >file.txt
529 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt mu:1
534 .IP \fBcontext-string\fR:\fIstring\fR 4
535 .IX Item "context-string:string"
539 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt context\-string:…
540 \&  $ openssl pkeyutl \-verify \-in file.txt \-inkey mldsa65.pem \-sigfile sig \-pkeyopt context\-s…
542 .IP \fBhexcontext-string\fR:\fIstring\fR 4
543 .IX Item "hexcontext-string:string"
547 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt hexcontext\-stri…
553 By default, or if the \fIbool\fR is \f(CW0\fR a random entropy value is used.
555 entropy value via the \fBhextest-entropy\fR:\fIvalue\fR parameter.
556 Deterministic \fBML-DSA\fR signing should only be used in tests.
558 See \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7) for additional details about the ML-DSA algorithms and their …
559 .SH "ML\-KEM\-512, ML\-KEM\-768 AND ML\-KEM\-1024 ALGORITHMS"
560 .IX Header "ML-KEM-512, ML-KEM-768 AND ML-KEM-1024 ALGORITHMS"
561 The ML-KEM algorithms support encapsulation and decapsulation only.
563 with \fIentropy\fR the 64 hexadecimal digit encoding of a 32\-byte value.
567 See \fBEVP_KEM\-ML\-KEM\fR\|(7) for additional detail.
582 be passed in. The following \fB\-pkeyopt\fR value is supported:
593 should be a valid hexadecimal value.
596 Sign some data using a private key:
599 \& openssl pkeyutl \-sign \-in file \-inkey key.pem \-out sig
602 Recover the signed data (e.g. if an RSA key is used):
605 \& openssl pkeyutl \-verifyrecover \-in sig \-inkey key.pem
608 Verify the signature (e.g. a DSA key):
611 \& openssl pkeyutl \-verify \-in file \-sigfile sig \-inkey key.pem
614 Sign data using a message digest value (this is currently only valid for RSA):
617 \& openssl pkeyutl \-sign \-in file \-inkey key.pem \-out sig \-pkeyopt digest:sha256
620 Derive a shared secret value:
623 \& openssl pkeyutl \-derive \-inkey key.pem \-peerkey pubkey.pem \-out secret
630 \& openssl pkeyutl \-kdf TLS1\-PRF \-kdflen 48 \-pkeyopt md:SHA256 \e
631 \&    \-pkeyopt hexsecret:ff \-pkeyopt hexseed:ff \-hexdump
634 Derive a key using \fBscrypt\fR where the password is read from command line:
637 \& openssl pkeyutl \-kdf scrypt \-kdflen 16 \-pkeyopt_passin pass \e
638 \&    \-pkeyopt hexsalt:aabbcc \-pkeyopt N:16384 \-pkeyopt r:8 \-pkeyopt p:1
641 Derive using the same algorithm, but read key from environment variable MYPASS:
644 \& openssl pkeyutl \-kdf scrypt \-kdflen 16 \-pkeyopt_passin pass:env:MYPASS \e
645 \&    \-pkeyopt hexsalt:aabbcc \-pkeyopt N:16384 \-pkeyopt r:8 \-pkeyopt p:1
648 Sign some data using an \fBSM2\fR\|(7) private key and a specific ID:
651 \& openssl pkeyutl \-sign \-in file \-inkey sm2.key \-out sig \-rawin \-digest sm3 \e
652 \&    \-pkeyopt distid:someid
658 \& openssl pkeyutl \-verify \-certin \-in file \-inkey sm2.cert \-sigfile sig \e
659 \&    \-rawin \-digest sm3 \-pkeyopt distid:someid
662 Decrypt some data using a private key with OAEP padding using SHA256:
665 \& openssl pkeyutl \-decrypt \-in file \-inkey key.pem \-out secret \e
666 \&    \-pkeyopt rsa_padding_mode:oaep \-pkeyopt rsa_oaep_md:sha256
669 Create an ML-DSA key pair and sign data with a specific context string:
672 \&  $ openssl genpkey \-algorithm ML\-DSA\-65 \-out mldsa65.pem
673 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt context\-string:…
676 Verify a signature using ML-DSA with the same context string:
679 \&  $ openssl pkeyutl \-verify \-in file.txt \-inkey mldsa65.pem \-sigfile sig \-pkeyopt context\-s…
682 Generate an ML-KEM key pair and use it for encapsulation:
685 \&  $ openssl genpkey \-algorithm ML\-KEM\-768 \-out mlkem768.pem
686 \&  $ openssl pkey \-in mlkem768.pem \-pubout \-out mlkem768_pub.pem
687 \&  $ openssl pkeyutl \-encap \-inkey mlkem768_pub.pem \-pubin \-out ciphertext \-secret shared_sec…
690 Decapsulate a shared secret using an ML-KEM private key:
693 \&  $ openssl pkeyutl \-decap \-inkey mlkem768.pem \-in ciphertext \-secret decapsulated_secret.bin
696 Create an SLH-DSA key pair and sign data:
699 \&  $ openssl genpkey \-algorithm SLH\-DSA\-SHA2\-128s \-out slh\-dsa.pem
700 \&  $ openssl pkeyutl \-sign \-in file.txt \-inkey slh\-dsa.pem \-out sig
703 Verify a signature using SLH-DSA:
706 \&  $ openssl pkeyutl \-verify \-in file.txt \-inkey slh\-dsa.pem \-sigfile sig
711 \&\fBopenssl\-genpkey\fR\|(1),
712 \&\fBopenssl\-pkey\fR\|(1),
713 \&\fBopenssl\-rsautl\fR\|(1)
714 \&\fBopenssl\-dgst\fR\|(1),
715 \&\fBopenssl\-rsa\fR\|(1),
716 \&\fBopenssl\-genrsa\fR\|(1),
717 \&\fBopenssl\-kdf\fR\|(1)
723 the \fB\-digest\fR option implies \fB\-rawin\fR, and these two options are
724 no longer required when signing or verifying with an Ed25519 or Ed448 key.
726 Also since OpenSSL 3.5, the \fB\-kemop\fR option is no longer required for any of
729 The \fB\-engine\fR option was deprecated in OpenSSL 3.0.
732 Copyright 2006\-2025 The OpenSSL Project Authors. All Rights Reserved.