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