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] [-d [sql:]directory]
11 [-h tokenname] [-P dbprefix] [-r] [-v]
12 [-k slotPasswordFile|-K slotPassword]
13 [-w p12filePasswordFile|-W p12filePassword]
14
16 This documentation is still work in progress. Please contribute to the
17 initial review in Mozilla NSS bug 836477[1]
18
20 The PKCS #12 utility, pk12util, enables sharing certificates among any
21 server that supports PKCS #12. The tool can import certificates and
22 keys from PKCS #12 files into security databases, export certificates,
23 and list certificates and keys.
24
26 Options
27 -i p12file
29 Import keys and certificates from a PKCS #12 file into a security
30 database.
31 -l p12file
33 List the keys and certificates in PKCS #12 file.
34 -o p12file
36 Export keys and certificates from the security database to a PKCS
37 #12 file.
38 Arguments
40 -c keyCipher
42 Specify the key encryption algorithm.
43 -C certCipher
45 Specify the certiticate encryption algorithm.
46 -d [sql:]directory
48 Specify the database directory into which to import to or export
49 from certificates and keys.
50 pk12util supports two types of databases: the legacy security
52 databases (cert8.db, key3.db, and secmod.db) and new SQLite
53 databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql:
54 is not used, then the tool assumes that the given databases are in
55 the old format.
56 -h tokenname
58 Specify the name of the token to import into or export from.
59 -k slotPasswordFile
61 Specify the text file containing the slot's password.
62 -K slotPassword
64 Specify the slot's password.
65 -m | --key-len keyLength
67 Specify the desired length of the symmetric key to be used to
68 encrypt the private key.
69 -n | --cert-key-len certKeyLength
71 Specify the desired length of the symmetric key to be used to
72 encrypt the certificates and other meta-data.
73 -n certname
75 Specify the nickname of the cert and private key to export.
76 -P prefix
78 Specify the prefix used on the certificate and key databases. This
79 option is provided as a special case. Changing the names of the
80 certificate and key databases is not recommended.
81 -r
83 Dumps all of the data in raw (binary) form. This must be saved as a
84 DER file. The default is to return information in a pretty-print
85 ASCII format, which displays the information about the certificates
86 and public keys in the p12 file.
87 -v
89 Enable debug logging when importing.
90 -w p12filePasswordFile
92 Specify the text file containing the pkcs #12 file password.
93 -W p12filePassword
95 Specify the pkcs #12 file password.
96
98 · 0 - No error
99 · 1 - User Cancelled
101 · 2 - Usage error
103 · 6 - NLS init error
105 · 8 - Certificate DB open error
107 · 9 - Key DB open error
109 · 10 - File initialization error
111 · 11 - Unicode conversion error
113 · 12 - Temporary file creation error
115 · 13 - PKCS11 get slot error
117 · 14 - PKCS12 decoder start error
119 · 15 - error read from import file
121 · 16 - pkcs12 decode error
123 · 17 - pkcs12 decoder verify error
125 · 18 - pkcs12 decoder validate bags error
127 · 19 - pkcs12 decoder import bags error
129 · 20 - key db conversion version 3 to version 2 error
131 · 21 - cert db conversion version 7 to version 5 error
133 · 22 - cert and key dbs patch error
135 · 23 - get default cert db error
137 · 24 - find cert by nickname error
139 · 25 - create export context error
141 · 26 - PKCS12 add password itegrity error
143 · 27 - cert and key Safes creation error
145 · 28 - PKCS12 add cert and key error
147 · 29 - PKCS12 encode error
149
151 Importing Keys and Certificates
152 The most basic usage of pk12util for importing a certificate or key is
154 the PKCS #12 input file (-i) and some way to specify the security
155 database being accessed (either -d for a directory or -h for a token).
156 pk12util -i p12File [-h tokenname] [-v] [-d [sql:]directory] [-P
158 dbprefix] [-k slotPasswordFile|-K slotPassword] [-w
159 p12filePasswordFile|-W p12filePassword]
160 For example:
162 # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb
164 Enter a password which will be used to encrypt your keys.
166 The password should be at least 8 characters long,
167 and should contain at least one non-alphabetic character.
168 Enter new password:
170 Re-enter password:
171 Enter password for PKCS12 file:
172 pk12util: PKCS12 IMPORT SUCCESSFUL
173 Exporting Keys and Certificates
175 Using the pk12util command to export certificates and keys requires
177 both the name of the certificate to extract from the database (-n) and
178 the PKCS #12-formatted output file to write to. There are optional
179 parameters that can be used to encrypt the file to protect the
180 certificate material.
181 pk12util -o p12File -n certname [-c keyCipher] [-C certCipher]
183 [-m|--key_len keyLen] [-n|--cert_key_len certKeyLen] [-d
184 [sql:]directory] [-P dbprefix] [-k slotPasswordFile|-K slotPassword]
185 [-w p12filePasswordFile|-W p12filePassword]
186 For example:
188 # pk12util -o certs.p12 -n Server-Cert -d sql:/home/my/sharednssdb
190 Enter password for PKCS12 file:
191 Re-enter password:
192 Listing Keys and Certificates
194 The information in a .p12 file are not human-readable. The certificates
196 and keys in the file can be printed (listed) in a human-readable
197 pretty-print format that shows information for every certificate and
198 any public keys in the .p12 file.
199 pk12util -l p12File [-h tokenname] [-r] [-d [sql:]directory] [-P
201 dbprefix] [-k slotPasswordFile|-K slotPassword] [-w
202 p12filePasswordFile|-W p12filePassword]
203 For example, this prints the default ASCII output:
205 # pk12util -l certs.p12
207 Enter password for PKCS12 file:
209 Key(shrouded):
210 Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
211 Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
213 Parameters:
214 Salt:
215 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
216 Iteration Count: 1 (0x1)
217 Certificate:
218 Data:
219 Version: 3 (0x2)
220 Serial Number: 13 (0xd)
221 Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
222 Issuer: "E=personal-freemail@thawte.com,CN=Thawte Personal Freemail C
223 A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T
224 own,ST=Western Cape,C=ZA"
225 Alternatively, the -r prints the certificates and then exports them
228 into separate DER binary files. This allows the certificates to be fed
229 to another application that supports .p12 files. Each certificate is
230 written to a sequentially-number file, beginning with file0001.der and
231 continuing through file000N.der, incrementing the number for every
232 certificate:
233 pk12util -l test.p12 -r
235 Enter password for PKCS12 file:
236 Key(shrouded):
237 Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
238 Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
240 Parameters:
241 Salt:
242 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
243 Iteration Count: 1 (0x1)
244 Certificate Friendly Name: Thawte Personal Freemail Issuing CA - Thawte Consulting
245 Certificate Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
247
250 PKCS #12 provides for not only the protection of the private keys but
251 also the certificate and meta-data associated with the keys.
252 Password-based encryption is used to protect private keys on export to
253 a PKCS #12 file and, optionally, the associated certificates. If no
254 algorithm is specified, the tool defaults to using PKCS #12 SHA-1 and
255 3-key triple DES for private key encryption. When not in FIPS mode,
256 PKCS #12 SHA-1 and 40-bit RC4 is used for certificate encryption. When
257 in FIPS mode, there is no certificate encryption. If certificate
258 encryption is not wanted, specify "NONE" as the argument of the -C
259 option.
260 The private key is always protected with strong encryption by default.
262 Several types of ciphers are supported.
264 PKCS #5 password-based encryption
266 · PBES2 with AES-CBC-Pad as underlying encryption scheme
268 ("AES-128-CBC", "AES-192-CBC", and "AES-256-CBC")
269 PKCS #12 password-based encryption
271 · SHA-1 and 128-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
273 RC4" or "RC4")
274 · SHA-1 and 40-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
276 RC4") (used by default for certificate encryption in non-FIPS
277 mode)
278 · SHA-1 and 3-key triple-DES ("PKCS #12 V2 PBE With SHA-1 And
280 3KEY Triple DES-CBC" or "DES-EDE3-CBC")
281 · SHA-1 and 128-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
283 RC2 CBC" or "RC2-CBC")
284 · SHA-1 and 40-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
286 RC2 CBC")
287 With PKCS #12, the crypto provider may be the soft token module or an
289 external hardware module. If the cryptographic module does not support
290 the requested algorithm, then the next best fit will be selected
291 (usually the default). If no suitable replacement for the desired
292 algorithm can be found, the tool returns the error no security module
293 can perform the requested operation.
294
296 NSS originally used BerkeleyDB databases to store security information.
297 The last versions of these legacy databases are:
298 · cert8.db for certificates
300 · key3.db for keys
302 · secmod.db for PKCS #11 module information
304 BerkeleyDB has performance limitations, though, which prevent it from
306 being easily used by multiple applications simultaneously. NSS has some
307 flexibility that allows applications to use their own, independent
308 database engine while keeping a shared database and working around the
309 access issues. Still, NSS requires more flexibility to provide a truly
310 shared security database.
311 In 2009, NSS introduced a new set of databases that are SQLite
313 databases rather than BerkleyDB. These new databases provide more
314 accessibility and performance:
315 · cert9.db for certificates
317 · key4.db for keys
319 · pkcs11.txt, which is listing of all of the PKCS #11 modules
321 contained in a new subdirectory in the security databases directory
322 Because the SQLite databases are designed to be shared, these are the
324 shared database type. The shared database type is preferred; the legacy
325 format is included for backward compatibility.
326 By default, the tools (certutil, pk12util, modutil) assume that the
328 given security databases follow the more common legacy type. Using the
329 SQLite databases must be manually specified by using the sql: prefix
330 with the given security directory. For example:
331 # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb
333 To set the shared database type as the default type for the tools, set
335 the NSS_DEFAULT_DB_TYPE environment variable to sql:
336 export NSS_DEFAULT_DB_TYPE="sql"
338 This line can be set added to the ~/.bashrc file to make the change
340 permanent.
341 Most applications do not use the shared database by default, but they
343 can be configured to use them. For example, this how-to article covers
344 how to configure Firefox and Thunderbird to use the new shared NSS
345 databases:
346 · https://wiki.mozilla.org/NSS_Shared_DB_Howto
348 For an engineering draft on the changes in the shared NSS databases,
350 see the NSS project wiki:
351 · https://wiki.mozilla.org/NSS_Shared_DB
353
355 The exporting behavior of pk12util has changed over time, while
356 importing files exported with older versions of NSS is still supported.
357 Until the 3.30 release, pk12util used the UTF-16 encoding for the PKCS
359 #5 password-based encryption schemes, while the recommendation is to
360 encode passwords in UTF-8 if the used encryption scheme is defined
361 outside of the PKCS #12 standard.
362 Until the 3.31 release, even when "AES-128-CBC" or "AES-192-CBC" is
364 given from the command line, pk12util always used 256-bit AES as the
365 underlying encryption scheme.
366 For historical reasons, pk12util accepts password-based encryption
368 schemes not listed in this document. However, those schemes are not
369 officially supported and may have issues in interoperability with other
370 tools.
371
373 certutil (1)
374 modutil (1)
376 The NSS wiki has information on the new database design and how to
378 configure applications to use it.
379 · https://wiki.mozilla.org/NSS_Shared_DB_Howto
381 · https://wiki.mozilla.org/NSS_Shared_DB
383
385 For information about NSS and other tools related to NSS (like JSS),
386 check out the NSS project wiki at
387 http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates
388 directly to NSS code changes and releases.
389 Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
391 IRC: Freenode at #dogtag-pki
393
395 The NSS tools were written and maintained by developers with Netscape,
396 Red Hat, Sun, Oracle, Mozilla, and Google.
397 Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
399 <dlackey@redhat.com>.
400
402 Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL
403 was not distributed with this file, You can obtain one at
404 http://mozilla.org/MPL/2.0/.
405
407 1. Mozilla NSS bug 836477
408 https://bugzilla.mozilla.org/show_bug.cgi?id=836477
409nss-tools 27 October 2017 PK12UTIL(1)