1PK12UTIL(1) NSS Security Tools PK12UTIL(1)
2
6 pk12util - Export and import keys and certificate to or from a PKCS #12
7 file and the NSS database
8
10 pk12util [-i p12File|-l p12File|-o p12File] [-c keyCipher]
11 [-C certCipher] [-d directory] [-h tokenname]
12 [-m | --key-len keyLength] [-M hashAlg] [-n certname]
13 [-P dbprefix] [-r] [-v] [--cert-key-len certKeyLength]
14 [-k slotPasswordFile|-K slotPassword]
15 [-w p12filePasswordFile|-W p12filePassword]
16
18 This documentation is still work in progress. Please contribute to the
19 initial review in Mozilla NSS bug 836477[1]
20
22 The PKCS #12 utility, pk12util, enables sharing certificates among any
23 server that supports PKCS #12. The tool can import certificates and
24 keys from PKCS #12 files into security databases, export certificates,
25 and list certificates and keys.
26
28 Options
29 -i p12file
31 Import keys and certificates from a PKCS #12 file into a security
32 database.
33 -l p12file
35 List the keys and certificates in PKCS #12 file.
36 -o p12file
38 Export keys and certificates from the security database to a PKCS
39 #12 file.
40 Arguments
42 -c keyCipher
44 Specify the key encryption algorithm.
45 -C certCipher
47 Specify the certiticate encryption algorithm.
48 -d directory
50 Specify the database directory into which to import to or export
51 from certificates and keys.
52 pk12util supports SQLite databases (cert9.db, key4.db, and
54 pkcs11.txt).
55 -h tokenname
57 Specify the name of the token to import into or export from.
58 -k slotPasswordFile
60 Specify the text file containing the slot's password.
61 -K slotPassword
63 Specify the slot's password.
64 -m | --key-len keyLength
66 Specify the desired length of the symmetric key to be used to
67 encrypt the private key.
68 -M hashAlg
70 Specify the hash algorithm used in the pkcs #12 mac. This algorithm
71 also specifies the HMAC used in the prf when using pkcs #5 v2.
72 --cert-key-len certKeyLength
74 Specify the desired length of the symmetric key to be used to
75 encrypt the certificates and other meta-data.
76 -n certname
78 Specify the nickname of the cert and private key to export.
79 The nickname can also be a PKCS #11 URI. For example, if you have a
81 certificate named "my-server-cert" on the internal certificate
82 store, it can be unambiguously specified as
83 "pkcs11:token=NSS%20Certificate%20DB;object=my-server-cert". For
84 details about the format, see RFC 7512.
85 -P prefix
87 Specify the prefix used on the certificate and key databases. This
88 option is provided as a special case. Changing the names of the
89 certificate and key databases is not recommended.
90 -r
92 Dumps all of the data in raw (binary) form. This must be saved as a
93 DER file. The default is to return information in a pretty-print
94 ASCII format, which displays the information about the certificates
95 and public keys in the p12 file.
96 -v
98 Enable debug logging when importing.
99 -w p12filePasswordFile
101 Specify the text file containing the pkcs #12 file password.
102 -W p12filePassword
104 Specify the pkcs #12 file password.
105
107 • 0 - No error
108 • 1 - User Cancelled
110 • 2 - Usage error
112 • 6 - NLS init error
114 • 8 - Certificate DB open error
116 • 9 - Key DB open error
118 • 10 - File initialization error
120 • 11 - Unicode conversion error
122 • 12 - Temporary file creation error
124 • 13 - PKCS11 get slot error
126 • 14 - PKCS12 decoder start error
128 • 15 - error read from import file
130 • 16 - pkcs12 decode error
132 • 17 - pkcs12 decoder verify error
134 • 18 - pkcs12 decoder validate bags error
136 • 19 - pkcs12 decoder import bags error
138 • 20 - key db conversion version 3 to version 2 error
140 • 21 - cert db conversion version 7 to version 5 error
142 • 22 - cert and key dbs patch error
144 • 23 - get default cert db error
146 • 24 - find cert by nickname error
148 • 25 - create export context error
150 • 26 - PKCS12 add password itegrity error
152 • 27 - cert and key Safes creation error
154 • 28 - PKCS12 add cert and key error
156 • 29 - PKCS12 encode error
158
160 Importing Keys and Certificates
161 The most basic usage of pk12util for importing a certificate or key is
163 the PKCS #12 input file (-i) and some way to specify the security
164 database being accessed (either -d for a directory or -h for a token).
165 pk12util -i p12File [-h tokenname] [-v] [-d directory] [-P dbprefix]
167 [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W
168 p12filePassword]
169 For example:
171 # pk12util -i /tmp/cert-files/users.p12 -d /home/my/sharednssdb
173 Enter a password which will be used to encrypt your keys.
175 The password should be at least 8 characters long,
176 and should contain at least one non-alphabetic character.
177 Enter new password:
179 Re-enter password:
180 Enter password for PKCS12 file:
181 pk12util: PKCS12 IMPORT SUCCESSFUL
182 Exporting Keys and Certificates
184 Using the pk12util command to export certificates and keys requires
186 both the name of the certificate to extract from the database (-n) and
187 the PKCS #12-formatted output file to write to. There are optional
188 parameters that can be used to encrypt the file to protect the
189 certificate material.
190 pk12util -o p12File -n certname [-c keyCipher] [-C certCipher]
192 [-m|--key_len keyLen] [-n|--cert_key_len certKeyLen] [-d directory] [-P
193 dbprefix] [-k slotPasswordFile|-K slotPassword] [-w
194 p12filePasswordFile|-W p12filePassword]
195 For example:
197 # pk12util -o certs.p12 -n Server-Cert -d /home/my/sharednssdb
199 Enter password for PKCS12 file:
200 Re-enter password:
201 Listing Keys and Certificates
203 The information in a .p12 file are not human-readable. The certificates
205 and keys in the file can be printed (listed) in a human-readable
206 pretty-print format that shows information for every certificate and
207 any public keys in the .p12 file.
208 pk12util -l p12File [-h tokenname] [-r] [-d directory] [-P dbprefix]
210 [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W
211 p12filePassword]
212 For example, this prints the default ASCII output:
214 # pk12util -l certs.p12
216 Enter password for PKCS12 file:
218 Key(shrouded):
219 Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
220 Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
222 Parameters:
223 Salt:
224 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
225 Iteration Count: 1 (0x1)
226 Certificate:
227 Data:
228 Version: 3 (0x2)
229 Serial Number: 13 (0xd)
230 Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
231 Issuer: "E=personal-freemail@thawte.com,CN=Thawte Personal Freemail C
232 A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T
233 own,ST=Western Cape,C=ZA"
234 Alternatively, the -r prints the certificates and then exports them
237 into separate DER binary files. This allows the certificates to be fed
238 to another application that supports .p12 files. Each certificate is
239 written to a sequentially-number file, beginning with file0001.der and
240 continuing through file000N.der, incrementing the number for every
241 certificate:
242 pk12util -l test.p12 -r
244 Enter password for PKCS12 file:
245 Key(shrouded):
246 Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
247 Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
249 Parameters:
250 Salt:
251 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
252 Iteration Count: 1 (0x1)
253 Certificate Friendly Name: Thawte Personal Freemail Issuing CA - Thawte Consulting
254 Certificate Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
256
259 PKCS #12 provides for not only the protection of the private keys but
260 also the certificate and meta-data associated with the keys.
261 Password-based encryption is used to protect private keys on export to
262 a PKCS #12 file and, optionally, the associated certificates. If no
263 algorithm is specified, the tool defaults to using PKCS #12 SHA-1 and
264 3-key triple DES for private key encryption. When not in FIPS mode,
265 PKCS #12 SHA-1 and 40-bit RC4 is used for certificate encryption. When
266 in FIPS mode, there is no certificate encryption. If certificate
267 encryption is not wanted, specify "NONE" as the argument of the -C
268 option.
269 The private key is always protected with strong encryption by default.
271 Several types of ciphers are supported.
273 PKCS #5 password-based encryption
275 • PBES2 with AES-CBC-Pad as underlying encryption scheme
277 ("AES-128-CBC", "AES-192-CBC", and "AES-256-CBC")
278 PKCS #12 password-based encryption
280 • SHA-1 and 128-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
282 RC4" or "RC4")
283 • SHA-1 and 40-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
285 RC4") (used by default for certificate encryption in non-FIPS
286 mode)
287 • SHA-1 and 3-key triple-DES ("PKCS #12 V2 PBE With SHA-1 And
289 3KEY Triple DES-CBC" or "DES-EDE3-CBC")
290 • SHA-1 and 128-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
292 RC2 CBC" or "RC2-CBC")
293 • SHA-1 and 40-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
295 RC2 CBC")
296 With PKCS #12, the crypto provider may be the soft token module or an
298 external hardware module. If the cryptographic module does not support
299 the requested algorithm, then the next best fit will be selected
300 (usually the default). If no suitable replacement for the desired
301 algorithm can be found, the tool returns the error no security module
302 can perform the requested operation.
303
305 NSS originally used BerkeleyDB databases to store security information.
306 The last versions of these legacy databases are:
307 • cert8.db for certificates
309 • key3.db for keys
311 • secmod.db for PKCS #11 module information
313 BerkeleyDB has performance limitations, though, which prevent it from
315 being easily used by multiple applications simultaneously. NSS has some
316 flexibility that allows applications to use their own, independent
317 database engine while keeping a shared database and working around the
318 access issues. Still, NSS requires more flexibility to provide a truly
319 shared security database.
320 In 2009, NSS introduced a new set of databases that are SQLite
322 databases rather than BerkleyDB. These new databases provide more
323 accessibility and performance:
324 • cert9.db for certificates
326 • key4.db for keys
328 • pkcs11.txt, which is listing of all of the PKCS #11 modules
330 contained in a new subdirectory in the security databases directory
331 Because the SQLite databases are designed to be shared, these are the
333 shared database type. The shared database type is preferred; the legacy
334 format is included for backward compatibility.
335 By default, the tools (certutil, pk12util, modutil) assume that the
337 given security databases use the SQLite type.
338 • https://wiki.mozilla.org/NSS_Shared_DB_Howto
340 For an engineering draft on the changes in the shared NSS databases,
342 see the NSS project wiki:
343 • https://wiki.mozilla.org/NSS_Shared_DB
345
347 The exporting behavior of pk12util has changed over time, while
348 importing files exported with older versions of NSS is still supported.
349 Until the 3.30 release, pk12util used the UTF-16 encoding for the PKCS
351 #5 password-based encryption schemes, while the recommendation is to
352 encode passwords in UTF-8 if the used encryption scheme is defined
353 outside of the PKCS #12 standard.
354 Until the 3.31 release, even when "AES-128-CBC" or "AES-192-CBC" is
356 given from the command line, pk12util always used 256-bit AES as the
357 underlying encryption scheme.
358 For historical reasons, pk12util accepts password-based encryption
360 schemes not listed in this document. However, those schemes are not
361 officially supported and may have issues in interoperability with other
362 tools.
363
365 certutil (1)
366 modutil (1)
368 The NSS wiki has information on the new database design and how to
370 configure applications to use it.
371 • https://wiki.mozilla.org/NSS_Shared_DB_Howto
373 • https://wiki.mozilla.org/NSS_Shared_DB
375
377 For information about NSS and other tools related to NSS (like JSS),
378 check out the NSS project wiki at
379 http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates
380 directly to NSS code changes and releases.
381 Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
383 IRC: Freenode at #dogtag-pki
385
387 The NSS tools were written and maintained by developers with Netscape,
388 Red Hat, Sun, Oracle, Mozilla, and Google.
389 Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
391 <dlackey@redhat.com>.
392
394 Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL
395 was not distributed with this file, You can obtain one at
396 http://mozilla.org/MPL/2.0/.
397
399 1. Mozilla NSS bug 836477
400 https://bugzilla.mozilla.org/show_bug.cgi?id=836477
401nss-tools 11 January 2023 PK12UTIL(1)