331 lines
14 KiB
HTML
331 lines
14 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>openssl-pkcs8</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="#pkcs_5_v1_5_and_pkcs_12_algorithms">PKCS#5 V1.5 AND PKCS#12 ALGORITHMS</a></li>
|
||
|
<li><a href="#examples">EXAMPLES</a></li>
|
||
|
<li><a href="#standards">STANDARDS</a></li>
|
||
|
<li><a href="#bugs">BUGS</a></li>
|
||
|
<li><a href="#see_also">SEE ALSO</a></li>
|
||
|
<li><a href="#history">HISTORY</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-pkcs8 - PKCS#8 format private key conversion tool</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||
|
<p><strong>openssl</strong> <strong>pkcs8</strong>
|
||
|
[<strong>-help</strong>]
|
||
|
[<strong>-topk8</strong>]
|
||
|
[<strong>-inform</strong> <strong>DER</strong>|<strong>PEM</strong>]
|
||
|
[<strong>-outform</strong> <strong>DER</strong>|<strong>PEM</strong>]
|
||
|
[<strong>-in</strong> <em>filename</em>]
|
||
|
[<strong>-passin</strong> <em>arg</em>]
|
||
|
[<strong>-out</strong> <em>filename</em>]
|
||
|
[<strong>-passout</strong> <em>arg</em>]
|
||
|
[<strong>-iter</strong> <em>count</em>]
|
||
|
[<strong>-noiter</strong>]
|
||
|
[<strong>-nocrypt</strong>]
|
||
|
[<strong>-traditional</strong>]
|
||
|
[<strong>-v2</strong> <em>alg</em>]
|
||
|
[<strong>-v2prf</strong> <em>alg</em>]
|
||
|
[<strong>-v1</strong> <em>alg</em>]
|
||
|
[<strong>-scrypt</strong>]
|
||
|
[<strong>-scrypt_N</strong> <em>N</em>]
|
||
|
[<strong>-scrypt_r</strong> <em>r</em>]
|
||
|
[<strong>-scrypt_p</strong> <em>p</em>]
|
||
|
[<strong>-rand</strong> <em>files</em>]
|
||
|
[<strong>-writerand</strong> <em>file</em>]
|
||
|
[<strong>-engine</strong> <em>id</em>]</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="description">DESCRIPTION</a></h1>
|
||
|
<p>This command processes private keys in PKCS#8 format. It can handle
|
||
|
both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
|
||
|
format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.</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="topk8" class="item"><strong>-topk8</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Normally a PKCS#8 private key is expected on input and a private key will be
|
||
|
written to the output file. With the <strong>-topk8</strong> option the situation is
|
||
|
reversed: it reads a private key and writes a PKCS#8 format key.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="inform_der_pem_outform_der_pem" class="item"><strong>-inform</strong> <strong>DER</strong>|<strong>PEM</strong>, <strong>-outform</strong> <strong>DER</strong>|<strong>PEM</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>The input and formats; the default is <strong>PEM</strong>.
|
||
|
See <em>openssl(1)/Format Options</em> for details.</p>
|
||
|
<p>If a key is being converted from PKCS#8 form (i.e. the <strong>-topk8</strong> option is
|
||
|
not used) then the input file must be in PKCS#8 format. An encrypted
|
||
|
key is expected unless <strong>-nocrypt</strong> is included.</p>
|
||
|
<p>If <strong>-topk8</strong> is not used and <strong>PEM</strong> mode is set the output file will be an
|
||
|
unencrypted private key in PKCS#8 format. If the <strong>-traditional</strong> option is
|
||
|
used then a traditional format private key is written instead.</p>
|
||
|
<p>If <strong>-topk8</strong> is not used and <strong>DER</strong> mode is set the output file will be an
|
||
|
unencrypted private key in traditional DER format.</p>
|
||
|
<p>If <strong>-topk8</strong> is used then any supported private key can be used for the input
|
||
|
file in a format specified by <strong>-inform</strong>. The output file will be encrypted
|
||
|
PKCS#8 format using the specified encryption parameters unless <strong>-nocrypt</strong>
|
||
|
is included.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="traditional" class="item"><strong>-traditional</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>When this option is present and <strong>-topk8</strong> is not a traditional format private
|
||
|
key is written.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="in_filename" class="item"><strong>-in</strong> <em>filename</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>This specifies the input filename to read a key from or standard input if this
|
||
|
option is not specified. If the key is encrypted a pass phrase will be
|
||
|
prompted for.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="passin_arg_passout_arg" class="item"><strong>-passin</strong> <em>arg</em>, <strong>-passout</strong> <em>arg</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>The password source for the input and output file.
|
||
|
For more information about the format of <strong>arg</strong>
|
||
|
see <em>openssl(1)/Pass Phrase Options</em>.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="out_filename" class="item"><strong>-out</strong> <em>filename</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>This specifies the output filename to write a key to or standard output by
|
||
|
default. If any encryption options are set then a pass phrase will be
|
||
|
prompted for. The output filename should <strong>not</strong> be the same as the input
|
||
|
filename.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="iter_count" class="item"><strong>-iter</strong> <em>count</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>When creating new PKCS#8 containers, use a given number of iterations on
|
||
|
the password in deriving the encryption key for the PKCS#8 output.
|
||
|
High values increase the time required to brute-force a PKCS#8 container.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="nocrypt" class="item"><strong>-nocrypt</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
|
||
|
structures using an appropriate password based encryption algorithm. With
|
||
|
this option an unencrypted PrivateKeyInfo structure is expected or output.
|
||
|
This option does not encrypt private keys at all and should only be used
|
||
|
when absolutely necessary. Certain software such as some versions of Java
|
||
|
code signing software used unencrypted private keys.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="v2_alg" class="item"><strong>-v2</strong> <em>alg</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>This option sets the PKCS#5 v2.0 algorithm.</p>
|
||
|
<p>The <em>alg</em> argument is the encryption algorithm to use, valid values include
|
||
|
<strong>aes128</strong>, <strong>aes256</strong> and <strong>des3</strong>. If this option isn't specified then <strong>aes256</strong>
|
||
|
is used.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="v2prf_alg" class="item"><strong>-v2prf</strong> <em>alg</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
|
||
|
value would be <strong>hmacWithSHA256</strong>. If this option isn't set then the default
|
||
|
for the cipher is used or <strong>hmacWithSHA256</strong> if there is no default.</p>
|
||
|
<p>Some implementations may not support custom PRF algorithms and may require
|
||
|
the <strong>hmacWithSHA1</strong> option to work.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="v1_alg" class="item"><strong>-v1</strong> <em>alg</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some
|
||
|
older implementations may not support PKCS#5 v2.0 and may require this option.
|
||
|
If not specified PKCS#5 v2.0 form is used.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="scrypt" class="item"><strong>-scrypt</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Uses the <strong>scrypt</strong> algorithm for private key encryption using default
|
||
|
parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
|
||
|
key. These parameters can be modified using the <strong>-scrypt_N</strong>, <strong>-scrypt_r</strong>,
|
||
|
<strong>-scrypt_p</strong> and <strong>-v2</strong> options.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="scrypt_n_n_scrypt_r_r_scrypt_p_p" class="item"><strong>-scrypt_N</strong> <em>N</em>, <strong>-scrypt_r</strong> <em>r</em>, <strong>-scrypt_p</strong> <em>p</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Sets the scrypt <em>N</em>, <em>r</em> or <em>p</em> parameters.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="rand_files_writerand_file" class="item"><strong>-rand</strong> <em>files</em>, <strong>-writerand</strong> <em>file</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>See <em>openssl(1)/Random State Options</em> for details.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="engine_id" class="item"><strong>-engine</strong> <em>id</em></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>See <em>openssl(1)/Engine Options</em>.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="notes">NOTES</a></h1>
|
||
|
<p>By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
|
||
|
AES with HMAC and SHA256 is used.</p>
|
||
|
<p>Some older implementations do not support PKCS#5 v2.0 format and require
|
||
|
the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
|
||
|
encryption algorithms such as 56 bit DES.</p>
|
||
|
<p>Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
|
||
|
counts are more secure that those encrypted using the traditional
|
||
|
SSLeay compatible formats. So if additional security is considered
|
||
|
important the keys should be converted.</p>
|
||
|
<p>It is possible to write out DER encoded encrypted private keys in
|
||
|
PKCS#8 format because the encryption details are included at an ASN1
|
||
|
level whereas the traditional format includes them at a PEM level.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="pkcs_5_v1_5_and_pkcs_12_algorithms">PKCS#5 V1.5 AND PKCS#12 ALGORITHMS</a></h1>
|
||
|
<p>Various algorithms can be used with the <strong>-v1</strong> command line option,
|
||
|
including PKCS#5 v1.5 and PKCS#12. These are described in more detail
|
||
|
below.</p>
|
||
|
<dl>
|
||
|
<dt><strong><a name="pbe_md2_des_pbe_md5_des" class="item"><strong>PBE-MD2-DES PBE-MD5-DES</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>These algorithms were included in the original PKCS#5 v1.5 specification.
|
||
|
They only offer 56 bits of protection since they both use DES.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="pbe_sha1_rc2_64_pbe_md2_rc2_64_pbe_md5_rc2_64_pbe_sha1_des" class="item"><strong>PBE-SHA1-RC2-64</strong>, <strong>PBE-MD2-RC2-64</strong>, <strong>PBE-MD5-RC2-64</strong>, <strong>PBE-SHA1-DES</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>These algorithms are not mentioned in the original PKCS#5 v1.5 specification
|
||
|
but they use the same key derivation algorithm and are supported by some
|
||
|
software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
|
||
|
56 bit DES.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="pbe_sha1_rc4_128_pbe_sha1_rc4_40_pbe_sha1_3des_pbe_sha1_2des_pbe_sha1_rc2_128_pbe_sha1_rc2_40" class="item"><strong>PBE-SHA1-RC4-128</strong>, <strong>PBE-SHA1-RC4-40</strong>, <strong>PBE-SHA1-3DES</strong>, <strong>PBE-SHA1-2DES</strong>, <strong>PBE-SHA1-RC2-128</strong>, <strong>PBE-SHA1-RC2-40</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>These algorithms use the PKCS#12 password based encryption algorithm and
|
||
|
allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="examples">EXAMPLES</a></h1>
|
||
|
<p>Convert a private key to PKCS#8 format using default parameters (AES with
|
||
|
256 bit key and <strong>hmacWithSHA256</strong>):</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -in key.pem -topk8 -out enckey.pem</pre>
|
||
|
<p>Convert a private key to PKCS#8 unencrypted format:</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem</pre>
|
||
|
<p>Convert a private key to PKCS#5 v2.0 format using triple DES:</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem</pre>
|
||
|
<p>Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
|
||
|
mode and <strong>hmacWithSHA512</strong> PRF:</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem</pre>
|
||
|
<p>Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
|
||
|
(DES):</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem</pre>
|
||
|
<p>Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
|
||
|
(3DES):</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES</pre>
|
||
|
<p>Read a DER unencrypted PKCS#8 format private key:</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem</pre>
|
||
|
<p>Convert a private key from any PKCS#8 encrypted format to traditional format:</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -in pk8.pem -traditional -out key.pem</pre>
|
||
|
<p>Convert a private key to PKCS#8 format, encrypting with AES-256 and with
|
||
|
one million iterations of the password:</p>
|
||
|
<pre>
|
||
|
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem</pre>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="standards">STANDARDS</a></h1>
|
||
|
<p>Test vectors from this PKCS#5 v2.0 implementation were posted to the
|
||
|
pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
|
||
|
counts, several people confirmed that they could decrypt the private
|
||
|
keys produced and Therefore it can be assumed that the PKCS#5 v2.0
|
||
|
implementation is reasonably accurate at least as far as these
|
||
|
algorithms are concerned.</p>
|
||
|
<p>The format of PKCS#8 DSA (and other) private keys is not well documented:
|
||
|
it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
|
||
|
PKCS#8 private key format complies with this standard.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="bugs">BUGS</a></h1>
|
||
|
<p>There should be an option that prints out the encryption algorithm
|
||
|
in use and other details such as the iteration count.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
||
|
<p><em>openssl(1)</em>,
|
||
|
<em>openssl-dsa(1)</em>,
|
||
|
<em>openssl-rsa(1)</em>,
|
||
|
<em>openssl-genrsa(1)</em>,
|
||
|
<em>openssl-gendsa(1)</em></p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="history">HISTORY</a></h1>
|
||
|
<p>The <strong>-iter</strong> option was added in OpenSSL 1.1.0.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||
|
<p>Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
<p>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
|
||
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
||
|
</body>
|
||
|
|
||
|
</html>
|