=head1 SYNOPSIS
B<openssl> B<pkeyutl>
+[B<-help>]
[B<-in file>]
[B<-out file>]
[B<-sigfile file>]
[B<-inkey file>]
-[B<-keyform PEM|DER>]
+[B<-keyform PEM|DER|ENGINE>]
+[B<-passin arg>]
[B<-peerkey file>]
-[B<-peerform PEM|DER>]
+[B<-peerform PEM|DER|ENGINE>]
[B<-pubin>]
[B<-certin>]
[B<-rev>]
[B<-encrypt>]
[B<-decrypt>]
[B<-derive>]
+[B<-kdf algorithm>]
+[B<-kdflen length>]
[B<-pkeyopt opt:value>]
[B<-hexdump>]
[B<-asn1parse>]
+[B<-engine id>]
+[B<-engine_impl>]
=head1 DESCRIPTION
=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
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>
+=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)>.
-the key format PEM or DER.
=item B<-peerkey file>
the peer key file, used by key derivation (agreement) operations.
-=item B<-peerform PEM|DER>
+=item B<-peerform PEM|DER|ENGINE>
-the peer key format PEM or DER.
+the peer key format PEM, DER or ENGINE. Default is PEM.
=item B<-pubin>
-the input file is a public key.
+the input file is a public key.
=item B<-certin>
-the input is a certificate containing a public key.
+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>
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_HKDF(3)> and L<EVP_PKEY_TLS1_PRF(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<-hexdump>
hex dump the output data.
asn1parse the output data, this is useful when combined with the
B<-verifyrecover> option when an ASN1 structure is signed.
+=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 used only 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).
+In case of RSA, ECDSA and DSA signatures, this utility
+will not perform hashing on input data but rather use the data directly as
+input of signature algorithm. Depending on key type, signature type and mode
+of padding, the maximum acceptable lengths of input data differ. In general,
+with RSA the signed data can't be longer than the key modulus, in case of ECDSA
+and DSA the data shouldn't be longer than field size, otherwise it will be
+silently truncated to field size.
+
+In other words, if the value of digest is B<sha1> the input should be 20 bytes
+long binary encoding of SHA-1 hash function output.
+
=head1 RSA ALGORITHM
-The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover
-operations in general. Some padding modes only support some of these
-operations however.
+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.
-[NB: more to be added later]
+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. Two special values
+are supported: -1 sets the salt length to the digest length. When signing -2
+sets the salt length to the maximum permissible value. When verifying -2 causes
+the salt length to be automatically determined based on the B<PSS> block
+structure.
+
+=back
+
+=head1 DSA ALGORITHM
+
+The DSA algorithm supports signing and verification operations only. Currently
+there are no additional options other than B<digest>. Only the SHA1
+digest can be used and this digest is assumed by default.
+
+=head1 DH ALGORITHM
+
+The DH algorithm only supports the derivation operation and no additional
+options.
+
+=head1 EC ALGORITHM
+
+The EC algorithm supports sign, verify and derive operations. The sign and
+verify operations use ECDSA and derive uses ECDH. Currently there are no
+additional options other than B<digest>. Only the SHA1 digest can be used and
+this digest is assumed by default.
+
+=head1 X25519 ALGORITHM
+
+The X25519 algorithm supports key derivation only. Currently there are no
+additional options.
=head1 EXAMPLES
Verify the signature (e.g. a DSA key):
- openssl pkeyutl -verify -sigfile file -in sig -inkey key.pem
+ 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
=head1 SEE ALSO
-L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)>
-L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>
+
+L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
+L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
+L<EVP_PKEY_HKDF(3)>, L<EVP_PKEY_TLS1_PRF(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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
projects / oweals / openssl.git / blobdiff