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