diff options
Diffstat (limited to 'static/freebsd/man1/openssl-pkeyutl.1')
| -rw-r--r-- | static/freebsd/man1/openssl-pkeyutl.1 | 740 |
1 files changed, 740 insertions, 0 deletions
diff --git a/static/freebsd/man1/openssl-pkeyutl.1 b/static/freebsd/man1/openssl-pkeyutl.1 new file mode 100644 index 00000000..251304ae --- /dev/null +++ b/static/freebsd/man1/openssl-pkeyutl.1 @@ -0,0 +1,740 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "OPENSSL-PKEYUTL 1ossl" +.TH OPENSSL-PKEYUTL 1ossl 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-pkeyutl \- asymmetric key command +.SH SYNOPSIS +.IX Header "SYNOPSIS" +\&\fBopenssl\fR \fBpkeyutl\fR +[\fB\-help\fR] +[\fB\-in\fR \fIfile\fR] +[\fB\-rawin\fR] +[\fB\-digest\fR \fIalgorithm\fR] +[\fB\-out\fR \fIfile\fR] +[\fB\-secret\fR \fIfile\fR] +[\fB\-sigfile\fR \fIfile\fR] +[\fB\-inkey\fR \fIfilename\fR|\fIuri\fR] +[\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR] +[\fB\-passin\fR \fIarg\fR] +[\fB\-pubin\fR] +[\fB\-certin\fR] +[\fB\-rev\fR] +[\fB\-sign\fR] +[\fB\-verify\fR] +[\fB\-verifyrecover\fR] +[\fB\-encrypt\fR] +[\fB\-decrypt\fR] +[\fB\-derive\fR] +[\fB\-peerkey\fR \fIfile\fR] +[\fB\-peerform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR] +[\fB\-encap\fR] +[\fB\-decap\fR] +[\fB\-kdf\fR \fIalgorithm\fR] +[\fB\-kdflen\fR \fIlength\fR] +[\fB\-kemop\fR \fImode\fR] +[\fB\-pkeyopt\fR \fIopt\fR:\fIvalue\fR] +[\fB\-pkeyopt_passin\fR \fIopt\fR[:\fIpassarg\fR]] +[\fB\-hexdump\fR] +[\fB\-asn1parse\fR] +[\fB\-engine\fR \fIid\fR] +[\fB\-engine_impl\fR] +[\fB\-rand\fR \fIfiles\fR] +[\fB\-writerand\fR \fIfile\fR] +[\fB\-provider\fR \fIname\fR] +[\fB\-provider\-path\fR \fIpath\fR] +[\fB\-provparam\fR \fI[name:]key=value\fR] +[\fB\-propquery\fR \fIpropq\fR] +[\fB\-config\fR \fIconfigfile\fR] +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This command can be used to perform low\-level operations +on asymmetric (public or private) keys using any supported algorithm. +.PP +By default the signing operation (see \fB\-sign\fR option) is assumed. +.SH OPTIONS +.IX Header "OPTIONS" +.IP \fB\-help\fR 4 +.IX Item "-help" +Print out a usage message. +.IP "\fB\-in\fR \fIfilename\fR" 4 +.IX Item "-in filename" +This specifies the input filename to read data from or standard input +if this option is not specified. +.IP \fB\-rawin\fR 4 +.IX Item "-rawin" +This indicates that the signature or verification input data is raw data, +which is not hashed by any message digest algorithm. +Except with EdDSA, +the user can specify a digest algorithm by using the \fB\-digest\fR option. +For signature algorithms like RSA, DSA and ECDSA, +the default digest algorithm is SHA256. For SM2, it is SM3. +.Sp +This option can only be used with \fB\-sign\fR and \fB\-verify\fR. +For EdDSA (the Ed25519 and Ed448 algorithms) this option +is implied since OpenSSL 3.5, and required in earlier versions. +.Sp +The \fB\-digest\fR option implies \fB\-rawin\fR since OpenSSL 3.5. +.IP "\fB\-digest\fR \fIalgorithm\fR" 4 +.IX Item "-digest algorithm" +This option can only be used with \fB\-sign\fR and \fB\-verify\fR. +It specifies the digest algorithm that is used to hash the input data +before signing or verifying it with the input key. This option could be omitted +if the signature algorithm does not require preprocessing the input through +a pluggable hash function before signing (for instance, EdDSA). If this option +is omitted but the signature algorithm requires one and the \fB\-rawin\fR option +is given, a default value will be used (see \fB\-rawin\fR for details). +If this option is present, then the \fB\-rawin\fR option +is implied since OpenSSL 3.5, and required in earlier versions. +.Sp +At this time, HashEdDSA (the ph or "prehash" variant of EdDSA) is not supported, +so the \fB\-digest\fR option cannot be used with EdDSA. +.IP "\fB\-out\fR \fIfilename\fR" 4 +.IX Item "-out filename" +Specifies the output filename to write to or standard output by default. +.IP "\fB\-secret\fR \fIfilename\fR" 4 +.IX Item "-secret filename" +Specifies the shared\-secret output filename for when performing encapsulation +via the \fB\-encap\fR option or decapsulation via the \fB\-decap\fR option. +The \fB\-encap\fR option also produces a separate (public) ciphertext output which +is by default written to standard output, but being \fIbinary\fR non\-text data, +is typically also redirected to a file selected via the \fI\-out\fR option. +.IP "\fB\-sigfile\fR \fIfile\fR" 4 +.IX Item "-sigfile file" +Signature file, required and allowed for \fB\-verify\fR operations only. +.IP "\fB\-inkey\fR \fIfilename\fR|\fIuri\fR" 4 +.IX Item "-inkey filename|uri" +The input key, by default it should be a private key. +.IP "\fB\-keyform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR" 4 +.IX Item "-keyform DER|PEM|P12|ENGINE" +The key format; unspecified by default. +See \fBopenssl\-format\-options\fR\|(1) for details. +.IP "\fB\-passin\fR \fIarg\fR" 4 +.IX Item "-passin arg" +The input key password source. For more information about the format of \fIarg\fR +see \fBopenssl\-passphrase\-options\fR\|(1). +.IP \fB\-pubin\fR 4 +.IX Item "-pubin" +By default a private key is read from the key input. +With this option a public key is read instead. +If the input contains no public key but a private key, its public part is used. +.IP \fB\-certin\fR 4 +.IX Item "-certin" +The input is a certificate containing a public key. +.IP \fB\-rev\fR 4 +.IX Item "-rev" +Reverse the order of the input buffer. This is useful for some libraries +(such as CryptoAPI) which represent the buffer in little\-endian format. +This cannot be used in conjunction with \fB\-rawin\fR. +.IP \fB\-sign\fR 4 +.IX Item "-sign" +Sign the input data and output the signed result. This requires a private key. +Using a message digest operation along with this is recommended, +when applicable, see the \fB\-rawin\fR and \fB\-digest\fR options for details. +Otherwise, the input data given with the \fB\-in\fR option is assumed to already +be a digest, but this may then require an additional \fB\-pkeyopt\fR \f(CW\*(C`digest:\*(C'\fR\fImd\fR +in some cases (e.g., RSA with the default PKCS#1 padding mode). +Even for other algorithms like ECDSA, where the additional \fB\-pkeyopt\fR option +does not affect signature output, it is recommended, as it enables +checking that the input length is consistent with the intended digest. +.IP \fB\-verify\fR 4 +.IX Item "-verify" +Verify the input data against the signature given with the \fB\-sigfile\fR option +and indicate if the verification succeeded or failed. +The input data given with the \fB\-in\fR option is assumed to be a hash value +unless the \fB\-rawin\fR option is specified or implied. +With raw data, when a digest algorithm is applicable, though it may be inferred +from the signature or take a default value, it should also be specified. +.IP \fB\-verifyrecover\fR 4 +.IX Item "-verifyrecover" +Verify the given signature and output the recovered data (signature payload). +For example, in case of RSA PKCS#1 the recovered data is the \fBEMSA\-PKCS\-v1_5\fR +DER encoding of the digest algorithm OID and value as specified in +RFC8017 Section 9.2 <https://datatracker.ietf.org/doc/html/rfc8017#section-9.2>. +.Sp +Note that here the input given with the \fB\-in\fR option is not a signature input +(as with the \fB\-sign\fR and \fB\-verify\fR options) but a signature output value, +typically produced using the \fB\-sign\fR option. +.Sp +This option is available only for use with RSA keys. +.IP \fB\-encrypt\fR 4 +.IX Item "-encrypt" +Encrypt the input data using a public key. +.IP \fB\-decrypt\fR 4 +.IX Item "-decrypt" +Decrypt the input data using a private key. +.IP \fB\-derive\fR 4 +.IX Item "-derive" +Derive a shared secret using own private (EC)DH key and peer key. +.IP "\fB\-peerkey\fR \fIfile\fR" 4 +.IX Item "-peerkey file" +File containing the peer public or private (EC)DH key +to use with the key derivation (agreement) operation. +Its type must match the type of the own private key given with \fB\-inkey\fR. +.IP "\fB\-peerform\fR \fBDER\fR|\fBPEM\fR|\fBP12\fR|\fBENGINE\fR" 4 +.IX Item "-peerform DER|PEM|P12|ENGINE" +The peer key format; unspecified by default. +See \fBopenssl\-format\-options\fR\|(1) for details. +.IP \fB\-encap\fR 4 +.IX Item "-encap" +Use a Key Encapsulation Mechanism (\fBKEM\fR) to \fBencapsulate\fR a shared\-secret to +a peer\*(Aqs \fBpublic\fR key. +The encapsulated result (or ciphertext, non\-text binary data) is written to +standard output by default, or else to the file specified with \fI\-out\fR. +The \fI\-secret\fR option must also be provided to specify the output file for the +derived shared\-secret value generated in the encapsulation process. +Encapsulation is supported with a number of public key algorithms, currently: +ML\-KEM, +X25519, +X448, +and +EC. +The ECX and EC algorithms use the +RFC9180 <https://www.rfc-editor.org/rfc/rfc9180> DHKEM construction. +Encapsulation is also supported with RSA keys via the +\&\fBRSASVE\fR construction. +.Sp +At the API level, encapsulation and decapsulation are also supported for a few +hybrid ECDHE (no DHKEM) plus \fBML\-KEM\fR algorithms, but these are intended +primarily for use with TLS and should not be used standalone. +There are in any case no standard public and private key formats for the hybrid +algorithms, so it is not possible to provide the required key material. +.IP \fB\-decap\fR 4 +.IX Item "-decap" +Decode an encapsulated secret, with the use of a \fB\-private\fR key, to derive the +same shared\-secret as that obtained when the secret was encapsulated to the +corresponding public key. +The encapsulated secret is by default read from the standard input, or else +from the file specified with \fB\-in\fR. +The derived shared\-secret is written to the file specified with the \fB\-secret\fR +option, which \fImust\fR also be provided. +Decapsulation is supported with a number of public key algorithms, currently: +ML\-KEM, +X25519, +X448, +and +EC. +The ECX and EC algorithms use the +RFC9180 <https://www.rfc-editor.org/rfc/rfc9180> DHKEM construction. +Decapsulation is also supported with RSA keys via the +\&\fBRSASVE\fR construction. +.IP "\fB\-kemop\fR \fImode\fR" 4 +.IX Item "-kemop mode" +This option is used with the \fI\-encap\fR/\fI\-decap\fR commands and specifies the KEM +\&\fImode\fR specific for the key algorithm when there is no default way to +encapsulate and decapsulate shared secrets with the chosen key type. +All the supported algorithms presently support only their default \fImode\fR, and +this option, though available, is not required. +.IP "\fB\-kdf\fR \fIalgorithm\fR" 4 +.IX Item "-kdf algorithm" +Use key derivation function \fIalgorithm\fR. The supported algorithms are +at present \fBTLS1\-PRF\fR and \fBHKDF\fR. +Note: additional parameters and the KDF output length will normally have to be +set for this to work. +See \fBEVP_PKEY_CTX_set_hkdf_md\fR\|(3) and \fBEVP_PKEY_CTX_set_tls1_prf_md\fR\|(3) +for the supported string parameters of each algorithm. +.IP "\fB\-kdflen\fR \fIlength\fR" 4 +.IX Item "-kdflen length" +Set the output length for KDF. +.IP "\fB\-pkeyopt\fR \fIopt\fR:\fIvalue\fR" 4 +.IX Item "-pkeyopt opt:value" +Public key options specified as opt:value. See NOTES below for more details. +.IP "\fB\-pkeyopt_passin\fR \fIopt\fR[:\fIpassarg\fR]" 4 +.IX Item "-pkeyopt_passin opt[:passarg]" +Allows reading a public key option \fIopt\fR from stdin or a password source. +If only \fIopt\fR is specified, the user will be prompted to enter a password on +stdin. Alternatively, \fIpassarg\fR can be specified which can be any value +supported by \fBopenssl\-passphrase\-options\fR\|(1). +.IP \fB\-hexdump\fR 4 +.IX Item "-hexdump" +hex dump the output data. +.IP \fB\-asn1parse\fR 4 +.IX Item "-asn1parse" +Parse the ASN.1 output data to check its DER encoding and print any errors. +When combined with the \fB\-verifyrecover\fR option, this may be useful in case +an ASN.1 DER\-encoded structure had been signed directly (without hashing it) +and when checking a signature in PKCS#1 v1.5 format, which has a DER encoding. +.IP "\fB\-engine\fR \fIid\fR" 4 +.IX Item "-engine id" +See "Engine Options" in \fBopenssl\fR\|(1). +This option is deprecated. +.IP \fB\-engine_impl\fR 4 +.IX Item "-engine_impl" +When used with the \fB\-engine\fR option, it specifies to also use +engine \fIid\fR for crypto operations. +.IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4 +.IX Item "-rand files, -writerand file" +See "Random State Options" in \fBopenssl\fR\|(1) for details. +.IP "\fB\-provider\fR \fIname\fR" 4 +.IX Item "-provider name" +.PD 0 +.IP "\fB\-provider\-path\fR \fIpath\fR" 4 +.IX Item "-provider-path path" +.IP "\fB\-provparam\fR \fI[name:]key=value\fR" 4 +.IX Item "-provparam [name:]key=value" +.IP "\fB\-propquery\fR \fIpropq\fR" 4 +.IX Item "-propquery propq" +.PD +See "Provider Options" in \fBopenssl\fR\|(1), \fBprovider\fR\|(7), and \fBproperty\fR\|(7). +.IP "\fB\-config\fR \fIconfigfile\fR" 4 +.IX Item "-config configfile" +See "Configuration Option" in \fBopenssl\fR\|(1). +.SH NOTES +.IX Header "NOTES" +The operations and options supported vary according to the key algorithm +and its implementation. The OpenSSL operations and options are indicated below. +.PP +Unless otherwise mentioned, the \fB\-pkeyopt\fR option supports +for all public\-key types the \f(CW\*(C`digest:\*(C'\fR\fIalg\fR argument, +which specifies the digest in use for the signing and verification operations. +The value \fIalg\fR should represent a digest name as used in the +\&\fBEVP_get_digestbyname()\fR function for example \fBsha256\fR. This value is not used to +hash the input data. It is used (by some algorithms) for sanity\-checking the +lengths of data passed in and for creating the structures that make up the +signature (e.g., \fBDigestInfo\fR in RSASSA PKCS#1 v1.5 signatures). +.PP +For instance, +if the value of the \fB\-pkeyopt\fR option \f(CW\*(C`digest\*(C'\fR argument is \fBsha256\fR, +the signature or verification input should be the 32 bytes long binary value +of the SHA256 hash function output. +.PP +Unless \fB\-rawin\fR is used or implied, this command does not hash the input data +but rather it will use the data directly as input to the signature algorithm. +Depending on the key type, signature type, and mode of padding, the maximum +sensible lengths of input data differ. With RSA the signed data cannot be longer +than the key modulus. In case of ECDSA and DSA the data should not be longer +than the field size, otherwise it will be silently truncated to the field size. +In any event the input size must not be larger than the largest supported digest +output size \fBEVP_MAX_MD_SIZE\fR, which currently is 64 bytes. +.SH "RSA ALGORITHM" +.IX Header "RSA ALGORITHM" +The RSA algorithm generally supports the encrypt, decrypt, sign, +verify and verifyrecover operations. However, some padding modes +support only a subset of these operations. The following additional +\&\fBpkeyopt\fR values are supported: +.IP \fBrsa_padding_mode:\fR\fImode\fR 4 +.IX Item "rsa_padding_mode:mode" +This sets the RSA padding mode. Acceptable values for \fImode\fR are \fBpkcs1\fR for +PKCS#1 padding, \fBnone\fR for no padding, \fBoaep\fR +for \fBOAEP\fR mode, \fBx931\fR for X9.31 mode and \fBpss\fR for PSS. +.Sp +In PKCS#1 padding, if the message digest is not set, then the supplied data is +signed or verified directly instead of using a \fBDigestInfo\fR structure. If a +digest is set, then the \fBDigestInfo\fR structure is used and its length +must correspond to the digest type. +.Sp +Note, for \fBpkcs1\fR padding, as a protection against the Bleichenbacher attack, +the decryption will not fail in case of padding check failures. Use \fBnone\fR +and manual inspection of the decrypted message to verify if the decrypted +value has correct PKCS#1 v1.5 padding. +.Sp +For \fBoaep\fR mode only encryption and decryption is supported. +.Sp +For \fBx931\fR if the digest type is set it is used to format the block data +otherwise the first byte is used to specify the X9.31 digest ID. Sign, +verify and verifyrecover are can be performed in this mode. +.Sp +For \fBpss\fR mode only sign and verify are supported and the digest type must be +specified. +.IP \fBrsa_pss_saltlen:\fR\fIlen\fR 4 +.IX Item "rsa_pss_saltlen:len" +For \fBpss\fR mode only this option specifies the salt length. Three special +values are supported: \fBdigest\fR sets the salt length to the digest length, +\&\fBmax\fR sets the salt length to the maximum permissible value. When verifying +\&\fBauto\fR causes the salt length to be automatically determined based on the +\&\fBPSS\fR block structure. +.IP \fBrsa_mgf1_md:\fR\fIdigest\fR 4 +.IX Item "rsa_mgf1_md:digest" +For PSS and OAEP padding sets the MGF1 digest. If the MGF1 digest is not +explicitly set in PSS mode then the signing digest is used. +.IP \fBrsa_oaep_md:\fR\fIdigest\fR 4 +.IX Item "rsa_oaep_md:digest" +Sets the digest used for the OAEP hash function. If not explicitly set then +SHA256 is used. +.IP \fBrsa_pkcs1_implicit_rejection:\fR\fIflag\fR 4 +.IX Item "rsa_pkcs1_implicit_rejection:flag" +Disables (when set to 0) or enables (when set to 1) the use of implicit +rejection with PKCS#1 v1.5 decryption. When enabled (the default), as a +protection against Bleichenbacher attack, the library will generate a +deterministic random plaintext that it will return to the caller in case +of padding check failure. +When disabled, it\*(Aqs the callers\*(Aq responsibility to handle the returned +errors in a side\-channel free manner. +.SH "RSA\-PSS ALGORITHM" +.IX Header "RSA-PSS ALGORITHM" +The RSA\-PSS algorithm is a restricted version of the RSA algorithm which only +supports the sign and verify operations with PSS padding. The following +additional \fB\-pkeyopt\fR values are supported: +.IP "\fBrsa_padding_mode:\fR\fImode\fR, \fBrsa_pss_saltlen:\fR\fIlen\fR, \fBrsa_mgf1_md:\fR\fIdigest\fR" 4 +.IX Item "rsa_padding_mode:mode, rsa_pss_saltlen:len, rsa_mgf1_md:digest" +These have the same meaning as the \fBRSA\fR algorithm with some additional +restrictions. The padding mode can only be set to \fBpss\fR which is the +default value. +.Sp +If the key has parameter restrictions then the digest, MGF1 +digest and salt length are set to the values specified in the parameters. +The digest and MG cannot be changed and the salt length cannot be set to a +value less than the minimum restriction. +.SH "DSA ALGORITHM" +.IX Header "DSA ALGORITHM" +The DSA algorithm supports signing and verification operations only. Currently +there are no additional \fB\-pkeyopt\fR options other than \fBdigest\fR. The SHA256 +digest is assumed by default. +.SH "DH ALGORITHM" +.IX Header "DH ALGORITHM" +The DH algorithm only supports the derivation operation and no additional +\&\fB\-pkeyopt\fR options. +.SH "EC ALGORITHM" +.IX Header "EC ALGORITHM" +The EC algorithm supports sign, verify and derive operations. The sign and +verify operations use ECDSA and derive uses ECDH. SHA256 is assumed by default +for the \fB\-pkeyopt\fR \fBdigest\fR option. +.SH "X25519 AND X448 ALGORITHMS" +.IX Header "X25519 AND X448 ALGORITHMS" +The X25519 and X448 algorithms support key derivation only. Currently there are +no additional options. +.SS "SLH\-DSA ALGORITHMS" +.IX Subsection "SLH-DSA ALGORITHMS" +The SLH\-DSA algorithms (SLH\-DSA\-SHA2\-128s, SLH\-DSA\-SHA2\-128f, SLH\-DSA\-SHA2\-192s, SLH\-DSA\-SHA2\-192f, SLH\-DSA\-SHA2\-256s, SLH\-DSA\-SHA2\-256f) are post\-quantum signature algorithms. When using SLH\-DSA with pkeyutl, the following options are available: +.IP \fB\-sign\fR 4 +.IX Item "-sign" +Sign the input data using an SLH\-DSA private key. For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey slhdsa.pem \-out sig +.Ve +.IP \fB\-verify\fR 4 +.IX Item "-verify" +Verify the signature using an SLH\-DSA public key. For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-verify \-in file.txt \-inkey slhdsa.pem \-sigfile sig +.Ve +.PP +See \fBEVP_PKEY\-SLH\-DSA\fR\|(7) and \fBEVP_SIGNATURE\-SLH\-DSA\fR\|(7) for additional details about the SLH\-DSA algorithm and its implementation. +.SH "ML\-DSA\-44, ML\-DSA\-65 AND ML\-DSA\-87 ALGORITHMS" +.IX Header "ML-DSA-44, ML-DSA-65 AND ML-DSA-87 ALGORITHMS" +The ML\-DSA algorithms are post\-quantum signature algorithms that support signing and verification of "raw" messages. +No preliminary hashing is performed. When using ML\-DSA with pkeyutl, the following options are available: +.IP \fB\-sign\fR 4 +.IX Item "-sign" +Sign the input data using an ML\-DSA private key. For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig +.Ve +.IP \fB\-verify\fR 4 +.IX Item "-verify" +Verify the signature using an ML\-DSA public key. For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-verify \-in file.txt \-inkey mldsa65.pem \-sigfile sig +.Ve +.IP "\fB\-pkeyopt\fR \fIopt\fR:\fIvalue\fR" 4 +.IX Item "-pkeyopt opt:value" +Additional options for ML\-DSA signing and verification: +.RS 4 +.IP \fBmessage\-encoding\fR:\fIvalue\fR 4 +.IX Item "message-encoding:value" +Specifies the message encoding mode used for signing. This controls how the input message is processed before signing. Valid values are described in \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7). For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt message\-encoding:1 +.Ve +.IP \fBtest\-entropy\fR:\fIvalue\fR 4 +.IX Item "test-entropy:value" +Specifies a test entropy value for deterministic signing. For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt test\-entropy:abcdefghijklmnopqrstuvwxyz012345 +.Ve +.IP \fBhextest\-entropy\fR:\fIvalue\fR 4 +.IX Item "hextest-entropy:value" +Specifies a test entropy value in hex format. For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt hextest\-entropy:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f +.Ve +.IP \fBdeterministic\fR:\fIvalue\fR 4 +.IX Item "deterministic:value" +Enables deterministic signing. For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt deterministic:1 +.Ve +.IP \fBmu\fR:\fIvalue\fR 4 +.IX Item "mu:value" +Specifies the mu parameter. For example: +.Sp +.Vb 2 +\& $ echo \-n "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" >file.txt +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt mu:1 +.Ve +.RE +.RS 4 +.RE +.IP \fBcontext\-string\fR:\fIstring\fR 4 +.IX Item "context-string:string" +Specifies a context string for both signing and verification operations. The context string must be the same for verification to succeed. For example: +.Sp +.Vb 2 +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt context\-string:mycontext +\& $ openssl pkeyutl \-verify \-in file.txt \-inkey mldsa65.pem \-sigfile sig \-pkeyopt context\-string:mycontext +.Ve +.IP \fBhexcontext\-string\fR:\fIstring\fR 4 +.IX Item "hexcontext-string:string" +Specifies a context string in hex format, allowing binary control values. For example: +.Sp +.Vb 1 +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt hexcontext\-string:6d79636f6e74657874 +.Ve +.PP +The signing operation supports a \fBdeterministic\fR:\fIbool\fR option, +with \fIbool\fR set to \f(CW1\fR if a deterministic signature is to be generated +with a fixed all zero random input. +By default, or if the \fIbool\fR is \f(CW0\fR a random entropy value is used. +A deterministic result can also be obtained by specifying an explicit +entropy value via the \fBhextest\-entropy\fR:\fIvalue\fR parameter. +Deterministic \fBML\-DSA\fR signing should only be used in tests. +.PP +See \fBEVP_SIGNATURE\-ML\-DSA\fR\|(7) for additional details about the ML\-DSA algorithms and their implementation. +.SH "ML\-KEM\-512, ML\-KEM\-768 AND ML\-KEM\-1024 ALGORITHMS" +.IX Header "ML-KEM-512, ML-KEM-768 AND ML-KEM-1024 ALGORITHMS" +The ML\-KEM algorithms support encapsulation and decapsulation only. +The encapsulation operation supports a \fBhexikme\fR:\fIentropy\fR option, +with \fIentropy\fR the 64 hexadecimal digit encoding of a 32\-byte value. +This should only be used in tests, known or leaked values of the option may +compromise the generated shared secret. +.PP +See \fBEVP_KEM\-ML\-KEM\fR\|(7) for additional detail. +.SH "ED25519 AND ED448 ALGORITHMS" +.IX Header "ED25519 AND ED448 ALGORITHMS" +These algorithms only support signing and verifying. OpenSSL only implements the +"pure" variants of these algorithms so raw data can be passed directly to them +without hashing them first. OpenSSL only supports +"oneshot" operation with these algorithms. This means that the entire file to +be signed/verified must be read into memory before processing it. Signing or +Verifying very large files should be avoided. Additionally the size of the file +must be known for this to work. If the size of the file cannot be determined +(for example if the input is stdin) then the sign or verify operation will fail. +.SH SM2 +.IX Header "SM2" +The SM2 algorithm supports sign, verify, encrypt and decrypt operations. For +the sign and verify operations, SM2 requires an Distinguishing ID string to +be passed in. The following \fB\-pkeyopt\fR value is supported: +.IP \fBdistid:\fR\fIstring\fR 4 +.IX Item "distid:string" +This sets the ID string used in SM2 sign or verify operations. While verifying +an SM2 signature, the ID string must be the same one used when signing the data. +Otherwise the verification will fail. +.IP \fBhexdistid:\fR\fIhex_string\fR 4 +.IX Item "hexdistid:hex_string" +This sets the ID string used in SM2 sign or verify operations. While verifying +an SM2 signature, the ID string must be the same one used when signing the data. +Otherwise the verification will fail. The ID string provided with this option +should be a valid hexadecimal value. +.SH EXAMPLES +.IX Header "EXAMPLES" +Sign some data using a private key: +.PP +.Vb 1 +\& openssl pkeyutl \-sign \-in file \-inkey key.pem \-out sig +.Ve +.PP +Recover the signed data (e.g. if an RSA key is used): +.PP +.Vb 1 +\& openssl pkeyutl \-verifyrecover \-in sig \-inkey key.pem +.Ve +.PP +Verify the signature (e.g. a DSA key): +.PP +.Vb 1 +\& openssl pkeyutl \-verify \-in file \-sigfile sig \-inkey key.pem +.Ve +.PP +Sign data using a message digest value (this is currently only valid for RSA): +.PP +.Vb 1 +\& openssl pkeyutl \-sign \-in file \-inkey key.pem \-out sig \-pkeyopt digest:sha256 +.Ve +.PP +Derive a shared secret value: +.PP +.Vb 1 +\& openssl pkeyutl \-derive \-inkey key.pem \-peerkey pubkey.pem \-out secret +.Ve +.PP +Hexdump 48 bytes of TLS1 PRF using digest \fBSHA256\fR and shared secret and +seed consisting of the single byte 0xFF: +.PP +.Vb 2 +\& openssl pkeyutl \-kdf TLS1\-PRF \-kdflen 48 \-pkeyopt md:SHA256 \e +\& \-pkeyopt hexsecret:ff \-pkeyopt hexseed:ff \-hexdump +.Ve +.PP +Derive a key using \fBscrypt\fR where the password is read from command line: +.PP +.Vb 2 +\& openssl pkeyutl \-kdf scrypt \-kdflen 16 \-pkeyopt_passin pass \e +\& \-pkeyopt hexsalt:aabbcc \-pkeyopt N:16384 \-pkeyopt r:8 \-pkeyopt p:1 +.Ve +.PP +Derive using the same algorithm, but read key from environment variable MYPASS: +.PP +.Vb 2 +\& openssl pkeyutl \-kdf scrypt \-kdflen 16 \-pkeyopt_passin pass:env:MYPASS \e +\& \-pkeyopt hexsalt:aabbcc \-pkeyopt N:16384 \-pkeyopt r:8 \-pkeyopt p:1 +.Ve +.PP +Sign some data using an \fBSM2\fR\|(7) private key and a specific ID: +.PP +.Vb 2 +\& openssl pkeyutl \-sign \-in file \-inkey sm2.key \-out sig \-rawin \-digest sm3 \e +\& \-pkeyopt distid:someid +.Ve +.PP +Verify some data using an \fBSM2\fR\|(7) certificate and a specific ID: +.PP +.Vb 2 +\& openssl pkeyutl \-verify \-certin \-in file \-inkey sm2.cert \-sigfile sig \e +\& \-rawin \-digest sm3 \-pkeyopt distid:someid +.Ve +.PP +Decrypt some data using a private key with OAEP padding using SHA256: +.PP +.Vb 2 +\& openssl pkeyutl \-decrypt \-in file \-inkey key.pem \-out secret \e +\& \-pkeyopt rsa_padding_mode:oaep \-pkeyopt rsa_oaep_md:sha256 +.Ve +.PP +Create an ML\-DSA key pair and sign data with a specific context string: +.PP +.Vb 2 +\& $ openssl genpkey \-algorithm ML\-DSA\-65 \-out mldsa65.pem +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey mldsa65.pem \-out sig \-pkeyopt context\-string:example +.Ve +.PP +Verify a signature using ML\-DSA with the same context string: +.PP +.Vb 1 +\& $ openssl pkeyutl \-verify \-in file.txt \-inkey mldsa65.pem \-sigfile sig \-pkeyopt context\-string:example +.Ve +.PP +Generate an ML\-KEM key pair and use it for encapsulation: +.PP +.Vb 3 +\& $ openssl genpkey \-algorithm ML\-KEM\-768 \-out mlkem768.pem +\& $ openssl pkey \-in mlkem768.pem \-pubout \-out mlkem768_pub.pem +\& $ openssl pkeyutl \-encap \-inkey mlkem768_pub.pem \-pubin \-out ciphertext \-secret shared_secret.bin +.Ve +.PP +Decapsulate a shared secret using an ML\-KEM private key: +.PP +.Vb 1 +\& $ openssl pkeyutl \-decap \-inkey mlkem768.pem \-in ciphertext \-secret decapsulated_secret.bin +.Ve +.PP +Create an SLH\-DSA key pair and sign data: +.PP +.Vb 2 +\& $ openssl genpkey \-algorithm SLH\-DSA\-SHA2\-128s \-out slh\-dsa.pem +\& $ openssl pkeyutl \-sign \-in file.txt \-inkey slh\-dsa.pem \-out sig +.Ve +.PP +Verify a signature using SLH\-DSA: +.PP +.Vb 1 +\& $ openssl pkeyutl \-verify \-in file.txt \-inkey slh\-dsa.pem \-sigfile sig +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\fR\|(1), +\&\fBopenssl\-genpkey\fR\|(1), +\&\fBopenssl\-pkey\fR\|(1), +\&\fBopenssl\-rsautl\fR\|(1) +\&\fBopenssl\-dgst\fR\|(1), +\&\fBopenssl\-rsa\fR\|(1), +\&\fBopenssl\-genrsa\fR\|(1), +\&\fBopenssl\-kdf\fR\|(1) +\&\fBEVP_PKEY_CTX_set_hkdf_md\fR\|(3), +\&\fBEVP_PKEY_CTX_set_tls1_prf_md\fR\|(3), +.SH HISTORY +.IX Header "HISTORY" +Since OpenSSL 3.5, +the \fB\-digest\fR option implies \fB\-rawin\fR, and these two options are +no longer required when signing or verifying with an Ed25519 or Ed448 key. +.PP +Also since OpenSSL 3.5, the \fB\-kemop\fR option is no longer required for any of +the supported algorithms, the only supported \fBmode\fR is now the default. +.PP +The \fB\-engine\fR option was deprecated in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2026 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +<https://www.openssl.org/source/license.html>. |