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