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