1=pod
2
3=head1 NAME
4
5pkcs8 - PKCS#8 format private key conversion tool
6
7=head1 SYNOPSIS
8
9B<openssl> B<pkcs8>
10[B<-topk8>]
11[B<-inform PEM|DER>]
12[B<-outform PEM|DER>]
13[B<-in filename>]
14[B<-passin arg>]
15[B<-out filename>]
16[B<-passout arg>]
17[B<-noiter>]
18[B<-nocrypt>]
19[B<-nooct>]
20[B<-embed>]
21[B<-nsdb>]
22[B<-v2 alg>]
23[B<-v2prf alg>]
24[B<-v1 alg>]
25[B<-engine id>]
26
27=head1 DESCRIPTION
28
29The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
30both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
31format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
32
33=head1 COMMAND OPTIONS
34
35=over 4
36
37=item B<-topk8>
38
39Normally a PKCS#8 private key is expected on input and a traditional format
40private key will be written. With the B<-topk8> option the situation is
41reversed: it reads a traditional format private key and writes a PKCS#8
42format key.
43
44=item B<-inform DER|PEM>
45
46This specifies the input format. If a PKCS#8 format key is expected on input
47then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
48expected. Otherwise the B<DER> or B<PEM> format of the traditional format
49private key is used.
50
51=item B<-outform DER|PEM>
52
53This specifies the output format, the options have the same meaning as the 
54B<-inform> option.
55
56=item B<-in filename>
57
58This specifies the input filename to read a key from or standard input if this
59option is not specified. If the key is encrypted a pass phrase will be
60prompted for.
61
62=item B<-passin arg>
63
64the input file password source. For more information about the format of B<arg>
65see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
66
67=item B<-out filename>
68
69This specifies the output filename to write a key to or standard output by
70default. If any encryption options are set then a pass phrase will be
71prompted for. The output filename should B<not> be the same as the input
72filename.
73
74=item B<-passout arg>
75
76the output file password source. For more information about the format of B<arg>
77see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
78
79=item B<-nocrypt>
80
81PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
82structures using an appropriate password based encryption algorithm. With
83this option an unencrypted PrivateKeyInfo structure is expected or output.
84This option does not encrypt private keys at all and should only be used
85when absolutely necessary. Certain software such as some versions of Java
86code signing software used unencrypted private keys.
87
88=item B<-nooct>
89
90This option generates RSA private keys in a broken format that some software
91uses. Specifically the private key should be enclosed in a OCTET STRING
92but some software just includes the structure itself without the
93surrounding OCTET STRING.
94
95=item B<-embed>
96
97This option generates DSA keys in a broken format. The DSA parameters are
98embedded inside the PrivateKey structure. In this form the OCTET STRING
99contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing
100the parameters and an ASN1 INTEGER containing the private key.
101
102=item B<-nsdb>
103
104This option generates DSA keys in a broken format compatible with Netscape
105private key databases. The PrivateKey contains a SEQUENCE consisting of
106the public and private keys respectively.
107
108=item B<-v2 alg>
109
110This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
111private keys are encrypted with the password based encryption algorithm
112called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
113was the strongest encryption algorithm supported in PKCS#5 v1.5. Using 
114the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
115encryption algorithm such as 168 bit triple DES or 128 bit RC2 however
116not many implementations support PKCS#5 v2.0 yet. If you are just using
117private keys with OpenSSL then this doesn't matter.
118
119The B<alg> argument is the encryption algorithm to use, valid values include
120B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
121
122=item B<-v2prf alg>
123
124This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
125values would be B<hmacWithSHA256>. If this option isn't set then the default
126for the cipher is used or B<hmacWithSHA1> if there is no default.
127
128=item B<-v1 alg>
129
130This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
131list of possible algorithms is included below.
132
133=item B<-engine id>
134
135specifying an engine (by its unique B<id> string) will cause B<pkcs8>
136to attempt to obtain a functional reference to the specified engine,
137thus initialising it if needed. The engine will then be set as the default
138for all available algorithms.
139
140=back
141
142=head1 NOTES
143
144The encrypted form of a PEM encode PKCS#8 files uses the following
145headers and footers:
146
147 -----BEGIN ENCRYPTED PRIVATE KEY-----
148 -----END ENCRYPTED PRIVATE KEY-----
149
150The unencrypted form uses:
151
152 -----BEGIN PRIVATE KEY-----
153 -----END PRIVATE KEY-----
154
155Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
156counts are more secure that those encrypted using the traditional
157SSLeay compatible formats. So if additional security is considered
158important the keys should be converted.
159
160The default encryption is only 56 bits because this is the encryption
161that most current implementations of PKCS#8 will support.
162
163Some software may use PKCS#12 password based encryption algorithms
164with PKCS#8 format private keys: these are handled automatically
165but there is no option to produce them.
166
167It is possible to write out DER encoded encrypted private keys in
168PKCS#8 format because the encryption details are included at an ASN1
169level whereas the traditional format includes them at a PEM level.
170
171=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
172
173Various algorithms can be used with the B<-v1> command line option,
174including PKCS#5 v1.5 and PKCS#12. These are described in more detail
175below.
176
177=over 4
178
179=item B<PBE-MD2-DES PBE-MD5-DES>
180
181These algorithms were included in the original PKCS#5 v1.5 specification.
182They only offer 56 bits of protection since they both use DES.
183
184=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES>
185
186These algorithms are not mentioned in the original PKCS#5 v1.5 specification
187but they use the same key derivation algorithm and are supported by some
188software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
18956 bit DES.
190
191=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40>
192
193These algorithms use the PKCS#12 password based encryption algorithm and
194allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
195
196=back
197
198=head1 EXAMPLES
199
200Convert a private from traditional to PKCS#5 v2.0 format using triple
201DES:
202
203 openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
204
205Convert a private from traditional to PKCS#5 v2.0 format using AES with
206256 bits in CBC mode and B<hmacWithSHA256> PRF:
207
208 openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem
209
210Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
211(DES):
212
213 openssl pkcs8 -in key.pem -topk8 -out enckey.pem
214
215Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
216(3DES):
217
218 openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
219
220Read a DER unencrypted PKCS#8 format private key:
221
222 openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
223
224Convert a private key from any PKCS#8 format to traditional format:
225
226 openssl pkcs8 -in pk8.pem -out key.pem
227
228=head1 STANDARDS
229
230Test vectors from this PKCS#5 v2.0 implementation were posted to the
231pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
232counts, several people confirmed that they could decrypt the private
233keys produced and Therefore it can be assumed that the PKCS#5 v2.0
234implementation is reasonably accurate at least as far as these
235algorithms are concerned.
236
237The format of PKCS#8 DSA (and other) private keys is not well documented:
238it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
239PKCS#8 private key format complies with this standard.
240
241=head1 BUGS
242
243There should be an option that prints out the encryption algorithm
244in use and other details such as the iteration count.
245
246PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
247key format for OpenSSL: for compatibility several of the utilities use
248the old format at present.
249
250=head1 SEE ALSO
251
252L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>,
253L<gendsa(1)|gendsa(1)> 
254
255=cut
256