1PK12UTIL(1)                   NSS Security Tools                   PK12UTIL(1)
2
3
4

NAME

6       pk12util - Export and import keys and certificate to or from a PKCS #12
7       file and the NSS database
8

SYNOPSIS

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

STATUS

18       This documentation is still work in progress. Please contribute to the
19       initial review in Mozilla NSS bug 836477[1]
20

DESCRIPTION

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

OPTIONS AND ARGUMENTS

28       Options
29
30       -i p12file
31           Import keys and certificates from a PKCS #12 file into a security
32           database.
33
34       -l p12file
35           List the keys and certificates in PKCS #12 file.
36
37       -o p12file
38           Export keys and certificates from the security database to a PKCS
39           #12 file.
40
41       Arguments
42
43       -c keyCipher
44           Specify the key encryption algorithm.
45
46       -C certCipher
47           Specify the certiticate encryption algorithm.
48
49       -d directory
50           Specify the database directory into which to import to or export
51           from certificates and keys.
52
53           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
59       -h tokenname
60           Specify the name of the token to import into or export from.
61
62       -k slotPasswordFile
63           Specify the text file containing the slot's password.
64
65       -K slotPassword
66           Specify the slot's password.
67
68       -m | --key-len keyLength
69           Specify the desired length of the symmetric key to be used to
70           encrypt the private key.
71
72       -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
76       --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
80       -n certname
81           Specify the nickname of the cert and private key to export.
82
83           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
89       -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
94       -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
100       -v
101           Enable debug logging when importing.
102
103       -w p12filePasswordFile
104           Specify the text file containing the pkcs #12 file password.
105
106       -W p12filePassword
107           Specify the pkcs #12 file password.
108

RETURN CODES

110       •   0 - No error
111
112       •   1 - User Cancelled
113
114       •   2 - Usage error
115
116       •   6 - NLS init error
117
118       •   8 - Certificate DB open error
119
120       •   9 - Key DB open error
121
122       •   10 - File initialization error
123
124       •   11 - Unicode conversion error
125
126       •   12 - Temporary file creation error
127
128       •   13 - PKCS11 get slot error
129
130       •   14 - PKCS12 decoder start error
131
132       •   15 - error read from import file
133
134       •   16 - pkcs12 decode error
135
136       •   17 - pkcs12 decoder verify error
137
138       •   18 - pkcs12 decoder validate bags error
139
140       •   19 - pkcs12 decoder import bags error
141
142       •   20 - key db conversion version 3 to version 2 error
143
144       •   21 - cert db conversion version 7 to version 5 error
145
146       •   22 - cert and key dbs patch error
147
148       •   23 - get default cert db error
149
150       •   24 - find cert by nickname error
151
152       •   25 - create export context error
153
154       •   26 - PKCS12 add password itegrity error
155
156       •   27 - cert and key Safes creation error
157
158       •   28 - PKCS12 add cert and key error
159
160       •   29 - PKCS12 encode error
161

EXAMPLES

163       Importing Keys and Certificates
164
165       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
169       pk12util -i p12File [-h tokenname] [-v] [-d directory] [-P dbprefix]
170       [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W
171       p12filePassword]
172
173       For example:
174
175           # pk12util -i /tmp/cert-files/users.p12 -d /home/my/sharednssdb
176
177           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
181           Enter new password:
182           Re-enter password:
183           Enter password for PKCS12 file:
184           pk12util: PKCS12 IMPORT SUCCESSFUL
185
186       Exporting Keys and Certificates
187
188       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
194       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
199       For example:
200
201           # pk12util -o certs.p12 -n Server-Cert -d /home/my/sharednssdb
202           Enter password for PKCS12 file:
203           Re-enter password:
204
205       Listing Keys and Certificates
206
207       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
212       pk12util -l p12File [-h tokenname] [-r] [-d directory] [-P dbprefix]
213       [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W
214       p12filePassword]
215
216       For example, this prints the default ASCII output:
217
218           # pk12util -l certs.p12
219
220           Enter password for PKCS12 file:
221           Key(shrouded):
222               Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
223
224               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
238
239       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
246           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
251               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
258           Certificate    Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
259
260

PASSWORD ENCRYPTION

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
273       The private key is always protected with strong encryption by default.
274
275       Several types of ciphers are supported.
276
277       PKCS #5 password-based encryption
278
279           •   PBES2 with AES-CBC-Pad as underlying encryption scheme
280               ("AES-128-CBC", "AES-192-CBC", and "AES-256-CBC")
281
282       PKCS #12 password-based encryption
283
284           •   SHA-1 and 128-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
285               RC4" or "RC4")
286
287           •   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
291           •   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
294           •   SHA-1 and 128-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
295               RC2 CBC" or "RC2-CBC")
296
297           •   SHA-1 and 40-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
298               RC2 CBC")
299
300       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

NSS DATABASE TYPES

308       NSS originally used BerkeleyDB databases to store security information.
309       The last versions of these legacy databases are:
310
311       •   cert8.db for certificates
312
313       •   key3.db for keys
314
315       •   secmod.db for PKCS #11 module information
316
317       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
324       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
328       •   cert9.db for certificates
329
330       •   key4.db for keys
331
332       •   pkcs11.txt, which is listing of all of the PKCS #11 modules
333           contained in a new subdirectory in the security databases directory
334
335       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
339       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
344           # pk12util -i /tmp/cert-files/users.p12 -d dbm:/home/my/sharednssdb
345
346       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
349           export NSS_DEFAULT_DB_TYPE="dbm"
350
351       This line can be set added to the ~/.bashrc file to make the change
352       permanent.
353
354https://wiki.mozilla.org/NSS_Shared_DB_Howto
355
356       For an engineering draft on the changes in the shared NSS databases,
357       see the NSS project wiki:
358
359https://wiki.mozilla.org/NSS_Shared_DB
360

COMPATIBILITY NOTES

362       The exporting behavior of pk12util has changed over time, while
363       importing files exported with older versions of NSS is still supported.
364
365       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
370       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
374       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

SEE ALSO

380       certutil (1)
381
382       modutil (1)
383
384       The NSS wiki has information on the new database design and how to
385       configure applications to use it.
386
387https://wiki.mozilla.org/NSS_Shared_DB_Howto
388
389https://wiki.mozilla.org/NSS_Shared_DB
390

ADDITIONAL RESOURCES

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
397       Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
398
399       IRC: Freenode at #dogtag-pki
400

AUTHORS

402       The NSS tools were written and maintained by developers with Netscape,
403       Red Hat, Sun, Oracle, Mozilla, and Google.
404
405       Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
406       <dlackey@redhat.com>.
407

LICENSE

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

NOTES

414        1. Mozilla NSS bug 836477
415           https://bugzilla.mozilla.org/show_bug.cgi?id=836477
416
417
418
419nss-tools                         29 May 2021                      PK12UTIL(1)
Impressum