1OPENSSL-PKCS8(1ossl) OpenSSL OPENSSL-PKCS8(1ossl)
2
6 openssl-pkcs8 - PKCS#8 format private key conversion command
7
9 openssl pkcs8 [-help] [-topk8] [-inform DER|PEM] [-outform DER|PEM]
10 [-in filename] [-passin arg] [-out filename] [-passout arg] [-iter
11 count] [-noiter] [-nocrypt] [-traditional] [-v2 alg] [-v2prf alg] [-v1
12 alg] [-scrypt] [-scrypt_N N] [-scrypt_r r] [-scrypt_p p] [-rand files]
13 [-writerand file] [-engine id] [-provider name] [-provider-path path]
14 [-propquery propq]
15
17 This command processes private keys in PKCS#8 format. It can handle
18 both unencrypted PKCS#8 PrivateKeyInfo format and
19 EncryptedPrivateKeyInfo format with a variety of PKCS#5 (v1.5 and v2.0)
20 and PKCS#12 algorithms.
21
23 -help
24 Print out a usage message.
25 -topk8
27 Normally a PKCS#8 private key is expected on input and a private
28 key will be written to the output file. With the -topk8 option the
29 situation is reversed: it reads a private key and writes a PKCS#8
30 format key.
31 -inform DER|PEM, -outform DER|PEM
33 The input and formats; the default is PEM. See
34 openssl-format-options(1) for details.
35 If a key is being converted from PKCS#8 form (i.e. the -topk8
37 option is not used) then the input file must be in PKCS#8 format.
38 An encrypted key is expected unless -nocrypt is included.
39 If -topk8 is not used and PEM mode is set the output file will be
41 an unencrypted private key in PKCS#8 format. If the -traditional
42 option is used then a traditional format private key is written
43 instead.
44 If -topk8 is not used and DER mode is set the output file will be
46 an unencrypted private key in traditional DER format.
47 If -topk8 is used then any supported private key can be used for
49 the input file in a format specified by -inform. The output file
50 will be encrypted PKCS#8 format using the specified encryption
51 parameters unless -nocrypt is included.
52 -traditional
54 When this option is present and -topk8 is not a traditional format
55 private key is written.
56 -in filename
58 This specifies the input filename to read a key from or standard
59 input if this option is not specified. If the key is encrypted a
60 pass phrase will be prompted for.
61 -passin arg, -passout arg
63 The password source for the input and output file. For more
64 information about the format of arg see
65 openssl-passphrase-options(1).
66 -out filename
68 This specifies the output filename to write a key to or standard
69 output by default. If any encryption options are set then a pass
70 phrase will be prompted for. The output filename should not be the
71 same as the input filename.
72 -iter count
74 When creating new PKCS#8 containers, use a given number of
75 iterations on the password in deriving the encryption key for the
76 PKCS#8 output. High values increase the time required to brute-
77 force a PKCS#8 container.
78 -noiter
80 When creating new PKCS#8 containers, use 1 as iteration count.
81 -nocrypt
83 PKCS#8 keys generated or input are normally PKCS#8
84 EncryptedPrivateKeyInfo structures using an appropriate password
85 based encryption algorithm. With this option an unencrypted
86 PrivateKeyInfo structure is expected or output. This option does
87 not encrypt private keys at all and should only be used when
88 absolutely necessary. Certain software such as some versions of
89 Java code signing software used unencrypted private keys.
90 -v2 alg
92 This option sets the PKCS#5 v2.0 algorithm.
93 The alg argument is the encryption algorithm to use, valid values
95 include aes128, aes256 and des3. If this option isn't specified
96 then aes256 is used.
97 -v2prf alg
99 This option sets the PRF algorithm to use with PKCS#5 v2.0. A
100 typical value value would be hmacWithSHA256. If this option isn't
101 set then the default for the cipher is used or hmacWithSHA256 if
102 there is no default.
103 Some implementations may not support custom PRF algorithms and may
105 require the hmacWithSHA1 option to work.
106 -v1 alg
108 This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be
109 used. Some older implementations may not support PKCS#5 v2.0 and
110 may require this option. If not specified PKCS#5 v2.0 form is
111 used.
112 -scrypt
114 Uses the scrypt algorithm for private key encryption using default
115 parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with
116 a 256 bit key. These parameters can be modified using the
117 -scrypt_N, -scrypt_r, -scrypt_p and -v2 options.
118 -scrypt_N N, -scrypt_r r, -scrypt_p p
120 Sets the scrypt N, r or p parameters.
121 -rand files, -writerand file
123 See "Random State Options" in openssl(1) for details.
124 -engine id
126 See "Engine Options" in openssl(1). This option is deprecated.
127 -provider name
129 -provider-path path
130 -propquery propq
131 See "Provider Options" in openssl(1), provider(7), and property(7).
132
134 By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using
135 256 bit AES with HMAC and SHA256 is used.
136 Some older implementations do not support PKCS#5 v2.0 format and
138 require the older PKCS#5 v1.5 form instead, possibly also requiring
139 insecure weak encryption algorithms such as 56 bit DES.
140 Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
142 counts are more secure that those encrypted using the traditional
143 SSLeay compatible formats. So if additional security is considered
144 important the keys should be converted.
145 It is possible to write out DER encoded encrypted private keys in
147 PKCS#8 format because the encryption details are included at an ASN1
148 level whereas the traditional format includes them at a PEM level.
149
151 Various algorithms can be used with the -v1 command line option,
152 including PKCS#5 v1.5 and PKCS#12. These are described in more detail
153 below.
154 PBE-MD2-DES PBE-MD5-DES
156 These algorithms were included in the original PKCS#5 v1.5
157 specification. They only offer 56 bits of protection since they
158 both use DES.
159 PBE-SHA1-RC2-64, PBE-MD2-RC2-64, PBE-MD5-RC2-64, PBE-SHA1-DES
161 These algorithms are not mentioned in the original PKCS#5 v1.5
162 specification but they use the same key derivation algorithm and
163 are supported by some software. They are mentioned in PKCS#5 v2.0.
164 They use either 64 bit RC2 or 56 bit DES.
165 PBE-SHA1-RC4-128, PBE-SHA1-RC4-40, PBE-SHA1-3DES, PBE-SHA1-2DES,
167 PBE-SHA1-RC2-128, PBE-SHA1-RC2-40
168 These algorithms use the PKCS#12 password based encryption
169 algorithm and allow strong encryption algorithms like triple DES or
170 128 bit RC2 to be used.
171
173 Convert a private key to PKCS#8 format using default parameters (AES
174 with 256 bit key and hmacWithSHA256):
175 openssl pkcs8 -in key.pem -topk8 -out enckey.pem
177 Convert a private key to PKCS#8 unencrypted format:
179 openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem
181 Convert a private key to PKCS#5 v2.0 format using triple DES:
183 openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
185 Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in
187 CBC mode and hmacWithSHA512 PRF:
188 openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem
190 Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
192 (DES):
193 openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem
195 Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
197 (3DES):
198 openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
200 Read a DER unencrypted PKCS#8 format private key:
202 openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
204 Convert a private key from any PKCS#8 encrypted format to traditional
206 format:
207 openssl pkcs8 -in pk8.pem -traditional -out key.pem
209 Convert a private key to PKCS#8 format, encrypting with AES-256 and
211 with one million iterations of the password:
212 openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
214
216 Test vectors from this PKCS#5 v2.0 implementation were posted to the
217 pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
218 counts, several people confirmed that they could decrypt the private
219 keys produced and therefore, it can be assumed that the PKCS#5 v2.0
220 implementation is reasonably accurate at least as far as these
221 algorithms are concerned.
222 The format of PKCS#8 DSA (and other) private keys is not well
224 documented: it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's
225 default DSA PKCS#8 private key format complies with this standard.
226
228 There should be an option that prints out the encryption algorithm in
229 use and other details such as the iteration count.
230
232 openssl(1), openssl-dsa(1), openssl-rsa(1), openssl-genrsa(1),
233 openssl-gendsa(1)
234
236 The -iter option was added in OpenSSL 1.1.0.
237 The -engine option was deprecated in OpenSSL 3.0.
239
241 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
242 Licensed under the Apache License 2.0 (the "License"). You may not use
244 this file except in compliance with the License. You can obtain a copy
245 in the file LICENSE in the source distribution or at
246 <https://www.openssl.org/source/license.html>.
2473.0.9 2023-07-27 OPENSSL-PKCS8(1ossl)