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] [-d [sql:]directory]
11                [-h tokenname] [-P dbprefix] [-r] [-v]
12                [-k slotPasswordFile|-K slotPassword]
13                [-w p12filePasswordFile|-W p12filePassword]
14

STATUS

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

DESCRIPTION

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

OPTIONS AND ARGUMENTS

26       Options
27
28       -i p12file
29           Import keys and certificates from a PKCS #12 file into a security
30           database.
31
32       -l p12file
33           List the keys and certificates in PKCS #12 file.
34
35       -o p12file
36           Export keys and certificates from the security database to a PKCS
37           #12 file.
38
39       Arguments
40
41       -c keyCipher
42           Specify the key encryption algorithm.
43
44       -C certCipher
45           Specify the certiticate encryption algorithm.
46
47       -d [sql:]directory
48           Specify the database directory into which to import to or export
49           from certificates and keys.
50
51           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
57       -h tokenname
58           Specify the name of the token to import into or export from.
59
60       -k slotPasswordFile
61           Specify the text file containing the slot's password.
62
63       -K slotPassword
64           Specify the slot's password.
65
66       -m | --key-len keyLength
67           Specify the desired length of the symmetric key to be used to
68           encrypt the private key.
69
70       -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
74       -n certname
75           Specify the nickname of the cert and private key to export.
76
77           The nickname can also be a PKCS #11 URI. For example, if you have a
78           certificate named "my-server-cert" on the internal certificate
79           store, it can be unambiguously specified as
80           "pkcs11:token=NSS%20Certificate%20DB;object=my-server-cert". For
81           details about the format, see RFC 7512.
82
83       -P prefix
84           Specify the prefix used on the certificate and key databases. This
85           option is provided as a special case. Changing the names of the
86           certificate and key databases is not recommended.
87
88       -r
89           Dumps all of the data in raw (binary) form. This must be saved as a
90           DER file. The default is to return information in a pretty-print
91           ASCII format, which displays the information about the certificates
92           and public keys in the p12 file.
93
94       -v
95           Enable debug logging when importing.
96
97       -w p12filePasswordFile
98           Specify the text file containing the pkcs #12 file password.
99
100       -W p12filePassword
101           Specify the pkcs #12 file password.
102

RETURN CODES

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

EXAMPLES

157       Importing Keys and Certificates
158
159       The most basic usage of pk12util for importing a certificate or key is
160       the PKCS #12 input file (-i) and some way to specify the security
161       database being accessed (either -d for a directory or -h for a token).
162
163       pk12util -i p12File [-h tokenname] [-v] [-d [sql:]directory] [-P
164       dbprefix] [-k slotPasswordFile|-K slotPassword] [-w
165       p12filePasswordFile|-W p12filePassword]
166
167       For example:
168
169           # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb
170
171           Enter a password which will be used to encrypt your keys.
172           The password should be at least 8 characters long,
173           and should contain at least one non-alphabetic character.
174
175           Enter new password:
176           Re-enter password:
177           Enter password for PKCS12 file:
178           pk12util: PKCS12 IMPORT SUCCESSFUL
179
180       Exporting Keys and Certificates
181
182       Using the pk12util command to export certificates and keys requires
183       both the name of the certificate to extract from the database (-n) and
184       the PKCS #12-formatted output file to write to. There are optional
185       parameters that can be used to encrypt the file to protect the
186       certificate material.
187
188       pk12util -o p12File -n certname [-c keyCipher] [-C certCipher]
189       [-m|--key_len keyLen] [-n|--cert_key_len certKeyLen] [-d
190       [sql:]directory] [-P dbprefix] [-k slotPasswordFile|-K slotPassword]
191       [-w p12filePasswordFile|-W p12filePassword]
192
193       For example:
194
195           # pk12util -o certs.p12 -n Server-Cert -d sql:/home/my/sharednssdb
196           Enter password for PKCS12 file:
197           Re-enter password:
198
199       Listing Keys and Certificates
200
201       The information in a .p12 file are not human-readable. The certificates
202       and keys in the file can be printed (listed) in a human-readable
203       pretty-print format that shows information for every certificate and
204       any public keys in the .p12 file.
205
206       pk12util -l p12File [-h tokenname] [-r] [-d [sql:]directory] [-P
207       dbprefix] [-k slotPasswordFile|-K slotPassword] [-w
208       p12filePasswordFile|-W p12filePassword]
209
210       For example, this prints the default ASCII output:
211
212           # pk12util -l certs.p12
213
214           Enter password for PKCS12 file:
215           Key(shrouded):
216               Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
217
218               Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
219                   Parameters:
220                       Salt:
221                           45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
222                       Iteration Count: 1 (0x1)
223           Certificate:
224               Data:
225                   Version: 3 (0x2)
226                   Serial Number: 13 (0xd)
227                   Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
228                   Issuer: "E=personal-freemail@thawte.com,CN=Thawte Personal Freemail C
229                       A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T
230                       own,ST=Western Cape,C=ZA"
231
232
233       Alternatively, the -r prints the certificates and then exports them
234       into separate DER binary files. This allows the certificates to be fed
235       to another application that supports .p12 files. Each certificate is
236       written to a sequentially-number file, beginning with file0001.der and
237       continuing through file000N.der, incrementing the number for every
238       certificate:
239
240           pk12util -l test.p12 -r
241           Enter password for PKCS12 file:
242           Key(shrouded):
243               Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
244
245               Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
246                   Parameters:
247                       Salt:
248                           45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
249                       Iteration Count: 1 (0x1)
250           Certificate    Friendly Name: Thawte Personal Freemail Issuing CA - Thawte Consulting
251
252           Certificate    Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
253
254

PASSWORD ENCRYPTION

256       PKCS #12 provides for not only the protection of the private keys but
257       also the certificate and meta-data associated with the keys.
258       Password-based encryption is used to protect private keys on export to
259       a PKCS #12 file and, optionally, the associated certificates. If no
260       algorithm is specified, the tool defaults to using PKCS #12 SHA-1 and
261       3-key triple DES for private key encryption. When not in FIPS mode,
262       PKCS #12 SHA-1 and 40-bit RC4 is used for certificate encryption. When
263       in FIPS mode, there is no certificate encryption. If certificate
264       encryption is not wanted, specify "NONE" as the argument of the -C
265       option.
266
267       The private key is always protected with strong encryption by default.
268
269       Several types of ciphers are supported.
270
271       PKCS #5 password-based encryption
272
273           ·   PBES2 with AES-CBC-Pad as underlying encryption scheme
274               ("AES-128-CBC", "AES-192-CBC", and "AES-256-CBC")
275
276       PKCS #12 password-based encryption
277
278           ·   SHA-1 and 128-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
279               RC4" or "RC4")
280
281           ·   SHA-1 and 40-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
282               RC4") (used by default for certificate encryption in non-FIPS
283               mode)
284
285           ·   SHA-1 and 3-key triple-DES ("PKCS #12 V2 PBE With SHA-1 And
286               3KEY Triple DES-CBC" or "DES-EDE3-CBC")
287
288           ·   SHA-1 and 128-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit
289               RC2 CBC" or "RC2-CBC")
290
291           ·   SHA-1 and 40-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit
292               RC2 CBC")
293
294       With PKCS #12, the crypto provider may be the soft token module or an
295       external hardware module. If the cryptographic module does not support
296       the requested algorithm, then the next best fit will be selected
297       (usually the default). If no suitable replacement for the desired
298       algorithm can be found, the tool returns the error no security module
299       can perform the requested operation.
300

NSS DATABASE TYPES

302       NSS originally used BerkeleyDB databases to store security information.
303       The last versions of these legacy databases are:
304
305       ·   cert8.db for certificates
306
307       ·   key3.db for keys
308
309       ·   secmod.db for PKCS #11 module information
310
311       BerkeleyDB has performance limitations, though, which prevent it from
312       being easily used by multiple applications simultaneously. NSS has some
313       flexibility that allows applications to use their own, independent
314       database engine while keeping a shared database and working around the
315       access issues. Still, NSS requires more flexibility to provide a truly
316       shared security database.
317
318       In 2009, NSS introduced a new set of databases that are SQLite
319       databases rather than BerkleyDB. These new databases provide more
320       accessibility and performance:
321
322       ·   cert9.db for certificates
323
324       ·   key4.db for keys
325
326       ·   pkcs11.txt, which is listing of all of the PKCS #11 modules
327           contained in a new subdirectory in the security databases directory
328
329       Because the SQLite databases are designed to be shared, these are the
330       shared database type. The shared database type is preferred; the legacy
331       format is included for backward compatibility.
332
333       By default, the tools (certutil, pk12util, modutil) assume that the
334       given security databases follow the more common legacy type. Using the
335       SQLite databases must be manually specified by using the sql: prefix
336       with the given security directory. For example:
337
338           # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb
339
340       To set the shared database type as the default type for the tools, set
341       the NSS_DEFAULT_DB_TYPE environment variable to sql:
342
343           export NSS_DEFAULT_DB_TYPE="sql"
344
345       This line can be set added to the ~/.bashrc file to make the change
346       permanent.
347
348       Most applications do not use the shared database by default, but they
349       can be configured to use them. For example, this how-to article covers
350       how to configure Firefox and Thunderbird to use the new shared NSS
351       databases:
352
353       ·   https://wiki.mozilla.org/NSS_Shared_DB_Howto
354
355       For an engineering draft on the changes in the shared NSS databases,
356       see the NSS project wiki:
357
358       ·   https://wiki.mozilla.org/NSS_Shared_DB
359

COMPATIBILITY NOTES

361       The exporting behavior of pk12util has changed over time, while
362       importing files exported with older versions of NSS is still supported.
363
364       Until the 3.30 release, pk12util used the UTF-16 encoding for the PKCS
365       #5 password-based encryption schemes, while the recommendation is to
366       encode passwords in UTF-8 if the used encryption scheme is defined
367       outside of the PKCS #12 standard.
368
369       Until the 3.31 release, even when "AES-128-CBC" or "AES-192-CBC" is
370       given from the command line, pk12util always used 256-bit AES as the
371       underlying encryption scheme.
372
373       For historical reasons, pk12util accepts password-based encryption
374       schemes not listed in this document. However, those schemes are not
375       officially supported and may have issues in interoperability with other
376       tools.
377

SEE ALSO

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

ADDITIONAL RESOURCES

391       For information about NSS and other tools related to NSS (like JSS),
392       check out the NSS project wiki at
393       http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates
394       directly to NSS code changes and releases.
395
396       Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
397
398       IRC: Freenode at #dogtag-pki
399

AUTHORS

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

LICENSE

408       Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL
409       was not distributed with this file, You can obtain one at
410       http://mozilla.org/MPL/2.0/.
411

NOTES

413        1. Mozilla NSS bug 836477
414           https://bugzilla.mozilla.org/show_bug.cgi?id=836477
415
416
417
418nss-tools                       5 October 2017                     PK12UTIL(1)
Impressum