460b8d175b
Fixes #8784 Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9228)
410 lines
13 KiB
Text
410 lines
13 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
openssl-pkeyutl,
|
|
pkeyutl - public key algorithm utility
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<openssl> B<pkeyutl>
|
|
[B<-help>]
|
|
[B<-in file>]
|
|
[B<-rawin>]
|
|
[B<-digest algorithm>]
|
|
[B<-out file>]
|
|
[B<-sigfile file>]
|
|
[B<-inkey file>]
|
|
[B<-keyform PEM|DER|ENGINE>]
|
|
[B<-passin arg>]
|
|
[B<-peerkey file>]
|
|
[B<-peerform PEM|DER|ENGINE>]
|
|
[B<-pubin>]
|
|
[B<-certin>]
|
|
[B<-rev>]
|
|
[B<-sign>]
|
|
[B<-verify>]
|
|
[B<-verifyrecover>]
|
|
[B<-encrypt>]
|
|
[B<-decrypt>]
|
|
[B<-derive>]
|
|
[B<-kdf algorithm>]
|
|
[B<-kdflen length>]
|
|
[B<-pkeyopt opt:value>]
|
|
[B<-pkeyopt_passin opt:passarg>]
|
|
[B<-hexdump>]
|
|
[B<-asn1parse>]
|
|
[B<-rand file...>]
|
|
[B<-writerand file>]
|
|
[B<-engine id>]
|
|
[B<-engine_impl>]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<pkeyutl> command can be used to perform low level public key operations
|
|
using any supported algorithm.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<-help>
|
|
|
|
Print out a usage message.
|
|
|
|
=item B<-in filename>
|
|
|
|
This specifies the input filename to read data from or standard input
|
|
if this option is not specified.
|
|
|
|
=item B<-rawin>
|
|
|
|
This indicates that the input data is raw data, which is not hashed by any
|
|
message digest algorithm. The user can specify a digest algorithm by using
|
|
the B<-digest> option. This option can only be used with B<-sign> and
|
|
B<-verify> and must be used with the Ed25519 and Ed448 algorithms.
|
|
|
|
=item B<-digest algorithm>
|
|
|
|
This specifies the digest algorithm which 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 one (for instance, EdDSA). If this option
|
|
is omitted but the signature algorithm requires one, a default value will be
|
|
used. For signature algorithms like RSA, DSA and ECDSA, SHA-256 will be the
|
|
default digest algorithm. For SM2, it will be SM3. If this option is present,
|
|
then the B<-rawin> option must be also specified to B<pkeyutl>.
|
|
|
|
=item B<-out filename>
|
|
|
|
Specifies the output filename to write to or standard output by
|
|
default.
|
|
|
|
=item B<-sigfile file>
|
|
|
|
Signature file, required for B<verify> operations only
|
|
|
|
=item B<-inkey file>
|
|
|
|
The input key file, by default it should be a private key.
|
|
|
|
=item B<-keyform PEM|DER|ENGINE>
|
|
|
|
The key format PEM, DER or ENGINE. Default is PEM.
|
|
|
|
=item B<-passin arg>
|
|
|
|
The input key password source. For more information about the format of B<arg>
|
|
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
|
|
|
|
=item B<-peerkey file>
|
|
|
|
The peer key file, used by key derivation (agreement) operations.
|
|
|
|
=item B<-peerform PEM|DER|ENGINE>
|
|
|
|
The peer key format PEM, DER or ENGINE. Default is PEM.
|
|
|
|
=item B<-pubin>
|
|
|
|
The input file is a public key.
|
|
|
|
=item B<-certin>
|
|
|
|
The input is a certificate containing a public key.
|
|
|
|
=item B<-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.
|
|
|
|
=item B<-sign>
|
|
|
|
Sign the input data (which must be a hash) and output the signed result. This
|
|
requires a private key.
|
|
|
|
=item B<-verify>
|
|
|
|
Verify the input data (which must be a hash) against the signature file and
|
|
indicate if the verification succeeded or failed.
|
|
|
|
=item B<-verifyrecover>
|
|
|
|
Verify the input data (which must be a hash) and output the recovered data.
|
|
|
|
=item B<-encrypt>
|
|
|
|
Encrypt the input data using a public key.
|
|
|
|
=item B<-decrypt>
|
|
|
|
Decrypt the input data using a private key.
|
|
|
|
=item B<-derive>
|
|
|
|
Derive a shared secret using the peer key.
|
|
|
|
=item B<-kdf algorithm>
|
|
|
|
Use key derivation function B<algorithm>. The supported algorithms are
|
|
at present B<TLS1-PRF> and B<HKDF>.
|
|
Note: additional parameters and the KDF output length will normally have to be
|
|
set for this to work.
|
|
See L<EVP_PKEY_CTX_set_hkdf_md(3)> and L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
|
|
for the supported string parameters of each algorithm.
|
|
|
|
=item B<-kdflen length>
|
|
|
|
Set the output length for KDF.
|
|
|
|
=item B<-pkeyopt opt:value>
|
|
|
|
Public key options specified as opt:value. See NOTES below for more details.
|
|
|
|
=item B<-pkeyopt_passin opt:passarg>
|
|
|
|
Allows reading a public key option B<opt> from stdin or a password source. If
|
|
only opt is specified, the user will be prompted to enter the value on stdin.
|
|
Alternatively, passarg can be specified which can be any value supported by
|
|
B<PASS PHRASE ARGUMENTS> in L<openssl(1)>.
|
|
|
|
=item B<-hexdump>
|
|
|
|
hex dump the output data.
|
|
|
|
=item B<-asn1parse>
|
|
|
|
Parse the ASN.1 output data, this is useful when combined with the
|
|
B<-verifyrecover> option when an ASN1 structure is signed.
|
|
|
|
=item B<-rand file...>
|
|
|
|
A file or files containing random data used to seed the random number
|
|
generator.
|
|
Multiple files can be specified separated by an OS-dependent character.
|
|
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
|
|
all others.
|
|
|
|
=item [B<-writerand file>]
|
|
|
|
Writes random data to the specified I<file> upon exit.
|
|
This can be used with a subsequent B<-rand> flag.
|
|
|
|
=item B<-engine id>
|
|
|
|
Specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
|
|
to attempt to obtain a functional reference to the specified engine,
|
|
thus initialising it if needed. The engine will then be set as the default
|
|
for all available algorithms.
|
|
|
|
=item B<-engine_impl>
|
|
|
|
When used with the B<-engine> option, it specifies to also use
|
|
engine B<id> for crypto operations.
|
|
|
|
=back
|
|
|
|
=head1 NOTES
|
|
|
|
The operations and options supported vary according to the key algorithm
|
|
and its implementation. The OpenSSL operations and options are indicated below.
|
|
|
|
Unless otherwise mentioned all algorithms support the B<digest:alg> option
|
|
which specifies the digest in use for sign, verify and verifyrecover operations.
|
|
The value B<alg> should represent a digest name as used in the
|
|
EVP_get_digestbyname() function for example B<sha1>. 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 to the B<pkeyutl> and for creating the structures that
|
|
make up the signature (e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures).
|
|
|
|
This utility does not hash the input data (except where -rawin is used) 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
|
|
acceptable lengths of input data differ. The signed data can't be longer than
|
|
the key modulus with RSA. In case of ECDSA and DSA the data shouldn't 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
|
|
size.
|
|
|
|
In other words, if the value of digest is B<sha1> the input should be the 20
|
|
bytes long binary encoding of the SHA-1 hash function output.
|
|
|
|
=head1 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
|
|
B<pkeyopt> values are supported:
|
|
|
|
=over 4
|
|
|
|
=item B<rsa_padding_mode:mode>
|
|
|
|
This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for
|
|
PKCS#1 padding, B<sslv23> for SSLv23 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
|
|
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
|
|
must correspond to the digest type.
|
|
|
|
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
|
|
otherwise the first byte is used to specify the X9.31 digest ID. Sign,
|
|
verify and verifyrecover are can be performed in this mode.
|
|
|
|
For B<pss> mode only sign and verify are supported and the digest type must be
|
|
specified.
|
|
|
|
=item B<rsa_pss_saltlen:len>
|
|
|
|
For B<pss> mode only this option specifies the salt length. Three special
|
|
values are supported: "digest" sets the salt length to the digest length,
|
|
"max" sets the salt length to the maximum permissible value. When verifying
|
|
"auto" causes the salt length to be automatically determined based on the
|
|
B<PSS> block structure.
|
|
|
|
=item B<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.
|
|
|
|
=back
|
|
|
|
=head1 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 B<pkeyopt> values are supported:
|
|
|
|
=over 4
|
|
|
|
=item B<rsa_padding_mode:mode>, B<rsa_pss_saltlen:len>, B<rsa_mgf1_md:digest>
|
|
|
|
These have the same meaning as the B<RSA> algorithm with some additional
|
|
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
|
|
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.
|
|
|
|
=back
|
|
|
|
=head1 DSA ALGORITHM
|
|
|
|
The DSA algorithm supports signing and verification operations only. Currently
|
|
there are no additional B<-pkeyopt> options other than B<digest>. The SHA1
|
|
digest is assumed by default.
|
|
|
|
=head1 DH ALGORITHM
|
|
|
|
The DH algorithm only supports the derivation operation and no additional
|
|
B<-pkeyopt> options.
|
|
|
|
=head1 EC ALGORITHM
|
|
|
|
The EC algorithm supports sign, verify and derive operations. The sign and
|
|
verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for
|
|
the B<-pkeyopt> B<digest> option.
|
|
|
|
=head1 X25519 and X448 ALGORITHMS
|
|
|
|
The X25519 and X448 algorithms support key derivation only. Currently there are
|
|
no additional options.
|
|
|
|
=head1 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. The option "-rawin" must be used with these
|
|
algorithms with no "-digest" specified. Additionally 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.
|
|
|
|
=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:
|
|
|
|
=over 4
|
|
|
|
=item B<sm2_id: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.
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Sign some data using a private key:
|
|
|
|
openssl pkeyutl -sign -in file -inkey key.pem -out sig
|
|
|
|
Recover the signed data (e.g. if an RSA key is used):
|
|
|
|
openssl pkeyutl -verifyrecover -in sig -inkey key.pem
|
|
|
|
Verify the signature (e.g. a DSA key):
|
|
|
|
openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
|
|
|
|
Sign data using a message digest value (this is currently only valid for RSA):
|
|
|
|
openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
|
|
|
|
Derive a shared secret value:
|
|
|
|
openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
|
|
|
|
Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and
|
|
seed consisting of the single byte 0xFF:
|
|
|
|
openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
|
|
-pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
|
|
|
|
Derive a key using B<scrypt> where the password is read from command line:
|
|
|
|
openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass \
|
|
-pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1
|
|
|
|
Derive using the same algorithm, but read key from environment variable MYPASS:
|
|
|
|
openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass:env:MYPASS \
|
|
-pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1
|
|
|
|
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
|
|
|
|
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
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
|
|
L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
|
|
L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)>,
|
|
L<kdf(1)>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2006-2018 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
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|