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