473 lines
14 KiB
HTML
473 lines
14 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of PKEYUTL</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>PKEYUTL</H1>
|
|
Section: OpenSSL (1SSL)<BR>Updated: 2021-03-22<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
openssl-pkeyutl, pkeyutl - public key algorithm utility
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
<B>openssl</B> <B>pkeyutl</B>
|
|
[<B>-help</B>]
|
|
[<B>-in file</B>]
|
|
[<B>-out file</B>]
|
|
[<B>-sigfile file</B>]
|
|
[<B>-inkey file</B>]
|
|
[<B>-keyform PEM|DER|ENGINE</B>]
|
|
[<B>-passin arg</B>]
|
|
[<B>-peerkey file</B>]
|
|
[<B>-peerform PEM|DER|ENGINE</B>]
|
|
[<B>-pubin</B>]
|
|
[<B>-certin</B>]
|
|
[<B>-rev</B>]
|
|
[<B>-sign</B>]
|
|
[<B>-verify</B>]
|
|
[<B>-verifyrecover</B>]
|
|
[<B>-encrypt</B>]
|
|
[<B>-decrypt</B>]
|
|
[<B>-derive</B>]
|
|
[<B>-kdf algorithm</B>]
|
|
[<B>-kdflen length</B>]
|
|
[<B>-pkeyopt opt:value</B>]
|
|
[<B>-hexdump</B>]
|
|
[<B>-asn1parse</B>]
|
|
[<B>-rand file...</B>]
|
|
[<B>-writerand file</B>]
|
|
[<B>-engine id</B>]
|
|
[<B>-engine_impl</B>]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <B>pkeyutl</B> command can be used to perform low level public key operations
|
|
using any supported algorithm.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-help</B><DD>
|
|
|
|
|
|
Print out a usage message.
|
|
<DT id="2"><B>-in filename</B><DD>
|
|
|
|
|
|
This specifies the input filename to read data from or standard input
|
|
if this option is not specified.
|
|
<DT id="3"><B>-out filename</B><DD>
|
|
|
|
|
|
Specifies the output filename to write to or standard output by
|
|
default.
|
|
<DT id="4"><B>-sigfile file</B><DD>
|
|
|
|
|
|
Signature file, required for <B>verify</B> operations only
|
|
<DT id="5"><B>-inkey file</B><DD>
|
|
|
|
|
|
The input key file, by default it should be a private key.
|
|
<DT id="6"><B>-keyform PEM|DER|ENGINE</B><DD>
|
|
|
|
|
|
The key format <FONT SIZE="-1">PEM, DER</FONT> or <FONT SIZE="-1">ENGINE.</FONT> Default is <FONT SIZE="-1">PEM.</FONT>
|
|
<DT id="7"><B>-passin arg</B><DD>
|
|
|
|
|
|
The input key password source. For more information about the format of <B>arg</B>
|
|
see the <B></B><FONT SIZE="-1"><B>PASS PHRASE ARGUMENTS</B></FONT><B></B> section in <B><A HREF="/cgi-bin/man/man2html?1+openssl">openssl</A></B>(1).
|
|
<DT id="8"><B>-peerkey file</B><DD>
|
|
|
|
|
|
The peer key file, used by key derivation (agreement) operations.
|
|
<DT id="9"><B>-peerform PEM|DER|ENGINE</B><DD>
|
|
|
|
|
|
The peer key format <FONT SIZE="-1">PEM, DER</FONT> or <FONT SIZE="-1">ENGINE.</FONT> Default is <FONT SIZE="-1">PEM.</FONT>
|
|
<DT id="10"><B>-pubin</B><DD>
|
|
|
|
|
|
The input file is a public key.
|
|
<DT id="11"><B>-certin</B><DD>
|
|
|
|
|
|
The input is a certificate containing a public key.
|
|
<DT id="12"><B>-rev</B><DD>
|
|
|
|
|
|
Reverse the order of the input buffer. This is useful for some libraries
|
|
(such as CryptoAPI) which represent the buffer in little endian format.
|
|
<DT id="13"><B>-sign</B><DD>
|
|
|
|
|
|
Sign the input data (which must be a hash) and output the signed result. This
|
|
requires a private key.
|
|
<DT id="14"><B>-verify</B><DD>
|
|
|
|
|
|
Verify the input data (which must be a hash) against the signature file and
|
|
indicate if the verification succeeded or failed.
|
|
<DT id="15"><B>-verifyrecover</B><DD>
|
|
|
|
|
|
Verify the input data (which must be a hash) and output the recovered data.
|
|
<DT id="16"><B>-encrypt</B><DD>
|
|
|
|
|
|
Encrypt the input data using a public key.
|
|
<DT id="17"><B>-decrypt</B><DD>
|
|
|
|
|
|
Decrypt the input data using a private key.
|
|
<DT id="18"><B>-derive</B><DD>
|
|
|
|
|
|
Derive a shared secret using the peer key.
|
|
<DT id="19"><B>-kdf algorithm</B><DD>
|
|
|
|
|
|
Use key derivation function <B>algorithm</B>. The supported algorithms are
|
|
at present <B></B><FONT SIZE="-1"><B>TLS1-PRF</B></FONT><B></B> and <B></B><FONT SIZE="-1"><B>HKDF</B></FONT><B></B>.
|
|
Note: additional parameters and the <FONT SIZE="-1">KDF</FONT> output length will normally have to be
|
|
set for this to work.
|
|
See <B><A HREF="/cgi-bin/man/man2html?3+EVP_PKEY_CTX_set_hkdf_md">EVP_PKEY_CTX_set_hkdf_md</A></B>(3) and <B><A HREF="/cgi-bin/man/man2html?3+EVP_PKEY_CTX_set_tls1_prf_md">EVP_PKEY_CTX_set_tls1_prf_md</A></B>(3)
|
|
for the supported string parameters of each algorithm.
|
|
<DT id="20"><B>-kdflen length</B><DD>
|
|
|
|
|
|
Set the output length for <FONT SIZE="-1">KDF.</FONT>
|
|
<DT id="21"><B>-pkeyopt opt:value</B><DD>
|
|
|
|
|
|
Public key options specified as opt:value. See <FONT SIZE="-1">NOTES</FONT> below for more details.
|
|
<DT id="22"><B>-hexdump</B><DD>
|
|
|
|
|
|
hex dump the output data.
|
|
<DT id="23"><B>-asn1parse</B><DD>
|
|
|
|
|
|
Parse the <FONT SIZE="-1">ASN.1</FONT> output data, this is useful when combined with the
|
|
<B>-verifyrecover</B> option when an <FONT SIZE="-1">ASN1</FONT> structure is signed.
|
|
<DT id="24"><B>-rand file...</B><DD>
|
|
|
|
|
|
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>;</B> for MS-Windows, <B>,</B> for OpenVMS, and <B>:</B> for
|
|
all others.
|
|
<DT id="25">[<B>-writerand file</B>]<DD>
|
|
|
|
|
|
Writes random data to the specified <I>file</I> upon exit.
|
|
This can be used with a subsequent <B>-rand</B> flag.
|
|
<DT id="26"><B>-engine id</B><DD>
|
|
|
|
|
|
Specifying an engine (by its unique <B>id</B> string) will cause <B>pkeyutl</B>
|
|
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.
|
|
<DT id="27"><B>-engine_impl</B><DD>
|
|
|
|
|
|
When used with the <B>-engine</B> option, it specifies to also use
|
|
engine <B>id</B> for crypto operations.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
|
|
|
|
The operations and options supported vary according to the key algorithm
|
|
and its implementation. The OpenSSL operations and options are indicated below.
|
|
<P>
|
|
|
|
Unless otherwise mentioned all algorithms support the <B>digest:alg</B> option
|
|
which specifies the digest in use for sign, verify and verifyrecover operations.
|
|
The value <B>alg</B> should represent a digest name as used in the
|
|
<B>EVP_get_digestbyname()</B> function for example <B>sha1</B>. 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</B> and for creating the structures that
|
|
make up the signature (e.g. <B>DigestInfo</B> in <FONT SIZE="-1">RSASSA</FONT> PKCS#1 v1.5 signatures).
|
|
<P>
|
|
|
|
This utility does not hash the input data 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 <FONT SIZE="-1">RSA.</FONT> In
|
|
case of <FONT SIZE="-1">ECDSA</FONT> and <FONT SIZE="-1">DSA</FONT> 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.
|
|
<P>
|
|
|
|
In other words, if the value of digest is <B>sha1</B> the input should be the 20
|
|
bytes long binary encoding of the <FONT SIZE="-1">SHA-1</FONT> hash function output.
|
|
<P>
|
|
|
|
The Ed25519 and Ed448 signature algorithms are not supported by this utility.
|
|
They accept non-hashed input, but this utility can only be used to sign hashed
|
|
input.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>RSA ALGORITHM</H2>
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">RSA</FONT> 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</B> values are supported:
|
|
<DL COMPACT>
|
|
<DT id="28"><B>rsa_padding_mode:mode</B><DD>
|
|
|
|
|
|
This sets the <FONT SIZE="-1">RSA</FONT> padding mode. Acceptable values for <B>mode</B> are <B>pkcs1</B> for
|
|
PKCS#1 padding, <B>sslv23</B> for SSLv23 padding, <B>none</B> for no padding, <B>oaep</B>
|
|
for <B></B><FONT SIZE="-1"><B>OAEP</B></FONT><B></B> mode, <B>x931</B> for X9.31 mode and <B>pss</B> for <FONT SIZE="-1">PSS.</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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</B> structure. If a
|
|
digest is set then the a <B>DigestInfo</B> structure is used and its the length
|
|
must correspond to the digest type.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For <B>oaep</B> mode only encryption and decryption is supported.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For <B>x931</B> 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 <FONT SIZE="-1">ID.</FONT> Sign,
|
|
verify and verifyrecover are can be performed in this mode.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For <B>pss</B> mode only sign and verify are supported and the digest type must be
|
|
specified.
|
|
<DT id="29"><B>rsa_pss_saltlen:len</B><DD>
|
|
|
|
|
|
For <B>pss</B> 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></B><FONT SIZE="-1"><B>PSS</B></FONT><B></B> block structure.
|
|
<DT id="30"><B>rsa_mgf1_md:digest</B><DD>
|
|
|
|
|
|
For <FONT SIZE="-1">PSS</FONT> and <FONT SIZE="-1">OAEP</FONT> padding sets the <FONT SIZE="-1">MGF1</FONT> digest. If the <FONT SIZE="-1">MGF1</FONT> digest is not
|
|
explicitly set in <FONT SIZE="-1">PSS</FONT> mode then the signing digest is used.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>RSA-PSS ALGORITHM</H2>
|
|
|
|
|
|
|
|
The RSA-PSS algorithm is a restricted version of the <FONT SIZE="-1">RSA</FONT> algorithm which only
|
|
supports the sign and verify operations with <FONT SIZE="-1">PSS</FONT> padding. The following
|
|
additional <B>pkeyopt</B> values are supported:
|
|
<DL COMPACT>
|
|
<DT id="31"><B>rsa_padding_mode:mode</B>, <B>rsa_pss_saltlen:len</B>, <B>rsa_mgf1_md:digest</B><DD>
|
|
|
|
|
|
These have the same meaning as the <B></B><FONT SIZE="-1"><B>RSA</B></FONT><B></B> algorithm with some additional
|
|
restrictions. The padding mode can only be set to <B>pss</B> which is the
|
|
default value.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the key has parameter restrictions than the digest, <FONT SIZE="-1">MGF1</FONT>
|
|
digest and salt length are set to the values specified in the parameters.
|
|
The digest and <FONT SIZE="-1">MG</FONT> cannot be changed and the salt length cannot be set to a
|
|
value less than the minimum restriction.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>DSA ALGORITHM</H2>
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">DSA</FONT> algorithm supports signing and verification operations only. Currently
|
|
there are no additional <B>-pkeyopt</B> options other than <B>digest</B>. The <FONT SIZE="-1">SHA1</FONT>
|
|
digest is assumed by default.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>DH ALGORITHM</H2>
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">DH</FONT> algorithm only supports the derivation operation and no additional
|
|
<B>-pkeyopt</B> options.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>EC ALGORITHM</H2>
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">EC</FONT> algorithm supports sign, verify and derive operations. The sign and
|
|
verify operations use <FONT SIZE="-1">ECDSA</FONT> and derive uses <FONT SIZE="-1">ECDH. SHA1</FONT> is assumed by default for
|
|
the <B>-pkeyopt</B> <B>digest</B> option.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>X25519 and X448 ALGORITHMS</H2>
|
|
|
|
|
|
|
|
The X25519 and X448 algorithms support key derivation only. Currently there are
|
|
no additional options.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
|
|
|
|
Sign some data using a private key:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
openssl pkeyutl -sign -in file -inkey key.pem -out sig
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Recover the signed data (e.g. if an <FONT SIZE="-1">RSA</FONT> key is used):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
openssl pkeyutl -verifyrecover -in sig -inkey key.pem
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Verify the signature (e.g. a <FONT SIZE="-1">DSA</FONT> key):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Sign data using a message digest value (this is currently only valid for <FONT SIZE="-1">RSA</FONT>):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Derive a shared secret value:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Hexdump 48 bytes of <FONT SIZE="-1">TLS1 PRF</FONT> using digest <B></B><FONT SIZE="-1"><B>SHA256</B></FONT><B></B> and shared secret and
|
|
seed consisting of the single byte 0xFF:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
|
|
-pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+genpkey">genpkey</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+pkey">pkey</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+rsautl">rsautl</A></B>(1)
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dgst">dgst</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+rsa">rsa</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+genrsa">genrsa</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?3+EVP_PKEY_CTX_set_hkdf_md">EVP_PKEY_CTX_set_hkdf_md</A></B>(3), <B><A HREF="/cgi-bin/man/man2html?3+EVP_PKEY_CTX_set_tls1_prf_md">EVP_PKEY_CTX_set_tls1_prf_md</A></B>(3)
|
|
<A NAME="lbAO"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
<P>
|
|
|
|
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 <FONT SIZE="-1">LICENSE</FONT> in the source distribution or at
|
|
<<A HREF="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</A>>.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="32"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="33"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="34"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="35"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="36"><A HREF="#lbAF">NOTES</A><DD>
|
|
<DT id="37"><A HREF="#lbAG">RSA ALGORITHM</A><DD>
|
|
<DT id="38"><A HREF="#lbAH">RSA-PSS ALGORITHM</A><DD>
|
|
<DT id="39"><A HREF="#lbAI">DSA ALGORITHM</A><DD>
|
|
<DT id="40"><A HREF="#lbAJ">DH ALGORITHM</A><DD>
|
|
<DT id="41"><A HREF="#lbAK">EC ALGORITHM</A><DD>
|
|
<DT id="42"><A HREF="#lbAL">X25519 and X448 ALGORITHMS</A><DD>
|
|
<DT id="43"><A HREF="#lbAM">EXAMPLES</A><DD>
|
|
<DT id="44"><A HREF="#lbAN">SEE ALSO</A><DD>
|
|
<DT id="45"><A HREF="#lbAO">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:23 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|