Debian Codegraph @

upstream/debian-unstable/man1/openssl-pkcs8.1ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL-PKCS8 1SSL"
58 .TH OPENSSL-PKCS8 1SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 openssl\-pkcs8 \- PKCS#8 format private key conversion command
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 \&\fBopenssl\fR \fBpkcs8\fR
68 [\fB\-help\fR]
69 [\fB\-topk8\fR]
70 [\fB\-inform\fR \fBDER\fR|\fBPEM\fR]
71 [\fB\-outform\fR \fBDER\fR|\fBPEM\fR]
72 [\fB\-in\fR \fIfilename\fR]
73 [\fB\-passin\fR \fIarg\fR]
74 [\fB\-out\fR \fIfilename\fR]
75 [\fB\-passout\fR \fIarg\fR]
76 [\fB\-iter\fR \fIcount\fR]
77 [\fB\-noiter\fR]
78 [\fB\-nocrypt\fR]
79 [\fB\-traditional\fR]
80 [\fB\-v2\fR \fIalg\fR]
81 [\fB\-v2prf\fR \fIalg\fR]
82 [\fB\-v1\fR \fIalg\fR]
83 [\fB\-scrypt\fR]
84 [\fB\-scrypt_N\fR \fIN\fR]
85 [\fB\-scrypt_r\fR \fIr\fR]
86 [\fB\-scrypt_p\fR \fIp\fR]
87 [\fB\-saltlen\fR \fIsize\fR]
88 [\fB\-rand\fR \fIfiles\fR]
89 [\fB\-writerand\fR \fIfile\fR]
90 [\fB\-engine\fR \fIid\fR]
91 [\fB\-provider\fR \fIname\fR]
92 [\fB\-provider\-path\fR \fIpath\fR]
93 [\fB\-provparam\fR \fI[name:]key=value\fR]
94 [\fB\-propquery\fR \fIpropq\fR]
95 .SH DESCRIPTION
96 .IX Header "DESCRIPTION"
97 This command processes private keys in PKCS#8 format. It can handle
98 both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
99 format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
100 .SH OPTIONS
101 .IX Header "OPTIONS"
102 .IP \fB\-help\fR 4
103 .IX Item "-help"
104 Print out a usage message.
105 .IP \fB\-topk8\fR 4
106 .IX Item "-topk8"
107 Normally a PKCS#8 private key is expected on input and a private key will be
108 written to the output file. With the \fB\-topk8\fR option the situation is
109 reversed: it reads a private key and writes a PKCS#8 format key.
110 .IP "\fB\-inform\fR \fBDER\fR|\fBPEM\fR, \fB\-outform\fR \fBDER\fR|\fBPEM\fR" 4
111 .IX Item "-inform DER|PEM, -outform DER|PEM"
112 The input and formats; the default is \fBPEM\fR.
113 See \fBopenssl\-format\-options\fR\|(1) for details.
114 .Sp
115 If a key is being converted from PKCS#8 form (i.e. the \fB\-topk8\fR option is
116 not used) then the input file must be in PKCS#8 format. An encrypted
117 key is expected unless \fB\-nocrypt\fR is included.
118 .Sp
119 If \fB\-topk8\fR is not used and \fBPEM\fR mode is set the output file will be an
120 unencrypted private key in PKCS#8 format. If the \fB\-traditional\fR option is
121 used then a traditional format private key is written instead.
122 .Sp
123 If \fB\-topk8\fR is not used and \fBDER\fR mode is set the output file will be an
124 unencrypted private key in traditional DER format.
125 .Sp
126 If \fB\-topk8\fR is used then any supported private key can be used for the input
127 file in a format specified by \fB\-inform\fR. The output file will be encrypted
128 PKCS#8 format using the specified encryption parameters unless \fB\-nocrypt\fR
129 is included.
130 .IP \fB\-traditional\fR 4
131 .IX Item "-traditional"
132 When this option is present and \fB\-topk8\fR is not a traditional format private
133 key is written.
134 .IP "\fB\-in\fR \fIfilename\fR" 4
135 .IX Item "-in filename"
136 This specifies the input file to read a key from or standard input if this
137 option is not specified. If the key is encrypted a pass phrase will be
138 prompted for unless \fB\-passin\fR is given.
139 .IP "\fB\-passin\fR \fIarg\fR, \fB\-passout\fR \fIarg\fR" 4
140 .IX Item "-passin arg, -passout arg"
141 The password source for the input and output file.
142 For more information about the format of \fBarg\fR
143 see \fBopenssl\-passphrase\-options\fR\|(1).
144 .IP "\fB\-out\fR \fIfilename\fR" 4
145 .IX Item "-out filename"
146 This specifies the output file to write a key to or standard output by default.
147 The output filename can be the same as the input filename,
148 which leads to replacing the file contents.
149 Note that file I/O is not atomic. The output file is truncated and then written.
150 .Sp
151 If any encryption options are set and \fB\-passout\fR is not given
152 then a pass phrase will be prompted for.
153 When password input is interrupted, the output file is not touched.
154 .IP "\fB\-iter\fR \fIcount\fR" 4
155 .IX Item "-iter count"
156 When creating new PKCS#8 containers, use a given number of iterations on
157 the password in deriving the encryption key for the PKCS#8 output.
158 High values increase the time required to brute-force a PKCS#8 container.
159 .IP \fB\-noiter\fR 4
160 .IX Item "-noiter"
161 When creating new PKCS#8 containers, use 1 as iteration count.
162 .IP \fB\-nocrypt\fR 4
163 .IX Item "-nocrypt"
164 PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
165 structures using an appropriate password based encryption algorithm. With
166 this option an unencrypted PrivateKeyInfo structure is expected or output.
167 This option does not encrypt private keys at all and should only be used
168 when absolutely necessary. Certain software such as some versions of Java
169 code signing software used unencrypted private keys.
170 .IP "\fB\-v2\fR \fIalg\fR" 4
171 .IX Item "-v2 alg"
172 This option sets the PKCS#5 v2.0 algorithm.
173 .Sp
174 The \fIalg\fR argument is the encryption algorithm to use, valid values include
175 \&\fBaes128\fR, \fBaes256\fR and \fBdes3\fR. If this option isn't specified then \fBaes256\fR
176 is used.
177 .IP "\fB\-v2prf\fR \fIalg\fR" 4
178 .IX Item "-v2prf alg"
179 This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical valid
180 value would be \fBhmacWithSHA256\fR. If this option isn't set then the default
181 for the cipher is used or \fBhmacWithSHA256\fR if there is no default.
182 .Sp
183 Some implementations may not support custom PRF algorithms and may require
184 the \fBhmacWithSHA1\fR option to work.
185 .IP "\fB\-v1\fR \fIalg\fR" 4
186 .IX Item "-v1 alg"
187 This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some
188 older implementations may not support PKCS#5 v2.0 and may require this option.
189 If not specified PKCS#5 v2.0 form is used.
190 .IP \fB\-scrypt\fR 4
191 .IX Item "-scrypt"
192 Uses the \fBscrypt\fR algorithm for private key encryption using default
193 parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
194 key. These parameters can be modified using the \fB\-scrypt_N\fR, \fB\-scrypt_r\fR,
195 \&\fB\-scrypt_p\fR and \fB\-v2\fR options.
196 .IP "\fB\-scrypt_N\fR \fIN\fR, \fB\-scrypt_r\fR \fIr\fR, \fB\-scrypt_p\fR \fIp\fR" 4
197 .IX Item "-scrypt_N N, -scrypt_r r, -scrypt_p p"
198 Sets the scrypt \fIN\fR, \fIr\fR or \fIp\fR parameters.
199 .IP \fB\-saltlen\fR 4
200 .IX Item "-saltlen"
201 Sets the length (in bytes) of the salt to use for the PBE algorithm.
202 If this value is not specified, the default for PBES2 is 16 (128 bits)
203 and 8 (64 bits) for PBES1.
204 .IP "\fB\-rand\fR \fIfiles\fR, \fB\-writerand\fR \fIfile\fR" 4
205 .IX Item "-rand files, -writerand file"
206 See "Random State Options" in \fBopenssl\fR\|(1) for details.
207 .IP "\fB\-engine\fR \fIid\fR" 4
208 .IX Item "-engine id"
209 See "Engine Options" in \fBopenssl\fR\|(1).
210 This option is deprecated.
211 .IP "\fB\-provider\fR \fIname\fR" 4
212 .IX Item "-provider name"
213 .PD 0
214 .IP "\fB\-provider\-path\fR \fIpath\fR" 4
215 .IX Item "-provider-path path"
216 .IP "\fB\-provparam\fR \fI[name:]key=value\fR" 4
217 .IX Item "-provparam [name:]key=value"
218 .IP "\fB\-propquery\fR \fIpropq\fR" 4
219 .IX Item "-propquery propq"
220 .PD
221 See "Provider Options" in \fBopenssl\fR\|(1), \fBprovider\fR\|(7), and \fBproperty\fR\|(7).
222 .SH NOTES
223 .IX Header "NOTES"
224 By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
225 AES with HMAC and SHA256 is used.
226 .PP
227 Some older implementations do not support PKCS#5 v2.0 format and require
228 the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
229 encryption algorithms such as 56 bit DES.
230 .PP
231 Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
232 counts are more secure that those encrypted using the traditional
233 SSLeay compatible formats. So if additional security is considered
234 important the keys should be converted.
235 .PP
236 It is possible to write out DER encoded encrypted private keys in
237 PKCS#8 format because the encryption details are included at an ASN1
238 level whereas the traditional format includes them at a PEM level.
239 .SH "PKCS#5 V1.5 AND PKCS#12 ALGORITHMS"
240 .IX Header "PKCS#5 V1.5 AND PKCS#12 ALGORITHMS"
241 Various algorithms can be used with the \fB\-v1\fR command line option,
242 including PKCS#5 v1.5 and PKCS#12. These are described in more detail
243 below.
244 .IP "\fBPBE\-MD2\-DES PBE\-MD5\-DES\fR" 4
245 .IX Item "PBE-MD2-DES PBE-MD5-DES"
246 These algorithms were included in the original PKCS#5 v1.5 specification.
247 They only offer 56 bits of protection since they both use DES.
248 .IP "\fBPBE\-SHA1\-RC2\-64\fR, \fBPBE\-MD2\-RC2\-64\fR, \fBPBE\-MD5\-RC2\-64\fR, \fBPBE\-SHA1\-DES\fR" 4
249 .IX Item "PBE-SHA1-RC2-64, PBE-MD2-RC2-64, PBE-MD5-RC2-64, PBE-SHA1-DES"
250 These algorithms are not mentioned in the original PKCS#5 v1.5 specification
251 but they use the same key derivation algorithm and are supported by some
252 software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
253 56 bit DES.
254 .IP "\fBPBE\-SHA1\-RC4\-128\fR, \fBPBE\-SHA1\-RC4\-40\fR, \fBPBE\-SHA1\-3DES\fR, \fBPBE\-SHA1\-2DES\fR, \fBPBE\-SHA1\-RC2\-128\fR, \fBPBE\-SHA1\-RC2\-40\fR" 4
255 .IX Item "PBE-SHA1-RC4-128, PBE-SHA1-RC4-40, PBE-SHA1-3DES, PBE-SHA1-2DES, PBE-SHA1-RC2-128, PBE-SHA1-RC2-40"
256 These algorithms use the PKCS#12 password based encryption algorithm and
257 allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
258 .SH EXAMPLES
259 .IX Header "EXAMPLES"
260 Convert a private key to PKCS#8 format using default parameters (AES with
261 256 bit key and \fBhmacWithSHA256\fR):
262 .PP
263 .Vb 1
264 \& openssl pkcs8 \-in key.pem \-topk8 \-out enckey.pem
265 .Ve
266 .PP
267 Convert a private key to PKCS#8 unencrypted format:
268 .PP
269 .Vb 1
270 \& openssl pkcs8 \-in key.pem \-topk8 \-nocrypt \-out enckey.pem
271 .Ve
272 .PP
273 Convert a private key to PKCS#5 v2.0 format using triple DES:
274 .PP
275 .Vb 1
276 \& openssl pkcs8 \-in key.pem \-topk8 \-v2 des3 \-out enckey.pem
277 .Ve
278 .PP
279 Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
280 mode and \fBhmacWithSHA512\fR PRF:
281 .PP
282 .Vb 1
283 \& openssl pkcs8 \-in key.pem \-topk8 \-v2 aes\-256\-cbc \-v2prf hmacWithSHA512 \-out enckey.pem
284 .Ve
285 .PP
286 Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
287 (DES):
288 .PP
289 .Vb 1
290 \& openssl pkcs8 \-in key.pem \-topk8 \-v1 PBE\-MD5\-DES \-out enckey.pem
291 .Ve
292 .PP
293 Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
294 (3DES):
295 .PP
296 .Vb 1
297 \& openssl pkcs8 \-in key.pem \-topk8 \-out enckey.pem \-v1 PBE\-SHA1\-3DES
298 .Ve
299 .PP
300 Read a DER unencrypted PKCS#8 format private key:
301 .PP
302 .Vb 1
303 \& openssl pkcs8 \-inform DER \-nocrypt \-in key.der \-out key.pem
304 .Ve
305 .PP
306 Convert a private key from any PKCS#8 encrypted format to traditional format:
307 .PP
308 .Vb 1
309 \& openssl pkcs8 \-in pk8.pem \-traditional \-out key.pem
310 .Ve
311 .PP
312 Convert a private key to PKCS#8 format, encrypting with AES\-256 and with
313 one million iterations of the password:
314 .PP
315 .Vb 1
316 \& openssl pkcs8 \-in key.pem \-topk8 \-v2 aes\-256\-cbc \-iter 1000000 \-out pk8.pem
317 .Ve
318 .SH STANDARDS
319 .IX Header "STANDARDS"
320 Test vectors from this PKCS#5 v2.0 implementation were posted to the
321 pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
322 counts, several people confirmed that they could decrypt the private
323 keys produced and therefore, it can be assumed that the PKCS#5 v2.0
324 implementation is reasonably accurate at least as far as these
325 algorithms are concerned.
326 .PP
327 The format of PKCS#8 DSA (and other) private keys is not well documented:
328 it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
329 PKCS#8 private key format complies with this standard.
330 .SH BUGS
331 .IX Header "BUGS"
332 There should be an option that prints out the encryption algorithm
333 in use and other details such as the iteration count.
334 .SH "SEE ALSO"
335 .IX Header "SEE ALSO"
336 \&\fBopenssl\fR\|(1),
337 \&\fBopenssl\-dsa\fR\|(1),
338 \&\fBopenssl\-rsa\fR\|(1),
339 \&\fBopenssl\-genrsa\fR\|(1),
340 \&\fBopenssl\-gendsa\fR\|(1)
341 .SH HISTORY
342 .IX Header "HISTORY"
343 The \fB\-iter\fR option was added in OpenSSL 1.1.0.
344 .PP
345 The \fB\-engine\fR option was deprecated in OpenSSL 3.0.
346 .SH COPYRIGHT
347 .IX Header "COPYRIGHT"
348 Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved.
349 .PP
350 Licensed under the Apache License 2.0 (the "License"). You may not use
351 this file except in compliance with the License. You can obtain a copy
352 in the file LICENSE in the source distribution or at
353 <https://www.openssl.org/source/license.html>.