402 lines
16 KiB
HTML
402 lines
16 KiB
HTML
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>pkeyutl</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#options">OPTIONS</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#rsa_algorithm">RSA ALGORITHM</a></li>
|
|
<li><a href="#rsa_pss_algorithm">RSA-PSS ALGORITHM</a></li>
|
|
<li><a href="#dsa_algorithm">DSA ALGORITHM</a></li>
|
|
<li><a href="#dh_algorithm">DH ALGORITHM</a></li>
|
|
<li><a href="#ec_algorithm">EC ALGORITHM</a></li>
|
|
<li><a href="#x25519_and_x448_algorithms">X25519 and X448 ALGORITHMS</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>openssl-pkeyutl,
|
|
pkeyutl - public key algorithm utility</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<p><strong>openssl</strong> <strong>pkeyutl</strong>
|
|
[<strong>-help</strong>]
|
|
[<strong>-in file</strong>]
|
|
[<strong>-out file</strong>]
|
|
[<strong>-sigfile file</strong>]
|
|
[<strong>-inkey file</strong>]
|
|
[<strong>-keyform PEM|DER|ENGINE</strong>]
|
|
[<strong>-passin arg</strong>]
|
|
[<strong>-peerkey file</strong>]
|
|
[<strong>-peerform PEM|DER|ENGINE</strong>]
|
|
[<strong>-pubin</strong>]
|
|
[<strong>-certin</strong>]
|
|
[<strong>-rev</strong>]
|
|
[<strong>-sign</strong>]
|
|
[<strong>-verify</strong>]
|
|
[<strong>-verifyrecover</strong>]
|
|
[<strong>-encrypt</strong>]
|
|
[<strong>-decrypt</strong>]
|
|
[<strong>-derive</strong>]
|
|
[<strong>-kdf algorithm</strong>]
|
|
[<strong>-kdflen length</strong>]
|
|
[<strong>-pkeyopt opt:value</strong>]
|
|
[<strong>-hexdump</strong>]
|
|
[<strong>-asn1parse</strong>]
|
|
[<strong>-rand file...</strong>]
|
|
[<strong>-writerand file</strong>]
|
|
[<strong>-engine id</strong>]
|
|
[<strong>-engine_impl</strong>]</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>The <strong>pkeyutl</strong> command can be used to perform low level public key operations
|
|
using any supported algorithm.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="options">OPTIONS</a></h1>
|
|
<dl>
|
|
<dt><strong><a name="help" class="item"><strong>-help</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Print out a usage message.</p>
|
|
</dd>
|
|
<dt><strong><a name="in_filename" class="item"><strong>-in filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This specifies the input filename to read data from or standard input
|
|
if this option is not specified.</p>
|
|
</dd>
|
|
<dt><strong><a name="out_filename" class="item"><strong>-out filename</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Specifies the output filename to write to or standard output by
|
|
default.</p>
|
|
</dd>
|
|
<dt><strong><a name="sigfile_file" class="item"><strong>-sigfile file</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Signature file, required for <strong>verify</strong> operations only</p>
|
|
</dd>
|
|
<dt><strong><a name="inkey_file" class="item"><strong>-inkey file</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The input key file, by default it should be a private key.</p>
|
|
</dd>
|
|
<dt><strong><a name="keyform_pem_der_engine" class="item"><strong>-keyform PEM|DER|ENGINE</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The key format PEM, DER or ENGINE. Default is PEM.</p>
|
|
</dd>
|
|
<dt><strong><a name="passin_arg" class="item"><strong>-passin arg</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The input key password source. For more information about the format of <strong>arg</strong>
|
|
see the <strong>PASS PHRASE ARGUMENTS</strong> section in <em>openssl(1)</em>.</p>
|
|
</dd>
|
|
<dt><strong><a name="peerkey_file" class="item"><strong>-peerkey file</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The peer key file, used by key derivation (agreement) operations.</p>
|
|
</dd>
|
|
<dt><strong><a name="peerform_pem_der_engine" class="item"><strong>-peerform PEM|DER|ENGINE</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The peer key format PEM, DER or ENGINE. Default is PEM.</p>
|
|
</dd>
|
|
<dt><strong><a name="pubin" class="item"><strong>-pubin</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The input file is a public key.</p>
|
|
</dd>
|
|
<dt><strong><a name="certin" class="item"><strong>-certin</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>The input is a certificate containing a public key.</p>
|
|
</dd>
|
|
<dt><strong><a name="rev" class="item"><strong>-rev</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Reverse the order of the input buffer. This is useful for some libraries
|
|
(such as CryptoAPI) which represent the buffer in little endian format.</p>
|
|
</dd>
|
|
<dt><strong><a name="sign" class="item"><strong>-sign</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Sign the input data (which must be a hash) and output the signed result. This
|
|
requires a private key.</p>
|
|
</dd>
|
|
<dt><strong><a name="verify" class="item"><strong>-verify</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Verify the input data (which must be a hash) against the signature file and
|
|
indicate if the verification succeeded or failed.</p>
|
|
</dd>
|
|
<dt><strong><a name="verifyrecover" class="item"><strong>-verifyrecover</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Verify the input data (which must be a hash) and output the recovered data.</p>
|
|
</dd>
|
|
<dt><strong><a name="encrypt" class="item"><strong>-encrypt</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Encrypt the input data using a public key.</p>
|
|
</dd>
|
|
<dt><strong><a name="decrypt" class="item"><strong>-decrypt</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Decrypt the input data using a private key.</p>
|
|
</dd>
|
|
<dt><strong><a name="derive" class="item"><strong>-derive</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Derive a shared secret using the peer key.</p>
|
|
</dd>
|
|
<dt><strong><a name="kdf_algorithm" class="item"><strong>-kdf algorithm</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Use key derivation function <strong>algorithm</strong>. The supported algorithms are
|
|
at present <strong>TLS1-PRF</strong> and <strong>HKDF</strong>.
|
|
Note: additional parameters and the KDF output length will normally have to be
|
|
set for this to work.
|
|
See <em>EVP_PKEY_CTX_set_hkdf_md(3)</em> and <em>EVP_PKEY_CTX_set_tls1_prf_md(3)</em>
|
|
for the supported string parameters of each algorithm.</p>
|
|
</dd>
|
|
<dt><strong><a name="kdflen_length" class="item"><strong>-kdflen length</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Set the output length for KDF.</p>
|
|
</dd>
|
|
<dt><strong><a name="pkeyopt_opt_value" class="item"><strong>-pkeyopt opt:value</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Public key options specified as opt:value. See NOTES below for more details.</p>
|
|
</dd>
|
|
<dt><strong><a name="hexdump" class="item"><strong>-hexdump</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>hex dump the output data.</p>
|
|
</dd>
|
|
<dt><strong><a name="asn1parse" class="item"><strong>-asn1parse</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Parse the ASN.1 output data, this is useful when combined with the
|
|
<strong>-verifyrecover</strong> option when an ASN1 structure is signed.</p>
|
|
</dd>
|
|
<dt><strong><a name="rand_file" class="item"><strong>-rand file...</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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 <strong>;</strong> for MS-Windows, <strong>,</strong> for OpenVMS, and <strong>:</strong> for
|
|
all others.</p>
|
|
</dd>
|
|
<dt><strong><a name="writerand_file" class="item">[<strong>-writerand file</strong>]</a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Writes random data to the specified <em>file</em> upon exit.
|
|
This can be used with a subsequent <strong>-rand</strong> flag.</p>
|
|
</dd>
|
|
<dt><strong><a name="engine_id" class="item"><strong>-engine id</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>Specifying an engine (by its unique <strong>id</strong> string) will cause <strong>pkeyutl</strong>
|
|
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.</p>
|
|
</dd>
|
|
<dt><strong><a name="engine_impl" class="item"><strong>-engine_impl</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>When used with the <strong>-engine</strong> option, it specifies to also use
|
|
engine <strong>id</strong> for crypto operations.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>The operations and options supported vary according to the key algorithm
|
|
and its implementation. The OpenSSL operations and options are indicated below.</p>
|
|
<p>Unless otherwise mentioned all algorithms support the <strong>digest:alg</strong> option
|
|
which specifies the digest in use for sign, verify and verifyrecover operations.
|
|
The value <strong>alg</strong> should represent a digest name as used in the
|
|
<code>EVP_get_digestbyname()</code> function for example <strong>sha1</strong>. 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 <strong>pkeyutl</strong> and for creating the structures that
|
|
make up the signature (e.g. <strong>DigestInfo</strong> in RSASSA PKCS#1 v1.5 signatures).</p>
|
|
<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 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.</p>
|
|
<p>In other words, if the value of digest is <strong>sha1</strong> the input should be the 20
|
|
bytes long binary encoding of the SHA-1 hash function output.</p>
|
|
<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.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="rsa_algorithm">RSA ALGORITHM</a></h1>
|
|
<p>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
|
|
<strong>pkeyopt</strong> values are supported:</p>
|
|
<dl>
|
|
<dt><strong><a name="rsa_padding_mode_mode" class="item"><strong>rsa_padding_mode:mode</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>This sets the RSA padding mode. Acceptable values for <strong>mode</strong> are <strong>pkcs1</strong> for
|
|
PKCS#1 padding, <strong>sslv23</strong> for SSLv23 padding, <strong>none</strong> for no padding, <strong>oaep</strong>
|
|
for <strong>OAEP</strong> mode, <strong>x931</strong> for X9.31 mode and <strong>pss</strong> for PSS.</p>
|
|
<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 <strong>DigestInfo</strong> structure. If a
|
|
digest is set then the a <strong>DigestInfo</strong> structure is used and its the length
|
|
must correspond to the digest type.</p>
|
|
<p>For <strong>oaep</strong> mode only encryption and decryption is supported.</p>
|
|
<p>For <strong>x931</strong> 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.</p>
|
|
<p>For <strong>pss</strong> mode only sign and verify are supported and the digest type must be
|
|
specified.</p>
|
|
</dd>
|
|
<dt><strong><a name="rsa_pss_saltlen_len" class="item"><strong>rsa_pss_saltlen:len</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>For <strong>pss</strong> 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
|
|
<strong>PSS</strong> block structure.</p>
|
|
</dd>
|
|
<dt><strong><a name="rsa_mgf1_md_digest" class="item"><strong>rsa_mgf1_md:digest</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>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.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="rsa_pss_algorithm">RSA-PSS ALGORITHM</a></h1>
|
|
<p>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 <strong>pkeyopt</strong> values are supported:</p>
|
|
<dl>
|
|
<dt><strong><a name="rsa_padding_mode_mode_rsa_pss_saltlen_len_rsa_mgf1_md_digest" class="item"><strong>rsa_padding_mode:mode</strong>, <strong>rsa_pss_saltlen:len</strong>, <strong>rsa_mgf1_md:digest</strong></a></strong></dt>
|
|
|
|
<dd>
|
|
<p>These have the same meaning as the <strong>RSA</strong> algorithm with some additional
|
|
restrictions. The padding mode can only be set to <strong>pss</strong> which is the
|
|
default value.</p>
|
|
<p>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.</p>
|
|
</dd>
|
|
</dl>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="dsa_algorithm">DSA ALGORITHM</a></h1>
|
|
<p>The DSA algorithm supports signing and verification operations only. Currently
|
|
there are no additional <strong>-pkeyopt</strong> options other than <strong>digest</strong>. The SHA1
|
|
digest is assumed by default.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="dh_algorithm">DH ALGORITHM</a></h1>
|
|
<p>The DH algorithm only supports the derivation operation and no additional
|
|
<strong>-pkeyopt</strong> options.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="ec_algorithm">EC ALGORITHM</a></h1>
|
|
<p>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 <strong>-pkeyopt</strong> <strong>digest</strong> option.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="x25519_and_x448_algorithms">X25519 and X448 ALGORITHMS</a></h1>
|
|
<p>The X25519 and X448 algorithms support key derivation only. Currently there are
|
|
no additional options.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>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 RSA key is used):</p>
|
|
<pre>
|
|
openssl pkeyutl -verifyrecover -in sig -inkey key.pem</pre>
|
|
<p>Verify the signature (e.g. a DSA 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 RSA):</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 TLS1 PRF using digest <strong>SHA256</strong> 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>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>genpkey(1)</em>, <em>pkey(1)</em>, <em>rsautl(1)</em>
|
|
<em>dgst(1)</em>, <em>rsa(1)</em>, <em>genrsa(1)</em>,
|
|
<em>EVP_PKEY_CTX_set_hkdf_md(3)</em>, <em>EVP_PKEY_CTX_set_tls1_prf_md(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2006-2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<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 LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|