.. _mozilla_projects_nss_reference_nss_tools_:_pk12util:

NSS tools : pk12util
====================

.. container::

   NSS tools : pk12util

   Name

   | pk12util — Export and import keys and certificate to or from a PKCS #12
   | file and the NSS database

   Synopsis

   pk12util [-i p12File|-l p12File|-o p12File] [-d [sql:]directory] [-h tokenname] [-P dbprefix]
   [-r] [-v] [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword]

   Description

   | The PKCS #12 utility, pk12util, enables sharing certificates among any
   | server that supports PKCS#12. The tool can import certificates and keys
   | from PKCS#12 files into security databases, export certificates, and list
   | certificates and keys.

   Options and Arguments

   Options

   -i p12file

   | Import keys and certificates from a PKCS#12 file into a security
   | database.

   -l p12file

   List the keys and certificates in PKCS#12 file.

   -o p12file

   | Export keys and certificates from the security database to a
   | PKCS#12 file.

   Arguments

   -c keyCipher

   Specify the key encryption algorithm.

   -C certCipher

   Specify the key cert (overall package) encryption algorithm.

   | 
   | -d [sql:]directory

   | Specify the database directory into which to import to or export
   | from certificates and keys.

   | pk12util supports two types of databases: the legacy security
   | databases (cert8.db, key3.db, and secmod.db) and new SQLite
   | databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql:
   | is not used, then the tool assumes that the given databases are in
   | the old format.

   -h tokenname

   Specify the name of the token to import into or export from.

   -k slotPasswordFile

   Specify the text file containing the slot's password.

   -K slotPassword

   Specify the slot's password.

   -m \| --key-len keyLength

   | Specify the desired length of the symmetric key to be used to
   | encrypt the private key.

   -n \| --cert-key-len certKeyLength

   | Specify the desired length of the symmetric key to be used to
   | encrypt the certificates and other meta-data.

   -n certname

   Specify the nickname of the cert and private key to export.

   -P prefix

   | Specify the prefix used on the certificate and key databases. This
   | option is provided as a special case. Changing the names of the
   | certificate and key databases is not recommended.

   -r

   | Dumps all of the data in raw (binary) form. This must be saved as
   | a DER file. The default is to return information in a pretty-print
   | ASCII format, which displays the information about the
   | certificates and public keys in the p12 file.

   -v

   Enable debug logging when importing.

   -w p12filePasswordFile

   Specify the text file containing the pkcs #12 file password.

   -W p12filePassword

   Specify the pkcs #12 file password.

   Return Codes

   o 0 - No error

   o 1 - User Cancelled

   o 2 - Usage error

   o 6 - NLS init error

   o 8 - Certificate DB open error

   o 9 - Key DB open error

   o 10 - File initialization error

   o 11 - Unicode conversion error

   o 12 - Temporary file creation error

   o 13 - PKCS11 get slot error

   o 14 - PKCS12 decoder start error

   o 15 - error read from import file

   o 16 - pkcs12 decode error

   o 17 - pkcs12 decoder verify error

   o 18 - pkcs12 decoder validate bags error

   o 19 - pkcs12 decoder import bags error

   o 20 - key db conversion version 3 to version 2 error

   o 21 - cert db conversion version 7 to version 5 error

   o 22 - cert and key dbs patch error

   o 23 - get default cert db error

   o 24 - find cert by nickname error

   o 25 - create export context error

   o 26 - PKCS12 add password itegrity error

   o 27 - cert and key Safes creation error

   o 28 - PKCS12 add cert and key error

   o 29 - PKCS12 encode error

   Examples

   Importing Keys and Certificates

   | The most basic usage of pk12util for importing a certificate or key is the
   | PKCS#12 input file (-i) and some way to specify the security database
   | being accessed (either -d for a directory or -h for a token).

   pk12util -i p12File [-h tokenname] [-v] [-d [sql:]directory] [-P dbprefix] [-k
   slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword]

   For example:

   # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb

   | Enter a password which will be used to encrypt your keys.
   | The password should be at least 8 characters long,
   | and should contain at least one non-alphabetic character.

   | Enter new password:
   | Re-enter password:
   | Enter password for PKCS12 file:
   | pk12util: PKCS12 IMPORT SUCCESSFUL

   Exporting Keys and Certificates

   | Using the pk12util command to export certificates and keys requires both
   | the name of the certificate to extract from the database (-n) and the
   | PKCS#12-formatted output file to write to. There are optional parameters
   | that can be used to encrypt the file to protect the certificate material.

   pk12util -o p12File -n certname [-c keyCipher] [-C certCipher] [-m|--key_len keyLen]
   [-n|--cert_key_len certKeyLen] [-d [sql:]directory] [-P dbprefix] [-k slotPasswordFile|-K
   slotPassword] [-w p12filePasswordFile|-W p12filePassword]

   For example:

   | # pk12util -o certs.p12 -n Server-Cert -d sql:/home/my/sharednssdb
   | Enter password for PKCS12 file:
   | Re-enter password:

   Listing Keys and Certificates

   | The information in a .p12 file are not human-readable. The certificates
   | and keys in the file can be printed (listed) in a human-readable
   | pretty-print format that shows information for every certificate and any
   | public keys in the .p12 file.

   pk12util -l p12File [-h tokenname] [-r] [-d [sql:]directory] [-P dbprefix] [-k
   slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword]

   For example, this prints the default ASCII output:

   # pk12util -l certs.p12

   | Enter password for PKCS12 file:
   | Key(shrouded):
   | Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID

   | Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
   | Parameters:
   | Salt:
   | 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
   | Iteration Count: 1 (0x1)
   | Certificate:
   | Data:
   | Version: 3 (0x2)
   | Serial Number: 13 (0xd)
   | Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
   | Issuer: "E=personal-freemail@thawte.com,CN=Thawte Personal Freemail C
   | A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T
   | own,ST=Western Cape,C=ZA"

   | Alternatively, the -r prints the certificates and then exports them into
   | separate DER binary files. This allows the certificates to be fed to
   | another application that supports .p12 files. Each certificate is written
   | to a sequentially-number file, beginning with file0001.der and continuing
   | through file000N.der, incrementing the number for every certificate:

   | # pk12util -l test.p12 -r
   | Enter password for PKCS12 file:
   | Key(shrouded):
   | Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID

   | Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC
   | Parameters:
   | Salt:
   | 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
   | Iteration Count: 1 (0x1)
   | Certificate Friendly Name: Thawte Personal Freemail Issuing CA - Thawte Consulting

   Certificate Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID

   Password Encryption

   | PKCS#12 provides for not only the protection of the private keys but also
   | the certificate and meta-data associated with the keys. Password-based
   | encryption is used to protect private keys on export to a PKCS#12 file
   | and, optionally, the entire package. If no algorithm is specified, the
   | tool defaults to using PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc for
   | private key encryption. PKCS12 V2 PBE with SHA1 and 40 Bit RC4 is the
   | default for the overall package encryption when not in FIPS mode. When in
   | FIPS mode, there is no package encryption.

   The private key is always protected with strong encryption by default.

   Several types of ciphers are supported.

   Symmetric CBC ciphers for PKCS#5 V2

   o DES-CBC

   o RC2-CBC

   o RC5-CBCPad

   o DES-EDE3-CBC (the default for key encryption)

   o AES-128-CBC

   o AES-192-CBC

   o AES-256-CBC

   o CAMELLIA-128-CBC

   o CAMELLIA-192-CBC

   o CAMELLIA-256-CBC

   PKCS#12 PBE ciphers

   o PKCS #12 PBE with Sha1 and 128 Bit RC4

   o PKCS #12 PBE with Sha1 and 40 Bit RC4

   o PKCS #12 PBE with Sha1 and Triple DES CBC

   o PKCS #12 PBE with Sha1 and 128 Bit RC2 CBC

   o PKCS #12 PBE with Sha1 and 40 Bit RC2 CBC

   o PKCS12 V2 PBE with SHA1 and 128 Bit RC4

   | o PKCS12 V2 PBE with SHA1 and 40 Bit RC4 (the default for
   | non-FIPS mode)

   o PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc

   o PKCS12 V2 PBE with SHA1 and 2KEY Triple DES-cbc

   o PKCS12 V2 PBE with SHA1 and 128 Bit RC2 CBC

   o PKCS12 V2 PBE with SHA1 and 40 Bit RC2 CBC

   PKCS#5 PBE ciphers

   o PKCS #5 Password Based Encryption with MD2 and DES CBC

   o PKCS #5 Password Based Encryption with MD5 and DES CBC

   o PKCS #5 Password Based Encryption with SHA1 and DES CBC

   | With PKCS#12, the crypto provider may be the soft token module or an
   | external hardware module. If the cryptographic module does not support the
   | requested algorithm, then the next best fit will be selected (usually the
   | default). If no suitable replacement for the desired algorithm can be
   | found, the tool returns the error no security module can perform the
   | requested operation.

   NSS Database Types

   | NSS originally used BerkeleyDB databases to store security information.
   | The last versions of these legacy databases are:

   o cert8.db for certificates

   o key3.db for keys

   o secmod.db for PKCS #11 module information

   | BerkeleyDB has performance limitations, though, which prevent it from
   | being easily used by multiple applications simultaneously. NSS has some
   | flexibility that allows applications to use their own, independent
   | database engine while keeping a shared database and working around the
   | access issues. Still, NSS requires more flexibility to provide a truly
   | shared security database.

   | In 2009, NSS introduced a new set of databases that are SQLite databases
   | rather than BerkleyDB. These new databases provide more accessibility and
   | performance:

   o cert9.db for certificates

   o key4.db for keys

   | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained
   | in a new subdirectory in the security databases directory

   | Because the SQLite databases are designed to be shared, these are the
   | shared database type. The shared database type is preferred; the legacy
   | format is included for backward compatibility.

   | By default, the tools (certutil, pk12util, modutil) assume that the given
   | security databases follow the more common legacy type. Using the SQLite
   | databases must be manually specified by using the sql: prefix with the
   | given security directory. For example:

   # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb

   | To set the shared database type as the default type for the tools, set the
   | NSS_DEFAULT_DB_TYPE environment variable to sql:

   export NSS_DEFAULT_DB_TYPE="sql"

   | This line can be set added to the ~/.bashrc file to make the change
   | permanent.

   | Most applications do not use the shared database by default, but they can
   | be configured to use them. For example, this how-to article covers how to
   | configure Firefox and Thunderbird to use the new shared NSS databases:

   o https://wiki.mozilla.org/NSS_Shared_DB_Howto

   | For an engineering draft on the changes in the shared NSS databases, see
   | the NSS project wiki:

   o https://wiki.mozilla.org/NSS_Shared_DB

   See Also

   certutil (1)

   modutil (1)

   | The NSS wiki has information on the new database design and how to
   | configure applications to use it.

   o https://wiki.mozilla.org/NSS_Shared_DB_Howto

   o https://wiki.mozilla.org/NSS_Shared_DB

   Additional Resources

   | For information about NSS and other tools related to NSS (like JSS), check
   | out the NSS project wiki at
   | [1]http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates
   | directly to NSS code changes and releases.

   Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto

   IRC: Freenode at #dogtag-pki

   Authors

   | The NSS tools were written and maintained by developers with Netscape, Red
   | Hat, Sun, Oracle, Mozilla, and Google.

   | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey
   | <dlackey@redhat.com>.

   License

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

   References

   | 1. Mozilla NSS bug 836477
   | https://bugzilla.mozilla.org/show_bug.cgi?id=836477