pk12util - Man Page

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] [-c keyCipher] [-C certCipher] [-d directory] [-h tokenname] [-m | --key-len keyLength] [-M hashAlg] [-n certname] [-P dbprefix] [-r] [-v] [-I] [--cert-key-len certKeyLength] [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword]

Status

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

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 certiticate encryption algorithm​.

-d directory

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

pk12util supports SQLite databases (cert9​.db, key4​.db, and pkcs11​.txt)​.

-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​.

-M hashAlg

Specify the hash algorithm used in the pkcs #12 mac​. If an hmac is specified, then the PKCS #12 mac is replaced by a PKCS #5 mac1 pbe​. This algorithm also specifies the HMAC used in the prf when using pkcs #5 v2​.

--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​.

The nickname can also be a PKCS #11 URI​. For example, if you have a certificate named "my-server-cert" on the internal certificate store, it can be unambiguously specified as "pkcs11:token=NSS%20Certificate%20DB;object=my-server-cert"​. For details about the format, see RFC 7512​.

-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​.

-I

Ignore integrity check results on importing and listing​.

-w p12filePasswordFile

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

-W p12filePassword

Specify the pkcs #12 file password​.

Return Codes

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 directory] [-P dbprefix] [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword]

For example:

# pk12util -i /tmp/cert-files/users​.p12 -d /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 directory] [-P dbprefix] [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword]

For example:

# pk12util -o certs​.p12 -n Server-Cert -d /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 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 associated certificates​. If no algorithm is specified, the tool defaults to using AES-256-CBC for private key encryption and AES-128-CBC for certificate encryption​. If certificate encryption is not wanted, specify "NONE" as the argument of the -C option​.

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

Several types of ciphers are supported​.

PKCS #5 password-based encryption
  • PBES2 with AES-CBC-Pad as underlying encryption scheme ("AES-128-CBC", "AES-192-CBC", and "AES-256-CBC")
  • PBES2 with CAMELLIA-CBC-Pad as underlying encryption scheme ("CAMELLIA-128-CBC", "CAMELLIA-192-CBC", and "CAMELLIA-256-CBC")
PKCS #12 password-based encryption
  • SHA-1 and 128-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit RC4" or "RC4")
  • SHA-1 and 40-bit RC4 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit RC4") (used by default for certificate encryption in non-FIPS mode)
  • SHA-1 and 3-key triple-DES ("PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC" or "DES-EDE3-CBC")
  • SHA-1 and 128-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 128 Bit RC2 CBC" or "RC2-CBC")
  • SHA-1 and 40-bit RC2 ("PKCS #12 V2 PBE With SHA-1 And 40 Bit RC2 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:

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:

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 use the SQLite type​.

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

Compatibility Notes

The exporting behavior of pk12util has changed over time, while importing files exported with older versions of NSS is still supported​.

Until the 3​.30 release, pk12util used the UTF-16 encoding for the PKCS #5 password-based encryption schemes, while the recommendation is to encode passwords in UTF-8 if the used encryption scheme is defined outside of the PKCS #12 standard​.

Until the 3​.31 release, even when "AES-128-CBC" or "AES-192-CBC" is given from the command line, pk12util always used 256-bit AES as the underlying encryption scheme​.

For historical reasons, pk12util accepts password-based encryption schemes not listed in this document​. However, those schemes are not officially supported and may have issues in interoperability with other tools​.

See Also

certutil (1)

modutil (1)

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

Additional Resources

For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at 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 http://mozilla​.org/MPL/2​.0/​.

Notes

1.

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

Referenced By

certutil(1), efikeygen(1), ipsec-pk12util(8), modutil(1), pesign(1).

27 August 2026 nss-tools NSS Security Tools