=pod

=head1 NAME

pkcs8 - PKCS#8 format private key conversion tool

=head1 SYNOPSIS

B<openssl> B<pkcs8>
[B<-topk8>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
[B<-noiter>]
[B<-nocrypt>]
[B<-nooct>]
[B<-v2 alg>]

=head1 DESCRIPTION

The B<pkcs8> 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.

=head1 COMMAND OPTIONS

=over 4

=item B<-topk8>

Normally a PKCS#8 private key is expected on input and a traditional format
private key will be written. With the B<-topk8> option the situation is
reversed: it reads a traditional format private key and writes a PKCS#8
format key.

=item B<-inform DER|PEM>

This specifies the input format. If a PKCS#8 format key is expected on input
then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
expected. Otherwise the B<DER> or B<PEM> format of the traditional format
private key is used.

=item B<-outform DER|PEM>

This specifies the output format, the options have the same meaning as the 
B<-inform> option.

=item B<-in filename>

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.

=item B<-out filename>

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> be the same as the input
filename.

=item B<-nocrypt>

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.

=item B<-nooct>

This option generates private keys in a broken format that some software
uses. Specifically the private key should be enclosed in a OCTET STRING
but some software just includes the structure itself without the
surrounding OCTET STRING.

=item B<-v2 alg>

This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
private keys are encrypted with the password based encryption algorithm
called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
was the strongest encryption algorithm supported in PKCS#5 v1.5. Using 
the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
encryption algorithm such as 168 bit triple DES or 128 bit RC2 however
not many implementations support PKCS#5 v2.0 yet. If you are just using
private keys with OpenSSL then this doesn't matter.

The B<alg> argument is the encryption algorithm to use, valid values include
B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.

=back

=head1 NOTES

The encrypted form of a PEM encode PKCS#8 files uses the following
headers and footers:

 -----BEGIN ENCRYPTED PRIVATE KEY-----
 -----END ENCRYPTED PRIVATE KEY-----

The unencrypted form uses:

 -----BEGIN PRIVATE KEY-----
 -----END PRIVATE KEY-----

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.

The default encryption is only 56 bits because this is the encryption
that most current implementations of PKCS#8 will support.

Some software may use PKCS#12 password based encryption algorithms
with PKCS#8 format private keys: these are handled automatically
but there is no option to produce them.

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.

=head1 EXAMPLES

Convert a private from traditional to PKCS#5 v2.0 format using triple
DES:

 openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem

Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
(DES):

 openssl pkcs8 -in key.pem -topk8 -out enckey.pem

Read a DER unencrypted PKCS#8 format private key:

 openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem

Convert a private key from any PKCS#8 format to traditional format:

 openssl pkcs8 -in pk8.pem -out key.pem

=head1 STANDARDS

Test vectors from this 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.

=head1 BUGS

It isn't possible to produce keys encrypted using PKCS#5 v1.5 algorithms
other than B<pbeWithMD5AndDES-CBC> using this utility.

There should be an option that prints out the encryption algorithm
in use and other details such as the iteration count.

PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
key format for OpenSSL: for compatability several of the utilities use
the old format at present.

=head1 SEE ALSO

dsa(1), rsa(1), genrsa(1), gendsa(1)

=cut