Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / usr.bin / openssl / man / pkcs8.1
CommitLineData
e3cdf75b
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
e3cdf75b 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
e3cdf75b 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
e3cdf75b 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
e3cdf75b 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
e3cdf75b
JR
34'''
35'''
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.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
e3cdf75b
JR
42.ds -- \(*W-
43.ds PI pi
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
46.ds L" ""
47.ds R" ""
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
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
e3cdf75b
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
e3cdf75b
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
e3cdf75b
JR
93.nr % 0
94.rr F
984263bc 95.\}
e3cdf75b
JR
96.TH PKCS8 1 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
e3cdf75b
JR
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
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
e3cdf75b 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
e3cdf75b
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
e3cdf75b
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
e3cdf75b 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
e3cdf75b
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
e3cdf75b
JR
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'
984263bc 150.\}
e3cdf75b 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
e3cdf75b
JR
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'\*(#]
984263bc
MD
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
e3cdf75b
JR
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
984263bc
MD
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'
e3cdf75b 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
e3cdf75b
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191pkcs8 \- PKCS#8 format private key conversion tool
192.SH "SYNOPSIS"
e3cdf75b 193\fBopenssl\fR \fBpkcs8\fR
984263bc
MD
194[\fB\-topk8\fR]
195[\fB\-inform PEM|DER\fR]
196[\fB\-outform PEM|DER\fR]
197[\fB\-in filename\fR]
198[\fB\-passin arg\fR]
199[\fB\-out filename\fR]
200[\fB\-passout arg\fR]
201[\fB\-noiter\fR]
202[\fB\-nocrypt\fR]
203[\fB\-nooct\fR]
204[\fB\-embed\fR]
205[\fB\-nsdb\fR]
206[\fB\-v2 alg\fR]
207[\fB\-v1 alg\fR]
208[\fB\-engine id\fR]
209.SH "DESCRIPTION"
984263bc
MD
210The \fBpkcs8\fR command processes private keys in PKCS#8 format. It can handle
211both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
212format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
213.SH "COMMAND OPTIONS"
984263bc 214.Ip "\fB\-topk8\fR" 4
e3cdf75b 215Normally a \s-1PKCS\s0#8 private key is expected on input and a traditional format
984263bc 216private key will be written. With the \fB\-topk8\fR option the situation is
e3cdf75b 217reversed: it reads a traditional format private key and writes a \s-1PKCS\s0#8
984263bc 218format key.
e3cdf75b
JR
219.Ip "\fB\-inform \s-1DER\s0|\s-1PEM\s0\fR" 4
220This specifies the input format. If a \s-1PKCS\s0#8 format key is expected on input
221then either a \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR encoded version of a \s-1PKCS\s0#8 key will be
984263bc
MD
222expected. Otherwise the \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR format of the traditional format
223private key is used.
e3cdf75b 224.Ip "\fB\-outform \s-1DER\s0|\s-1PEM\s0\fR" 4
984263bc 225This specifies the output format, the options have the same meaning as the
e3cdf75b 226\fB\-inform\fR option.
984263bc 227.Ip "\fB\-in filename\fR" 4
984263bc
MD
228This specifies the input filename to read a key from or standard input if this
229option is not specified. If the key is encrypted a pass phrase will be
230prompted for.
231.Ip "\fB\-passin arg\fR" 4
984263bc
MD
232the input file password source. For more information about the format of \fBarg\fR
233see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
234.Ip "\fB\-out filename\fR" 4
984263bc
MD
235This specifies the output filename to write a key to or standard output by
236default. If any encryption options are set then a pass phrase will be
237prompted for. The output filename should \fBnot\fR be the same as the input
238filename.
239.Ip "\fB\-passout arg\fR" 4
984263bc
MD
240the output file password source. For more information about the format of \fBarg\fR
241see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
242.Ip "\fB\-nocrypt\fR" 4
e3cdf75b 243\s-1PKCS\s0#8 keys generated or input are normally \s-1PKCS\s0#8 EncryptedPrivateKeyInfo
984263bc
MD
244structures using an appropriate password based encryption algorithm. With
245this option an unencrypted PrivateKeyInfo structure is expected or output.
246This option does not encrypt private keys at all and should only be used
247when absolutely necessary. Certain software such as some versions of Java
248code signing software used unencrypted private keys.
249.Ip "\fB\-nooct\fR" 4
984263bc
MD
250This option generates \s-1RSA\s0 private keys in a broken format that some software
251uses. Specifically the private key should be enclosed in a \s-1OCTET\s0 \s-1STRING\s0
252but some software just includes the structure itself without the
253surrounding \s-1OCTET\s0 \s-1STRING\s0.
254.Ip "\fB\-embed\fR" 4
984263bc
MD
255This option generates \s-1DSA\s0 keys in a broken format. The \s-1DSA\s0 parameters are
256embedded inside the PrivateKey structure. In this form the \s-1OCTET\s0 \s-1STRING\s0
257contains an \s-1ASN1\s0 \s-1SEQUENCE\s0 consisting of two structures: a \s-1SEQUENCE\s0 containing
258the parameters and an \s-1ASN1\s0 \s-1INTEGER\s0 containing the private key.
259.Ip "\fB\-nsdb\fR" 4
984263bc
MD
260This option generates \s-1DSA\s0 keys in a broken format compatible with Netscape
261private key databases. The PrivateKey contains a \s-1SEQUENCE\s0 consisting of
262the public and private keys respectively.
263.Ip "\fB\-v2 alg\fR" 4
e3cdf75b 264This option enables the use of \s-1PKCS\s0#5 v2.0 algorithms. Normally \s-1PKCS\s0#8
984263bc 265private keys are encrypted with the password based encryption algorithm
e3cdf75b
JR
266called \fBpbeWithMD5AndDES\-\s-1CBC\s0\fR this uses 56 bit \s-1DES\s0 encryption but it
267was the strongest encryption algorithm supported in \s-1PKCS\s0#5 v1.5. Using
268the \fB\-v2\fR option \s-1PKCS\s0#5 v2.0 algorithms are used which can use any
984263bc 269encryption algorithm such as 168 bit triple \s-1DES\s0 or 128 bit \s-1RC2\s0 however
e3cdf75b 270not many implementations support \s-1PKCS\s0#5 v2.0 yet. If you are just using
984263bc
MD
271private keys with OpenSSL then this doesn't matter.
272.Sp
273The \fBalg\fR argument is the encryption algorithm to use, valid values include
e3cdf75b 274\fBdes\fR, \fBdes3\fR and \fBrc2\fR. It is recommended that \fBdes3\fR is used.
984263bc 275.Ip "\fB\-v1 alg\fR" 4
e3cdf75b 276This option specifies a \s-1PKCS\s0#5 v1.5 or \s-1PKCS\s0#12 algorithm to use. A complete
984263bc
MD
277list of possible algorithms is included below.
278.Ip "\fB\-engine id\fR" 4
984263bc
MD
279specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
280to attempt to obtain a functional reference to the specified engine,
281thus initialising it if needed. The engine will then be set as the default
282for all available algorithms.
283.SH "NOTES"
e3cdf75b 284The encrypted form of a PEM encode PKCS#8 files uses the following
984263bc
MD
285headers and footers:
286.PP
287.Vb 2
288\& -----BEGIN ENCRYPTED PRIVATE KEY-----
289\& -----END ENCRYPTED PRIVATE KEY-----
290.Ve
291The unencrypted form uses:
292.PP
293.Vb 2
294\& -----BEGIN PRIVATE KEY-----
295\& -----END PRIVATE KEY-----
296.Ve
297Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
298counts are more secure that those encrypted using the traditional
299SSLeay compatible formats. So if additional security is considered
300important the keys should be converted.
301.PP
302The default encryption is only 56 bits because this is the encryption
303that most current implementations of PKCS#8 will support.
304.PP
305Some software may use PKCS#12 password based encryption algorithms
306with PKCS#8 format private keys: these are handled automatically
307but there is no option to produce them.
308.PP
e3cdf75b
JR
309It is possible to write out DER encoded encrypted private keys in
310PKCS#8 format because the encryption details are included at an ASN1
311level whereas the traditional format includes them at a PEM level.
984263bc 312.SH "PKCS#5 v1.5 and PKCS#12 algorithms."
984263bc
MD
313Various algorithms can be used with the \fB\-v1\fR command line option,
314including PKCS#5 v1.5 and PKCS#12. These are described in more detail
315below.
e3cdf75b
JR
316.Ip "\fB\s-1PBE\s0\-\s-1MD2-DES\s0 \s-1PBE\s0\-\s-1MD5-DES\s0\fR" 4
317These algorithms were included in the original \s-1PKCS\s0#5 v1.5 specification.
984263bc 318They only offer 56 bits of protection since they both use \s-1DES\s0.
e3cdf75b
JR
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
320These algorithms are not mentioned in the original \s-1PKCS\s0#5 v1.5 specification
984263bc 321but they use the same key derivation algorithm and are supported by some
e3cdf75b 322software. They are mentioned in \s-1PKCS\s0#5 v2.0. They use either 64 bit \s-1RC2\s0 or
984263bc 32356 bit \s-1DES\s0.
e3cdf75b
JR
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
325These algorithms use the \s-1PKCS\s0#12 password based encryption algorithm and
984263bc
MD
326allow strong encryption algorithms like triple \s-1DES\s0 or 128 bit \s-1RC2\s0 to be used.
327.SH "EXAMPLES"
984263bc 328Convert a private from traditional to PKCS#5 v2.0 format using triple
e3cdf75b 329DES:
984263bc
MD
330.PP
331.Vb 1
332\& openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
333.Ve
334Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
e3cdf75b 335(DES):
984263bc
MD
336.PP
337.Vb 1
338\& openssl pkcs8 -in key.pem -topk8 -out enckey.pem
339.Ve
340Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
341(3DES):
342.PP
343.Vb 1
344\& openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
345.Ve
e3cdf75b 346Read a DER unencrypted PKCS#8 format private key:
984263bc
MD
347.PP
348.Vb 1
349\& openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
350.Ve
351Convert a private key from any PKCS#8 format to traditional format:
352.PP
353.Vb 1
354\& openssl pkcs8 -in pk8.pem -out key.pem
355.Ve
356.SH "STANDARDS"
984263bc 357Test vectors from this PKCS#5 v2.0 implementation were posted to the
e3cdf75b 358pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
984263bc
MD
359counts, several people confirmed that they could decrypt the private
360keys produced and Therefore it can be assumed that the PKCS#5 v2.0
361implementation is reasonably accurate at least as far as these
362algorithms are concerned.
363.PP
e3cdf75b
JR
364The format of PKCS#8 DSA (and other) private keys is not well documented:
365it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
984263bc
MD
366PKCS#8 private key format complies with this standard.
367.SH "BUGS"
984263bc
MD
368There should be an option that prints out the encryption algorithm
369in use and other details such as the iteration count.
370.PP
e3cdf75b 371PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
984263bc
MD
372key format for OpenSSL: for compatibility several of the utilities use
373the old format at present.
374.SH "SEE ALSO"
984263bc
MD
375dsa(1), rsa(1), genrsa(1),
376gendsa(1)
e3cdf75b
JR
377
378.rn }` ''
379.IX Title "PKCS8 1"
380.IX Name "pkcs8 - PKCS#8 format private key conversion tool"
381
382.IX Header "NAME"
383
384.IX Header "SYNOPSIS"
385
386.IX Header "DESCRIPTION"
387
388.IX Header "COMMAND OPTIONS"
389
390.IX Item "\fB\-topk8\fR"
391
392.IX Item "\fB\-inform \s-1DER\s0|\s-1PEM\s0\fR"
393
394.IX Item "\fB\-outform \s-1DER\s0|\s-1PEM\s0\fR"
395
396.IX Item "\fB\-in filename\fR"
397
398.IX Item "\fB\-passin arg\fR"
399
400.IX Item "\fB\-out filename\fR"
401
402.IX Item "\fB\-passout arg\fR"
403
404.IX Item "\fB\-nocrypt\fR"
405
406.IX Item "\fB\-nooct\fR"
407
408.IX Item "\fB\-embed\fR"
409
410.IX Item "\fB\-nsdb\fR"
411
412.IX Item "\fB\-v2 alg\fR"
413
414.IX Item "\fB\-v1 alg\fR"
415
416.IX Item "\fB\-engine id\fR"
417
418.IX Header "NOTES"
419
420.IX Header "PKCS#5 v1.5 and PKCS#12 algorithms."
421
422.IX Item "\fB\s-1PBE\s0\-\s-1MD2-DES\s0 \s-1PBE\s0\-\s-1MD5-DES\s0\fR"
423
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"
425
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"
427
428.IX Header "EXAMPLES"
429
430.IX Header "STANDARDS"
431
432.IX Header "BUGS"
433
434.IX Header "SEE ALSO"
435