Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / usr.bin / openssl / man / pkcs8.1
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
8b0cefbb 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
8b0cefbb 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
8b0cefbb
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
8b0cefbb
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
8b0cefbb
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
8b0cefbb
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
8b0cefbb
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
8b0cefbb 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
8b0cefbb
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
8b0cefbb
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
8b0cefbb 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
8b0cefbb
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
8b0cefbb
JR
124.\" ========================================================================
125.\"
126.IX Title "PKCS8 1"
e3261593 127.TH PKCS8 1 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133pkcs8 \- PKCS#8 format private key conversion tool
134.SH "SYNOPSIS"
8b0cefbb
JR
135.IX Header "SYNOPSIS"
136\&\fBopenssl\fR \fBpkcs8\fR
984263bc
MD
137[\fB\-topk8\fR]
138[\fB\-inform PEM|DER\fR]
139[\fB\-outform PEM|DER\fR]
140[\fB\-in filename\fR]
141[\fB\-passin arg\fR]
142[\fB\-out filename\fR]
143[\fB\-passout arg\fR]
144[\fB\-noiter\fR]
145[\fB\-nocrypt\fR]
146[\fB\-nooct\fR]
147[\fB\-embed\fR]
148[\fB\-nsdb\fR]
149[\fB\-v2 alg\fR]
150[\fB\-v1 alg\fR]
151[\fB\-engine id\fR]
152.SH "DESCRIPTION"
8b0cefbb 153.IX Header "DESCRIPTION"
984263bc
MD
154The \fBpkcs8\fR command processes private keys in PKCS#8 format. It can handle
155both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
156format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
157.SH "COMMAND OPTIONS"
8b0cefbb
JR
158.IX Header "COMMAND OPTIONS"
159.IP "\fB\-topk8\fR" 4
160.IX Item "-topk8"
161Normally a PKCS#8 private key is expected on input and a traditional format
984263bc 162private key will be written. With the \fB\-topk8\fR option the situation is
8b0cefbb 163reversed: it reads a traditional format private key and writes a PKCS#8
984263bc 164format key.
8b0cefbb
JR
165.IP "\fB\-inform DER|PEM\fR" 4
166.IX Item "-inform DER|PEM"
167This specifies the input format. If a PKCS#8 format key is expected on input
168then either a \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR encoded version of a PKCS#8 key will be
984263bc
MD
169expected. Otherwise the \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR format of the traditional format
170private key is used.
8b0cefbb
JR
171.IP "\fB\-outform DER|PEM\fR" 4
172.IX Item "-outform DER|PEM"
984263bc 173This specifies the output format, the options have the same meaning as the
8b0cefbb
JR
174\&\fB\-inform\fR option.
175.IP "\fB\-in filename\fR" 4
176.IX Item "-in filename"
984263bc
MD
177This specifies the input filename to read a key from or standard input if this
178option is not specified. If the key is encrypted a pass phrase will be
179prompted for.
8b0cefbb
JR
180.IP "\fB\-passin arg\fR" 4
181.IX Item "-passin arg"
984263bc 182the input file password source. For more information about the format of \fBarg\fR
8b0cefbb
JR
183see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
184.IP "\fB\-out filename\fR" 4
185.IX Item "-out filename"
984263bc
MD
186This specifies the output filename to write a key to or standard output by
187default. If any encryption options are set then a pass phrase will be
188prompted for. The output filename should \fBnot\fR be the same as the input
189filename.
8b0cefbb
JR
190.IP "\fB\-passout arg\fR" 4
191.IX Item "-passout arg"
984263bc 192the output file password source. For more information about the format of \fBarg\fR
8b0cefbb
JR
193see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
194.IP "\fB\-nocrypt\fR" 4
195.IX Item "-nocrypt"
196PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
984263bc
MD
197structures using an appropriate password based encryption algorithm. With
198this option an unencrypted PrivateKeyInfo structure is expected or output.
199This option does not encrypt private keys at all and should only be used
200when absolutely necessary. Certain software such as some versions of Java
201code signing software used unencrypted private keys.
8b0cefbb
JR
202.IP "\fB\-nooct\fR" 4
203.IX Item "-nooct"
984263bc
MD
204This option generates \s-1RSA\s0 private keys in a broken format that some software
205uses. Specifically the private key should be enclosed in a \s-1OCTET\s0 \s-1STRING\s0
206but some software just includes the structure itself without the
207surrounding \s-1OCTET\s0 \s-1STRING\s0.
8b0cefbb
JR
208.IP "\fB\-embed\fR" 4
209.IX Item "-embed"
984263bc
MD
210This option generates \s-1DSA\s0 keys in a broken format. The \s-1DSA\s0 parameters are
211embedded inside the PrivateKey structure. In this form the \s-1OCTET\s0 \s-1STRING\s0
212contains an \s-1ASN1\s0 \s-1SEQUENCE\s0 consisting of two structures: a \s-1SEQUENCE\s0 containing
213the parameters and an \s-1ASN1\s0 \s-1INTEGER\s0 containing the private key.
8b0cefbb
JR
214.IP "\fB\-nsdb\fR" 4
215.IX Item "-nsdb"
984263bc
MD
216This option generates \s-1DSA\s0 keys in a broken format compatible with Netscape
217private key databases. The PrivateKey contains a \s-1SEQUENCE\s0 consisting of
218the public and private keys respectively.
8b0cefbb
JR
219.IP "\fB\-v2 alg\fR" 4
220.IX Item "-v2 alg"
221This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
984263bc 222private keys are encrypted with the password based encryption algorithm
8b0cefbb
JR
223called \fBpbeWithMD5AndDES\-CBC\fR this uses 56 bit \s-1DES\s0 encryption but it
224was the strongest encryption algorithm supported in PKCS#5 v1.5. Using
225the \fB\-v2\fR option PKCS#5 v2.0 algorithms are used which can use any
984263bc 226encryption algorithm such as 168 bit triple \s-1DES\s0 or 128 bit \s-1RC2\s0 however
8b0cefbb 227not many implementations support PKCS#5 v2.0 yet. If you are just using
984263bc
MD
228private keys with OpenSSL then this doesn't matter.
229.Sp
230The \fBalg\fR argument is the encryption algorithm to use, valid values include
8b0cefbb
JR
231\&\fBdes\fR, \fBdes3\fR and \fBrc2\fR. It is recommended that \fBdes3\fR is used.
232.IP "\fB\-v1 alg\fR" 4
233.IX Item "-v1 alg"
234This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
984263bc 235list of possible algorithms is included below.
8b0cefbb
JR
236.IP "\fB\-engine id\fR" 4
237.IX Item "-engine id"
01185282 238specifying an engine (by its unique \fBid\fR string) will cause \fBpkcs8\fR
984263bc
MD
239to attempt to obtain a functional reference to the specified engine,
240thus initialising it if needed. The engine will then be set as the default
241for all available algorithms.
242.SH "NOTES"
8b0cefbb
JR
243.IX Header "NOTES"
244The encrypted form of a \s-1PEM\s0 encode PKCS#8 files uses the following
984263bc
MD
245headers and footers:
246.PP
247.Vb 2
e257b235
PA
248\& \-\-\-\-\-BEGIN ENCRYPTED PRIVATE KEY\-\-\-\-\-
249\& \-\-\-\-\-END ENCRYPTED PRIVATE KEY\-\-\-\-\-
984263bc 250.Ve
8b0cefbb 251.PP
984263bc
MD
252The unencrypted form uses:
253.PP
254.Vb 2
e257b235
PA
255\& \-\-\-\-\-BEGIN PRIVATE KEY\-\-\-\-\-
256\& \-\-\-\-\-END PRIVATE KEY\-\-\-\-\-
984263bc 257.Ve
8b0cefbb 258.PP
984263bc
MD
259Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
260counts are more secure that those encrypted using the traditional
261SSLeay compatible formats. So if additional security is considered
262important the keys should be converted.
263.PP
264The default encryption is only 56 bits because this is the encryption
265that most current implementations of PKCS#8 will support.
266.PP
267Some software may use PKCS#12 password based encryption algorithms
268with PKCS#8 format private keys: these are handled automatically
269but there is no option to produce them.
270.PP
8b0cefbb
JR
271It is possible to write out \s-1DER\s0 encoded encrypted private keys in
272PKCS#8 format because the encryption details are included at an \s-1ASN1\s0
273level whereas the traditional format includes them at a \s-1PEM\s0 level.
984263bc 274.SH "PKCS#5 v1.5 and PKCS#12 algorithms."
8b0cefbb 275.IX Header "PKCS#5 v1.5 and PKCS#12 algorithms."
984263bc
MD
276Various algorithms can be used with the \fB\-v1\fR command line option,
277including PKCS#5 v1.5 and PKCS#12. These are described in more detail
278below.
8b0cefbb
JR
279.IP "\fB\s-1PBE\-MD2\-DES\s0 \s-1PBE\-MD5\-DES\s0\fR" 4
280.IX Item "PBE-MD2-DES PBE-MD5-DES"
281These algorithms were included in the original PKCS#5 v1.5 specification.
984263bc 282They only offer 56 bits of protection since they both use \s-1DES\s0.
8b0cefbb
JR
283.IP "\fB\s-1PBE\-SHA1\-RC2\-64\s0 \s-1PBE\-MD2\-RC2\-64\s0 \s-1PBE\-MD5\-RC2\-64\s0 \s-1PBE\-SHA1\-DES\s0\fR" 4
284.IX Item "PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES"
285These algorithms are not mentioned in the original PKCS#5 v1.5 specification
984263bc 286but they use the same key derivation algorithm and are supported by some
8b0cefbb 287software. They are mentioned in PKCS#5 v2.0. They use either 64 bit \s-1RC2\s0 or
984263bc 28856 bit \s-1DES\s0.
8b0cefbb
JR
289.IP "\fB\s-1PBE\-SHA1\-RC4\-128\s0 \s-1PBE\-SHA1\-RC4\-40\s0 \s-1PBE\-SHA1\-3DES\s0 \s-1PBE\-SHA1\-2DES\s0 \s-1PBE\-SHA1\-RC2\-128\s0 \s-1PBE\-SHA1\-RC2\-40\s0\fR" 4
290.IX Item "PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40"
291These algorithms use the PKCS#12 password based encryption algorithm and
984263bc
MD
292allow strong encryption algorithms like triple \s-1DES\s0 or 128 bit \s-1RC2\s0 to be used.
293.SH "EXAMPLES"
8b0cefbb 294.IX Header "EXAMPLES"
984263bc 295Convert a private from traditional to PKCS#5 v2.0 format using triple
8b0cefbb 296\&\s-1DES:\s0
984263bc
MD
297.PP
298.Vb 1
e257b235 299\& openssl pkcs8 \-in key.pem \-topk8 \-v2 des3 \-out enckey.pem
984263bc 300.Ve
8b0cefbb 301.PP
984263bc 302Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
8b0cefbb 303(\s-1DES\s0):
984263bc
MD
304.PP
305.Vb 1
e257b235 306\& openssl pkcs8 \-in key.pem \-topk8 \-out enckey.pem
984263bc 307.Ve
8b0cefbb 308.PP
984263bc
MD
309Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
310(3DES):
311.PP
312.Vb 1
e257b235 313\& openssl pkcs8 \-in key.pem \-topk8 \-out enckey.pem \-v1 PBE\-SHA1\-3DES
984263bc 314.Ve
8b0cefbb
JR
315.PP
316Read a \s-1DER\s0 unencrypted PKCS#8 format private key:
984263bc
MD
317.PP
318.Vb 1
e257b235 319\& openssl pkcs8 \-inform DER \-nocrypt \-in key.der \-out key.pem
984263bc 320.Ve
8b0cefbb 321.PP
984263bc
MD
322Convert a private key from any PKCS#8 format to traditional format:
323.PP
324.Vb 1
e257b235 325\& openssl pkcs8 \-in pk8.pem \-out key.pem
984263bc
MD
326.Ve
327.SH "STANDARDS"
8b0cefbb 328.IX Header "STANDARDS"
984263bc 329Test vectors from this PKCS#5 v2.0 implementation were posted to the
8b0cefbb 330pkcs-tng mailing list using triple \s-1DES\s0, \s-1DES\s0 and \s-1RC2\s0 with high iteration
984263bc
MD
331counts, several people confirmed that they could decrypt the private
332keys produced and Therefore it can be assumed that the PKCS#5 v2.0
333implementation is reasonably accurate at least as far as these
334algorithms are concerned.
335.PP
8b0cefbb
JR
336The format of PKCS#8 \s-1DSA\s0 (and other) private keys is not well documented:
337it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default \s-1DSA\s0
984263bc
MD
338PKCS#8 private key format complies with this standard.
339.SH "BUGS"
8b0cefbb 340.IX Header "BUGS"
984263bc
MD
341There should be an option that prints out the encryption algorithm
342in use and other details such as the iteration count.
343.PP
8b0cefbb 344PKCS#8 using triple \s-1DES\s0 and PKCS#5 v2.0 should be the default private
984263bc
MD
345key format for OpenSSL: for compatibility several of the utilities use
346the old format at present.
347.SH "SEE ALSO"
e3cdf75b 348.IX Header "SEE ALSO"
8b0cefbb 349\&\fIdsa\fR\|(1), \fIrsa\fR\|(1), \fIgenrsa\fR\|(1),
e257b235 350\&\fIgendsa\fR\|(1)