2 ''' $RCSfile$$Revision$$Date$
20 .ie \\n(.$>=3 .ne \\$3
36 ''' Set up \*(-- to give an unbreakable dash;
37 ''' string Tr holds user defined translation string.
38 ''' Bell System Logo is used as a dummy character.
44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
48 ''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49 ''' \*(L" and \*(R", except that they are used on ".xx" lines,
50 ''' such as .IP and .SH, which do another additional levels of
51 ''' double-quote interpretation
80 .\" If the F register is turned on, we'll generate
81 .\" index entries out stderr for the following things:
86 .\" X<> Xref (embedded
87 .\" Of course, you have to process the output yourself
88 .\" in some meaninful fashion.
91 .tm Index:\\$1\t\\n%\t"\\$2"
96 .TH PKCS8 1 "0.9.7d" "2/Sep/2004" "OpenSSL"
100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101 .de CQ \" put $1 in typewriter font
107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111 . \" AM - accent mark definitions
113 . \" fudge factors for nroff and troff
122 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
128 . \" simple accents for nroff and troff
141 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146 . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147 . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149 . ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
151 . \" troff and (daisy-wheel) nroff accents
152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163 .ds ae a\h'-(\w'a'u*4/10)'e
164 .ds Ae A\h'-(\w'A'u*4/10)'E
165 .ds oe o\h'-(\w'o'u*4/10)'e
166 .ds Oe O\h'-(\w'O'u*4/10)'E
167 . \" corrections for vroff
168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
170 . \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
175 . ds v \h'-1'\o'\(aa\(ga'
191 pkcs8 \- PKCS#8 format private key conversion tool
193 \fBopenssl\fR \fBpkcs8\fR
195 [\fB\-inform PEM|DER\fR]
196 [\fB\-outform PEM|DER\fR]
197 [\fB\-in filename\fR]
199 [\fB\-out filename\fR]
200 [\fB\-passout arg\fR]
210 The \fBpkcs8\fR command processes private keys in PKCS#8 format. It can handle
211 both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
212 format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
213 .SH "COMMAND OPTIONS"
214 .Ip "\fB\-topk8\fR" 4
215 Normally a \s-1PKCS\s0#8 private key is expected on input and a traditional format
216 private key will be written. With the \fB\-topk8\fR option the situation is
217 reversed: it reads a traditional format private key and writes a \s-1PKCS\s0#8
219 .Ip "\fB\-inform \s-1DER\s0|\s-1PEM\s0\fR" 4
220 This specifies the input format. If a \s-1PKCS\s0#8 format key is expected on input
221 then either a \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR encoded version of a \s-1PKCS\s0#8 key will be
222 expected. Otherwise the \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR format of the traditional format
224 .Ip "\fB\-outform \s-1DER\s0|\s-1PEM\s0\fR" 4
225 This specifies the output format, the options have the same meaning as the
226 \fB\-inform\fR option.
227 .Ip "\fB\-in filename\fR" 4
228 This specifies the input filename to read a key from or standard input if this
229 option is not specified. If the key is encrypted a pass phrase will be
231 .Ip "\fB\-passin arg\fR" 4
232 the input file password source. For more information about the format of \fBarg\fR
233 see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
234 .Ip "\fB\-out filename\fR" 4
235 This specifies the output filename to write a key to or standard output by
236 default. If any encryption options are set then a pass phrase will be
237 prompted for. The output filename should \fBnot\fR be the same as the input
239 .Ip "\fB\-passout arg\fR" 4
240 the output file password source. For more information about the format of \fBarg\fR
241 see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
242 .Ip "\fB\-nocrypt\fR" 4
243 \s-1PKCS\s0#8 keys generated or input are normally \s-1PKCS\s0#8 EncryptedPrivateKeyInfo
244 structures using an appropriate password based encryption algorithm. With
245 this option an unencrypted PrivateKeyInfo structure is expected or output.
246 This option does not encrypt private keys at all and should only be used
247 when absolutely necessary. Certain software such as some versions of Java
248 code signing software used unencrypted private keys.
249 .Ip "\fB\-nooct\fR" 4
250 This option generates \s-1RSA\s0 private keys in a broken format that some software
251 uses. Specifically the private key should be enclosed in a \s-1OCTET\s0 \s-1STRING\s0
252 but some software just includes the structure itself without the
253 surrounding \s-1OCTET\s0 \s-1STRING\s0.
254 .Ip "\fB\-embed\fR" 4
255 This option generates \s-1DSA\s0 keys in a broken format. The \s-1DSA\s0 parameters are
256 embedded inside the PrivateKey structure. In this form the \s-1OCTET\s0 \s-1STRING\s0
257 contains an \s-1ASN1\s0 \s-1SEQUENCE\s0 consisting of two structures: a \s-1SEQUENCE\s0 containing
258 the parameters and an \s-1ASN1\s0 \s-1INTEGER\s0 containing the private key.
260 This option generates \s-1DSA\s0 keys in a broken format compatible with Netscape
261 private key databases. The PrivateKey contains a \s-1SEQUENCE\s0 consisting of
262 the public and private keys respectively.
263 .Ip "\fB\-v2 alg\fR" 4
264 This option enables the use of \s-1PKCS\s0#5 v2.0 algorithms. Normally \s-1PKCS\s0#8
265 private keys are encrypted with the password based encryption algorithm
266 called \fBpbeWithMD5AndDES\-\s-1CBC\s0\fR this uses 56 bit \s-1DES\s0 encryption but it
267 was the strongest encryption algorithm supported in \s-1PKCS\s0#5 v1.5. Using
268 the \fB\-v2\fR option \s-1PKCS\s0#5 v2.0 algorithms are used which can use any
269 encryption algorithm such as 168 bit triple \s-1DES\s0 or 128 bit \s-1RC2\s0 however
270 not many implementations support \s-1PKCS\s0#5 v2.0 yet. If you are just using
271 private keys with OpenSSL then this doesn't matter.
273 The \fBalg\fR argument is the encryption algorithm to use, valid values include
274 \fBdes\fR, \fBdes3\fR and \fBrc2\fR. It is recommended that \fBdes3\fR is used.
275 .Ip "\fB\-v1 alg\fR" 4
276 This option specifies a \s-1PKCS\s0#5 v1.5 or \s-1PKCS\s0#12 algorithm to use. A complete
277 list of possible algorithms is included below.
278 .Ip "\fB\-engine id\fR" 4
279 specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
280 to attempt to obtain a functional reference to the specified engine,
281 thus initialising it if needed. The engine will then be set as the default
282 for all available algorithms.
284 The encrypted form of a PEM encode PKCS#8 files uses the following
288 \& -----BEGIN ENCRYPTED PRIVATE KEY-----
289 \& -----END ENCRYPTED PRIVATE KEY-----
291 The unencrypted form uses:
294 \& -----BEGIN PRIVATE KEY-----
295 \& -----END PRIVATE KEY-----
297 Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
298 counts are more secure that those encrypted using the traditional
299 SSLeay compatible formats. So if additional security is considered
300 important the keys should be converted.
302 The default encryption is only 56 bits because this is the encryption
303 that most current implementations of PKCS#8 will support.
305 Some software may use PKCS#12 password based encryption algorithms
306 with PKCS#8 format private keys: these are handled automatically
307 but there is no option to produce them.
309 It is possible to write out DER encoded encrypted private keys in
310 PKCS#8 format because the encryption details are included at an ASN1
311 level whereas the traditional format includes them at a PEM level.
312 .SH "PKCS#5 v1.5 and PKCS#12 algorithms."
313 Various algorithms can be used with the \fB\-v1\fR command line option,
314 including PKCS#5 v1.5 and PKCS#12. These are described in more detail
316 .Ip "\fB\s-1PBE\s0\-\s-1MD2-DES\s0 \s-1PBE\s0\-\s-1MD5-DES\s0\fR" 4
317 These algorithms were included in the original \s-1PKCS\s0#5 v1.5 specification.
318 They only offer 56 bits of protection since they both use \s-1DES\s0.
319 .Ip "\fB\s-1PBE\s0\-\s-1SHA1-RC2-64\s0 \s-1PBE\s0\-\s-1MD2-RC2-64\s0 \s-1PBE\s0\-\s-1MD5-RC2-64\s0 \s-1PBE\s0\-\s-1SHA1-DES\s0\fR" 4
320 These algorithms are not mentioned in the original \s-1PKCS\s0#5 v1.5 specification
321 but they use the same key derivation algorithm and are supported by some
322 software. They are mentioned in \s-1PKCS\s0#5 v2.0. They use either 64 bit \s-1RC2\s0 or
324 .Ip "\fB\s-1PBE\s0\-\s-1SHA1-RC4-128\s0 \s-1PBE\s0\-\s-1SHA1-RC4-40\s0 \s-1PBE\s0\-\s-1SHA1-3DES\s0 \s-1PBE\s0\-\s-1SHA1-2DES\s0 \s-1PBE\s0\-\s-1SHA1-RC2-128\s0 \s-1PBE\s0\-\s-1SHA1-RC2-40\s0\fR" 4
325 These algorithms use the \s-1PKCS\s0#12 password based encryption algorithm and
326 allow strong encryption algorithms like triple \s-1DES\s0 or 128 bit \s-1RC2\s0 to be used.
328 Convert a private from traditional to PKCS#5 v2.0 format using triple
332 \& openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
334 Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
338 \& openssl pkcs8 -in key.pem -topk8 -out enckey.pem
340 Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
344 \& openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
346 Read a DER unencrypted PKCS#8 format private key:
349 \& openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
351 Convert a private key from any PKCS#8 format to traditional format:
354 \& openssl pkcs8 -in pk8.pem -out key.pem
357 Test vectors from this PKCS#5 v2.0 implementation were posted to the
358 pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
359 counts, several people confirmed that they could decrypt the private
360 keys produced and Therefore it can be assumed that the PKCS#5 v2.0
361 implementation is reasonably accurate at least as far as these
362 algorithms are concerned.
364 The format of PKCS#8 DSA (and other) private keys is not well documented:
365 it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
366 PKCS#8 private key format complies with this standard.
368 There should be an option that prints out the encryption algorithm
369 in use and other details such as the iteration count.
371 PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
372 key format for OpenSSL: for compatibility several of the utilities use
373 the old format at present.
375 dsa(1), rsa(1), genrsa(1),
380 .IX Name "pkcs8 - PKCS#8 format private key conversion tool"
384 .IX Header "SYNOPSIS"
386 .IX Header "DESCRIPTION"
388 .IX Header "COMMAND OPTIONS"
390 .IX Item "\fB\-topk8\fR"
392 .IX Item "\fB\-inform \s-1DER\s0|\s-1PEM\s0\fR"
394 .IX Item "\fB\-outform \s-1DER\s0|\s-1PEM\s0\fR"
396 .IX Item "\fB\-in filename\fR"
398 .IX Item "\fB\-passin arg\fR"
400 .IX Item "\fB\-out filename\fR"
402 .IX Item "\fB\-passout arg\fR"
404 .IX Item "\fB\-nocrypt\fR"
406 .IX Item "\fB\-nooct\fR"
408 .IX Item "\fB\-embed\fR"
410 .IX Item "\fB\-nsdb\fR"
412 .IX Item "\fB\-v2 alg\fR"
414 .IX Item "\fB\-v1 alg\fR"
416 .IX Item "\fB\-engine id\fR"
420 .IX Header "PKCS#5 v1.5 and PKCS#12 algorithms."
422 .IX Item "\fB\s-1PBE\s0\-\s-1MD2-DES\s0 \s-1PBE\s0\-\s-1MD5-DES\s0\fR"
424 .IX Item "\fB\s-1PBE\s0\-\s-1SHA1-RC2-64\s0 \s-1PBE\s0\-\s-1MD2-RC2-64\s0 \s-1PBE\s0\-\s-1MD5-RC2-64\s0 \s-1PBE\s0\-\s-1SHA1-DES\s0\fR"
426 .IX Item "\fB\s-1PBE\s0\-\s-1SHA1-RC4-128\s0 \s-1PBE\s0\-\s-1SHA1-RC4-40\s0 \s-1PBE\s0\-\s-1SHA1-3DES\s0 \s-1PBE\s0\-\s-1SHA1-2DES\s0 \s-1PBE\s0\-\s-1SHA1-RC2-128\s0 \s-1PBE\s0\-\s-1SHA1-RC2-40\s0\fR"
428 .IX Header "EXAMPLES"
430 .IX Header "STANDARDS"
434 .IX Header "SEE ALSO"