=head1 NAME
-openssl-pkeyutl - public key algorithm utility
+openssl-pkeyutl - public key algorithm command
=head1 SYNOPSIS
[B<-digest> I<algorithm>]
[B<-out> I<file>]
[B<-sigfile> I<file>]
-[B<-inkey> I<file>]
-[B<-keyform> B<DER>|B<PEM>|B<ENGINE>]
+[B<-inkey> I<filename>|I<uri>]
+[B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
[B<-passin> I<arg>]
[B<-peerkey> I<file>]
-[B<-peerform> B<DER>|B<PEM>|B<ENGINE>]
+[B<-peerform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
[B<-pubin>]
[B<-certin>]
[B<-rev>]
[B<-pkeyopt_passin> I<opt>[:I<passarg>]]
[B<-hexdump>]
[B<-asn1parse>]
-{- $OpenSSL::safe::opt_engine_synopsis -}
-[B<-engine_impl>]
+{- $OpenSSL::safe::opt_engine_synopsis -}[B<-engine_impl>]
{- $OpenSSL::safe::opt_r_synopsis -}
-
-=for openssl ifdef engine engine_impl
+{- $OpenSSL::safe::opt_provider_synopsis -}
+{- $OpenSSL::safe::opt_config_synopsis -}
=head1 DESCRIPTION
-This command can be used to perform low level public key
+This command can be used to perform low-level public key
operations using any supported algorithm.
=head1 OPTIONS
Signature file, required for B<-verify> operations only
-=item B<-inkey> I<file>
+=item B<-inkey> I<filename>|I<uri>
-The input key file, by default it should be a private key.
+The input key, by default it should be a private key.
-=item B<-keyform> B<DER>|B<PEM>|B<ENGINE>
+=item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
-The key format; the default is B<PEM>.
-See L<openssl(1)/Format Options> for details.
+The key format; unspecified by default.
+See L<openssl-format-options(1)> for details.
=item B<-passin> I<arg>
The input key password source. For more information about the format of I<arg>
-see L<openssl(1)/Pass Phrase Options>.
+see L<openssl-passphrase-options(1)>.
=item B<-peerkey> I<file>
The peer key file, used by key derivation (agreement) operations.
-=item B<-peerform> B<DER>|B<PEM>|B<ENGINE>
+=item B<-peerform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
-The peer key format; the default is B<PEM>.
-See L<openssl(1)/Format Options> for details.
+The peer key format; unspecified by default.
+See L<openssl-format-options(1)> for details.
=item B<-pubin>
-The input file is a public key.
+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.
=item B<-certin>
Allows reading a public key option I<opt> from stdin or a password source.
If only I<opt> is specified, the user will be prompted to enter a password on
stdin. Alternatively, I<passarg> can be specified which can be any value
-supported by L<openssl(1)/Pass phrase options>.
+supported by L<openssl-passphrase-options(1)>.
=item B<-hexdump>
{- $OpenSSL::safe::opt_engine_item -}
+{- output_off() if $disabled{"deprecated-3.0"}; "" -}
=item B<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine I<id> for crypto operations.
+{- output_on() if $disabled{"deprecated-3.0"}; "" -}
{- $OpenSSL::safe::opt_r_item -}
+{- $OpenSSL::safe::opt_provider_item -}
+
+{- $OpenSSL::safe::opt_config_item -}
+
=back
=head1 NOTES
=item B<rsa_padding_mode:>I<mode>
This sets the RSA padding mode. Acceptable values for I<mode> are B<pkcs1> for
-PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep>
+PKCS#1 padding, B<none> for no padding, B<oaep>
for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS.
-In PKCS#1 padding if the message digest is not set then the supplied data is
+In PKCS#1 padding, if the message digest is not set, then the supplied data is
signed or verified directly instead of using a B<DigestInfo> structure. If a
-digest is set then the a B<DigestInfo> structure is used and its the length
+digest is set, then the B<DigestInfo> structure is used and its length
must correspond to the digest type.
+Note, for B<pkcs1> padding, as a protection against the Bleichenbacher attack,
+the decryption will not fail in case of padding check failures. Use B<none>
+and manual inspection of the decrypted message to verify if the decrypted
+value has correct PKCS#1 v1.5 padding.
+
For B<oaep> mode only encryption and decryption is supported.
For B<x931> if the digest type is set it is used to format the block data
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.
+=item B<rsa_oaep_md:>I<digest>
+
+Sets the digest used for the OAEP hash function. If not explicitly set then
+SHA1 is used.
+
+=item B<rsa_pkcs1_implicit_rejection:>I<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's the callers' responsibility to handle the returned
+errors in a side-channel free manner.
+
=back
=head1 RSA-PSS ALGORITHM
restrictions. The padding mode can only be set to B<pss> which is the
default value.
-If the key has parameter restrictions than the digest, MGF1
+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.
=head1 SM2
The SM2 algorithm supports sign, verify, encrypt and decrypt operations. For
-the sign and verify operations, SM2 requires an ID string to be passed in. The
-following B<-pkeyopt> value is supported:
+the sign and verify operations, SM2 requires an Distinguishing ID string to
+be passed in. The following B<-pkeyopt> value is supported:
=over 4
-=item B<sm2_id:>I<string>
+=item B<distid:>I<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.
-=item B<sm2_hex_id:>I<hex_string>
+=item B<hexdistid:>I<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.
Sign some data using an L<SM2(7)> private key and a specific ID:
openssl pkeyutl -sign -in file -inkey sm2.key -out sig -rawin -digest sm3 \
- -pkeyopt sm2_id:someid
+ -pkeyopt distid:someid
Verify some data using an L<SM2(7)> certificate and a specific ID:
openssl pkeyutl -verify -certin -in file -inkey sm2.cert -sigfile sig \
- -rawin -digest sm3 -pkeyopt sm2_id:someid
+ -rawin -digest sm3 -pkeyopt distid:someid
+
+Decrypt some data using a private key with OAEP padding using SHA256:
+
+ openssl pkeyutl -decrypt -in file -inkey key.pem -out secret \
+ -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
=head1 SEE ALSO
L<EVP_PKEY_CTX_set_hkdf_md(3)>,
L<EVP_PKEY_CTX_set_tls1_prf_md(3)>,
+=head1 HISTORY
+
+The B<-engine> option was deprecated in OpenSSL 3.0.
=head1 COPYRIGHT
-Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2006-2023 The OpenSSL Project Authors. All Rights Reserved.
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
projects / openssl.git / blobdiff