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 two types of databases: the legacy security
54 databases (cert8.db, key3.db, and secmod.db) and new SQLite
55 databases (cert9.db, key4.db, and pkcs11.txt). If the prefix dbm:
56 is not used, then the tool assumes that the given databases are in
57 the SQLite format.
58 -h tokenname
60 Specify the name of the token to import into or export from.
61 -k slotPasswordFile
63 Specify the text file containing the slot's password.
64 -K slotPassword
66 Specify the slot's password.
67 -m | --key-len keyLength
69 Specify the desired length of the symmetric key to be used to
70 encrypt the private key.
71 -M hashAlg
73 Specify the hash algorithm used in the pkcs #12 mac. This algorithm
74 also specifies the HMAC used in the prf when using pkcs #5 v2.
75 --cert-key-len certKeyLength
77 Specify the desired length of the symmetric key to be used to
78 encrypt the certificates and other meta-data.
79 -n certname
81 Specify the nickname of the cert and private key to export.
82 The nickname can also be a PKCS #11 URI. For example, if you have a
84 certificate named "my-server-cert" on the internal certificate
85 store, it can be unambiguously specified as
86 "pkcs11:token=NSS%20Certificate%20DB;object=my-server-cert". For
87 details about the format, see RFC 7512.
88 -P prefix
90 Specify the prefix used on the certificate and key databases. This
91 option is provided as a special case. Changing the names of the
92 certificate and key databases is not recommended.
93 -r
95 Dumps all of the data in raw (binary) form. This must be saved as a
96 DER file. The default is to return information in a pretty-print
97 ASCII format, which displays the information about the certificates
98 and public keys in the p12 file.
99 -v
101 Enable debug logging when importing.
102 -w p12filePasswordFile
104 Specify the text file containing the pkcs #12 file password.
105 -W p12filePassword
107 Specify the pkcs #12 file password.
108
110 • 0 - No error
111 • 1 - User Cancelled
113 • 2 - Usage error
115 • 6 - NLS init error
117 • 8 - Certificate DB open error
119 • 9 - Key DB open error
121 • 10 - File initialization error
123 • 11 - Unicode conversion error
125 • 12 - Temporary file creation error
127 • 13 - PKCS11 get slot error
129 • 14 - PKCS12 decoder start error
131 • 15 - error read from import file
133 • 16 - pkcs12 decode error
135 • 17 - pkcs12 decoder verify error
137 • 18 - pkcs12 decoder validate bags error
139 • 19 - pkcs12 decoder import bags error
141 • 20 - key db conversion version 3 to version 2 error
143 • 21 - cert db conversion version 7 to version 5 error
145 • 22 - cert and key dbs patch error
147 • 23 - get default cert db error
149 • 24 - find cert by nickname error
151 • 25 - create export context error
153 • 26 - PKCS12 add password itegrity error
155 • 27 - cert and key Safes creation error
157 • 28 - PKCS12 add cert and key error
159 • 29 - PKCS12 encode error
161
163 Importing Keys and Certificates
164 The most basic usage of pk12util for importing a certificate or key is
166 the PKCS #12 input file (-i) and some way to specify the security
167 database being accessed (either -d for a directory or -h for a token).
168 pk12util -i p12File [-h tokenname] [-v] [-d directory] [-P dbprefix]
170 [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W
171 p12filePassword]
172 For example:
174 # pk12util -i /tmp/cert-files/users.p12 -d /home/my/sharednssdb
176 Enter a password which will be used to encrypt your keys.
178 The password should be at least 8 characters long,
179 and should contain at least one non-alphabetic character.
180 Enter new password:
182 Re-enter password:
183 Enter password for PKCS12 file:
184 pk12util: PKCS12 IMPORT SUCCESSFUL
185 Exporting Keys and Certificates
187 Using the pk12util command to export certificates and keys requires
189 both the name of the certificate to extract from the database (-n) and
190 the PKCS #12-formatted output file to write to. There are optional
191 parameters that can be used to encrypt the file to protect the
192 certificate material.
193 pk12util -o p12File -n certname [-c keyCipher] [-C certCipher]
195 [-m|--key_len keyLen] [-n|--cert_key_len certKeyLen] [-d directory] [-P
196 dbprefix] [-k slotPasswordFile|-K slotPassword] [-w
197 p12filePasswordFile|-W p12filePassword]
198 For example:
200 # pk12util -o certs.p12 -n Server-Cert -d /home/my/sharednssdb
202 Enter password for PKCS12 file:
203 Re-enter password:
204 Listing Keys and Certificates
206 The information in a .p12 file are not human-readable. The certificates
208 and keys in the file can be printed (listed) in a human-readable
209 pretty-print format that shows information for every certificate and
210 any public keys in the .p12 file.
211 pk12util -l p12File [-h tokenname] [-r] [-d directory] [-P dbprefix]
213 [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W
214 p12filePassword]
215 For example, this prints the default ASCII output:
217 # pk12util -l certs.p12
219 Enter password for PKCS12 file:
221 Key(shrouded):
222 Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
223 Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
225 Parameters:
226 Salt:
227 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
228 Iteration Count: 1 (0x1)
229 Certificate:
230 Data:
231 Version: 3 (0x2)
232 Serial Number: 13 (0xd)
233 Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
234 Issuer: "E=personal-freemail@thawte.com,CN=Thawte Personal Freemail C
235 A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T
236 own,ST=Western Cape,C=ZA"
237 Alternatively, the -r prints the certificates and then exports them
240 into separate DER binary files. This allows the certificates to be fed
241 to another application that supports .p12 files. Each certificate is
242 written to a sequentially-number file, beginning with file0001.der and
243 continuing through file000N.der, incrementing the number for every
244 certificate:
245 pk12util -l test.p12 -r
247 Enter password for PKCS12 file:
248 Key(shrouded):
249 Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
250 Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
252 Parameters:
253 Salt:
254 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
255 Iteration Count: 1 (0x1)
256 Certificate Friendly Name: Thawte Personal Freemail Issuing CA - Thawte Consulting
257 Certificate Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
259
262 PKCS #12 provides for not only the protection of the private keys but
263 also the certificate and meta-data associated with the keys.
264 Password-based encryption is used to protect private keys on export to
265 a PKCS #12 file and, optionally, the associated certificates. If no
266 algorithm is specified, the tool defaults to using PKCS #12 SHA-1 and
267 3-key triple DES for private key encryption. When not in FIPS mode,
268 PKCS #12 SHA-1 and 40-bit RC4 is used for certificate encryption. When
269 in FIPS mode, there is no certificate encryption. If certificate
270 encryption is not wanted, specify "NONE" as the argument of the -C
271 option.
272 The private key is always protected with strong encryption by default.
274 Several types of ciphers are supported.
276 PKCS #5 password-based encryption
278 • PBES2 with AES-CBC-Pad as underlying encryption scheme
280 ("AES-128-CBC", "AES-192-CBC", and "AES-256-CBC")
281 PKCS #12 password-based encryption
283 • SHA-1 and 128-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
285 RC4" or "RC4")
286 • SHA-1 and 40-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
288 RC4") (used by default for certificate encryption in non-FIPS
289 mode)
290 • SHA-1 and 3-key triple-DES ("PKCS #12 V2 PBE With SHA-1 And
292 3KEY Triple DES-CBC" or "DES-EDE3-CBC")
293 • SHA-1 and 128-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
295 RC2 CBC" or "RC2-CBC")
296 • SHA-1 and 40-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
298 RC2 CBC")
299 With PKCS #12, the crypto provider may be the soft token module or an
301 external hardware module. If the cryptographic module does not support
302 the requested algorithm, then the next best fit will be selected
303 (usually the default). If no suitable replacement for the desired
304 algorithm can be found, the tool returns the error no security module
305 can perform the requested operation.
306
308 NSS originally used BerkeleyDB databases to store security information.
309 The last versions of these legacy databases are:
310 • cert8.db for certificates
312 • key3.db for keys
314 • secmod.db for PKCS #11 module information
316 BerkeleyDB has performance limitations, though, which prevent it from
318 being easily used by multiple applications simultaneously. NSS has some
319 flexibility that allows applications to use their own, independent
320 database engine while keeping a shared database and working around the
321 access issues. Still, NSS requires more flexibility to provide a truly
322 shared security database.
323 In 2009, NSS introduced a new set of databases that are SQLite
325 databases rather than BerkleyDB. These new databases provide more
326 accessibility and performance:
327 • cert9.db for certificates
329 • key4.db for keys
331 • pkcs11.txt, which is listing of all of the PKCS #11 modules
333 contained in a new subdirectory in the security databases directory
334 Because the SQLite databases are designed to be shared, these are the
336 shared database type. The shared database type is preferred; the legacy
337 format is included for backward compatibility.
338 By default, the tools (certutil, pk12util, modutil) assume that the
340 given security databases use the SQLite type Using the legacy databases
341 must be manually specified by using the dbm: prefix with the given
342 security directory. For example:
343 # pk12util -i /tmp/cert-files/users.p12 -d dbm:/home/my/sharednssdb
345 To set the legacy database type as the default type for the tools, set
347 the NSS_DEFAULT_DB_TYPE environment variable to dbm:
348 export NSS_DEFAULT_DB_TYPE="dbm"
350 This line can be set added to the ~/.bashrc file to make the change
352 permanent.
353 • https://wiki.mozilla.org/NSS_Shared_DB_Howto
355 For an engineering draft on the changes in the shared NSS databases,
357 see the NSS project wiki:
358 • https://wiki.mozilla.org/NSS_Shared_DB
360
362 The exporting behavior of pk12util has changed over time, while
363 importing files exported with older versions of NSS is still supported.
364 Until the 3.30 release, pk12util used the UTF-16 encoding for the PKCS
366 #5 password-based encryption schemes, while the recommendation is to
367 encode passwords in UTF-8 if the used encryption scheme is defined
368 outside of the PKCS #12 standard.
369 Until the 3.31 release, even when "AES-128-CBC" or "AES-192-CBC" is
371 given from the command line, pk12util always used 256-bit AES as the
372 underlying encryption scheme.
373 For historical reasons, pk12util accepts password-based encryption
375 schemes not listed in this document. However, those schemes are not
376 officially supported and may have issues in interoperability with other
377 tools.
378
380 certutil (1)
381 modutil (1)
383 The NSS wiki has information on the new database design and how to
385 configure applications to use it.
386 • https://wiki.mozilla.org/NSS_Shared_DB_Howto
388 • https://wiki.mozilla.org/NSS_Shared_DB
390
392 For information about NSS and other tools related to NSS (like JSS),
393 check out the NSS project wiki at
394 http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates
395 directly to NSS code changes and releases.
396 Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
398 IRC: Freenode at #dogtag-pki
400
402 The NSS tools were written and maintained by developers with Netscape,
403 Red Hat, Sun, Oracle, Mozilla, and Google.
404 Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
406 <dlackey@redhat.com>.
407
409 Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL
410 was not distributed with this file, You can obtain one at
411 http://mozilla.org/MPL/2.0/.
412
414 1. Mozilla NSS bug 836477
415 https://bugzilla.mozilla.org/show_bug.cgi?id=836477
416nss-tools 29 May 2021 PK12UTIL(1)