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