491 lines
14 KiB
HTML
491 lines
14 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of PKCS8</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>PKCS8</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-pkcs8, pkcs8 - PKCS#8 format private key conversion tool
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
<B>openssl</B> <B>pkcs8</B>
|
|
[<B>-help</B>]
|
|
[<B>-topk8</B>]
|
|
[<B>-inform PEM|DER</B>]
|
|
[<B>-outform PEM|DER</B>]
|
|
[<B>-in filename</B>]
|
|
[<B>-passin arg</B>]
|
|
[<B>-out filename</B>]
|
|
[<B>-passout arg</B>]
|
|
[<B>-iter count</B>]
|
|
[<B>-noiter</B>]
|
|
[<B>-rand file...</B>]
|
|
[<B>-writerand file</B>]
|
|
[<B>-nocrypt</B>]
|
|
[<B>-traditional</B>]
|
|
[<B>-v2 alg</B>]
|
|
[<B>-v2prf alg</B>]
|
|
[<B>-v1 alg</B>]
|
|
[<B>-engine id</B>]
|
|
[<B>-scrypt</B>]
|
|
[<B>-scrypt_N N</B>]
|
|
[<B>-scrypt_r r</B>]
|
|
[<B>-scrypt_p p</B>]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <B>pkcs8</B> 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.
|
|
<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>-topk8</B><DD>
|
|
|
|
|
|
Normally a PKCS#8 private key is expected on input and a private key will be
|
|
written to the output file. With the <B>-topk8</B> option the situation is
|
|
reversed: it reads a private key and writes a PKCS#8 format key.
|
|
<DT id="3"><B>-inform DER|PEM</B><DD>
|
|
|
|
|
|
This specifies the input format: see ``<FONT SIZE="-1">KEY FORMATS''</FONT> for more details. The default
|
|
format is <FONT SIZE="-1">PEM.</FONT>
|
|
<DT id="4"><B>-outform DER|PEM</B><DD>
|
|
|
|
|
|
This specifies the output format: see ``<FONT SIZE="-1">KEY FORMATS''</FONT> for more details. The default
|
|
format is <FONT SIZE="-1">PEM.</FONT>
|
|
<DT id="5"><B>-traditional</B><DD>
|
|
|
|
|
|
When this option is present and <B>-topk8</B> is not a traditional format private
|
|
key is written.
|
|
<DT id="6"><B>-in filename</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="7"><B>-passin arg</B><DD>
|
|
|
|
|
|
The input file 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>-out filename</B><DD>
|
|
|
|
|
|
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 <B>not</B> be the same as the input
|
|
filename.
|
|
<DT id="9"><B>-passout arg</B><DD>
|
|
|
|
|
|
The output file 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="10"><B>-iter count</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="11"><B>-nocrypt</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="12"><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="13">[<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="14"><B>-v2 alg</B><DD>
|
|
|
|
|
|
This option sets the PKCS#5 v2.0 algorithm.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>alg</B> argument is the encryption algorithm to use, valid values include
|
|
<B>aes128</B>, <B>aes256</B> and <B>des3</B>. If this option isn't specified then <B>aes256</B>
|
|
is used.
|
|
<DT id="15"><B>-v2prf alg</B><DD>
|
|
|
|
|
|
This option sets the <FONT SIZE="-1">PRF</FONT> algorithm to use with PKCS#5 v2.0. A typical value
|
|
value would be <B>hmacWithSHA256</B>. If this option isn't set then the default
|
|
for the cipher is used or <B>hmacWithSHA256</B> if there is no default.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Some implementations may not support custom <FONT SIZE="-1">PRF</FONT> algorithms and may require
|
|
the <B>hmacWithSHA1</B> option to work.
|
|
<DT id="16"><B>-v1 alg</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="17"><B>-engine id</B><DD>
|
|
|
|
|
|
Specifying an engine (by its unique <B>id</B> string) will cause <B>pkcs8</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="18"><B>-scrypt</B><DD>
|
|
|
|
|
|
Uses the <B>scrypt</B> algorithm for private key encryption using default
|
|
parameters: currently N=16384, r=8 and p=1 and <FONT SIZE="-1">AES</FONT> in <FONT SIZE="-1">CBC</FONT> mode with a 256 bit
|
|
key. These parameters can be modified using the <B>-scrypt_N</B>, <B>-scrypt_r</B>,
|
|
<B>-scrypt_p</B> and <B>-v2</B> options.
|
|
<DT id="19"><B>-scrypt_N N</B> <B>-scrypt_r r</B> <B>-scrypt_p p</B><DD>
|
|
|
|
|
|
Sets the scrypt <B>N</B>, <B>r</B> or <B>p</B> parameters.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>KEY FORMATS</H2>
|
|
|
|
|
|
|
|
Various different formats are used by the pkcs8 utility. These are detailed
|
|
below.
|
|
<P>
|
|
|
|
If a key is being converted from PKCS#8 form (i.e. the <B>-topk8</B> option is
|
|
not used) then the input file must be in PKCS#8 format. An encrypted
|
|
key is expected unless <B>-nocrypt</B> is included.
|
|
<P>
|
|
|
|
If <B>-topk8</B> is not used and <B></B><FONT SIZE="-1"><B>PEM</B></FONT><B></B> mode is set the output file will be an
|
|
unencrypted private key in PKCS#8 format. If the <B>-traditional</B> option is
|
|
used then a traditional format private key is written instead.
|
|
<P>
|
|
|
|
If <B>-topk8</B> is not used and <B></B><FONT SIZE="-1"><B>DER</B></FONT><B></B> mode is set the output file will be an
|
|
unencrypted private key in traditional <FONT SIZE="-1">DER</FONT> format.
|
|
<P>
|
|
|
|
If <B>-topk8</B> is used then any supported private key can be used for the input
|
|
file in a format specified by <B>-inform</B>. The output file will be encrypted
|
|
PKCS#8 format using the specified encryption parameters unless <B>-nocrypt</B>
|
|
is included.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
|
|
|
|
By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
|
|
<FONT SIZE="-1">AES</FONT> with <FONT SIZE="-1">HMAC</FONT> and <FONT SIZE="-1">SHA256</FONT> is used.
|
|
<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 <FONT SIZE="-1">DES.</FONT>
|
|
<P>
|
|
|
|
The encrypted form of a <FONT SIZE="-1">PEM</FONT> encode PKCS#8 files uses the following
|
|
headers and footers:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
-----BEGIN ENCRYPTED PRIVATE KEY-----
|
|
-----END ENCRYPTED PRIVATE KEY-----
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The unencrypted form uses:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
-----BEGIN PRIVATE KEY-----
|
|
-----END PRIVATE KEY-----
|
|
|
|
</PRE>
|
|
|
|
|
|
<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>
|
|
|
|
It is possible to write out <FONT SIZE="-1">DER</FONT> encoded encrypted private keys in
|
|
PKCS#8 format because the encryption details are included at an <FONT SIZE="-1">ASN1</FONT>
|
|
level whereas the traditional format includes them at a <FONT SIZE="-1">PEM</FONT> level.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>PKCS#5 v1.5 and PKCS#12 algorithms.</H2>
|
|
|
|
|
|
|
|
Various algorithms can be used with the <B>-v1</B> command line option,
|
|
including PKCS#5 v1.5 and PKCS#12. These are described in more detail
|
|
below.
|
|
<DL COMPACT>
|
|
<DT id="20"><B></B><FONT SIZE="-1"><B>PBE-MD2-DES PBE-MD5-DES</B></FONT><B></B><DD>
|
|
|
|
|
|
These algorithms were included in the original PKCS#5 v1.5 specification.
|
|
They only offer 56 bits of protection since they both use <FONT SIZE="-1">DES.</FONT>
|
|
<DT id="21"><B></B><FONT SIZE="-1"><B>PBE-SHA1-RC2-64</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>PBE-MD2-RC2-64</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>PBE-MD5-RC2-64</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>PBE-SHA1-DES</B></FONT><B></B><DD>
|
|
|
|
|
|
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 <FONT SIZE="-1">RC2</FONT> or
|
|
56 bit <FONT SIZE="-1">DES.</FONT>
|
|
<DT id="22"><B></B><FONT SIZE="-1"><B>PBE-SHA1-RC4-128</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>PBE-SHA1-RC4-40</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>PBE-SHA1-3DES</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>PBE-SHA1-2DES</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>PBE-SHA1-RC2-128</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>PBE-SHA1-RC2-40</B></FONT><B></B><DD>
|
|
|
|
|
|
These algorithms use the PKCS#12 password based encryption algorithm and
|
|
allow strong encryption algorithms like triple <FONT SIZE="-1">DES</FONT> or 128 bit <FONT SIZE="-1">RC2</FONT> to be used.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
|
|
|
|
Convert a private key to PKCS#8 format using default parameters (<FONT SIZE="-1">AES</FONT> with
|
|
256 bit key and <B>hmacWithSHA256</B>):
|
|
<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 <FONT SIZE="-1">DES:</FONT>
|
|
<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 <FONT SIZE="-1">AES</FONT> with 256 bits in <FONT SIZE="-1">CBC</FONT>
|
|
mode and <B>hmacWithSHA512</B> <FONT SIZE="-1">PRF:</FONT>
|
|
<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
|
|
(<FONT SIZE="-1">DES</FONT>):
|
|
<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 <FONT SIZE="-1">DER</FONT> 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 <FONT SIZE="-1">AES-256</FONT> 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>
|
|
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>STANDARDS</H2>
|
|
|
|
|
|
|
|
Test vectors from this PKCS#5 v2.0 implementation were posted to the
|
|
pkcs-tng mailing list using triple <FONT SIZE="-1">DES, DES</FONT> and <FONT SIZE="-1">RC2</FONT> 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>
|
|
|
|
The format of PKCS#8 <FONT SIZE="-1">DSA</FONT> (and other) private keys is not well documented:
|
|
it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default <FONT SIZE="-1">DSA</FONT>
|
|
PKCS#8 private key format complies with this standard.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
|
|
|
|
There should be an option that prints out the encryption algorithm
|
|
in use and other details such as the iteration count.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+dsa">dsa</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?1+gendsa">gendsa</A></B>(1)
|
|
<A NAME="lbAM"> </A>
|
|
<H2>HISTORY</H2>
|
|
|
|
|
|
|
|
The <B>-iter</B> option was added in OpenSSL 1.1.0.
|
|
<A NAME="lbAN"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright 2000-2018 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="23"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="24"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="25"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="26"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="27"><A HREF="#lbAF">KEY FORMATS</A><DD>
|
|
<DT id="28"><A HREF="#lbAG">NOTES</A><DD>
|
|
<DT id="29"><A HREF="#lbAH">PKCS#5 v1.5 and PKCS#12 algorithms.</A><DD>
|
|
<DT id="30"><A HREF="#lbAI">EXAMPLES</A><DD>
|
|
<DT id="31"><A HREF="#lbAJ">STANDARDS</A><DD>
|
|
<DT id="32"><A HREF="#lbAK">BUGS</A><DD>
|
|
<DT id="33"><A HREF="#lbAL">SEE ALSO</A><DD>
|
|
<DT id="34"><A HREF="#lbAM">HISTORY</A><DD>
|
|
<DT id="35"><A HREF="#lbAN">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>
|