STATUS

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

Description

The Certificate Database Tool, certutil, is a command-line utility that can create and modify certificate and key databases. It can specifically list, generate, modify, or delete certificates, create or change the password, generate new public and private key pairs, display the contents of the key database, or delete key pairs within the key database.

Certificate issuance, part of the key and certificate management process, requires that keys and certificates be created in the key database. This document discusses certificate and key database management. For information on the security module database management, see the modutil manpage.

Command Options and Arguments

Running certutil always requires one and only one command option to specify the type of certificate operation. Each command option may take zero or more arguments. The command option -H will list all the command options and their relevant arguments.

Command Options

Arguments

Arguments modify a command option and are usually lower case, numbers, or symbols.

Usage and Examples

Most of the command options in the examples listed here have more arguments available. The arguments included in these examples are the most common ones or are used to illustrate a specific scenario. Use the -H option to show the complete list of arguments for each command option.

Creating New Security Databases

Certificates, keys, and security modules related to managing certificates are stored in three related databases:

These databases must be created before certificates or keys can be generated.

certutil -N -d [sql:]directory

Creating a Certificate Request

A certificate request contains most or all of the information that is used to generate the final certificate. This request is submitted separately to a certificate authority and is then approved by some mechanism (automatically or by human review). Once the request is approved, then the certificate is generated.

$ certutil -R -k key-type-or-id [-q pqgfile|curve-name] -g key-size -s subject [-h tokenname] -d [sql:]directory [-p phone] [-o output-file] [-a]

The -R command options requires four arguments:

The new certificate request can be output in ASCII format (-a) or can be written to a specified file (-o).

For example:

$ certutil -R -k rsa -g 1024 -s "CN=John Smith,O=Example Corp,L=Mountain View,ST=California,C=US" -d sql:$HOME/nssdb -p 650-555-0123 -a -o cert.cer

Generating key.  This may take a few moments...

Creating a Certificate

A valid certificate must be issued by a trusted CA. This can be done by specifying a CA certificate (-c) that is stored in the certificate database. If a CA key pair is not available, you can create a self-signed certificate using the -x argument with the -S command option.

$ certutil -S -k rsa|dsa|ec -n certname -s subject [-c issuer |-x] -t trustargs -d [sql:]directory [-m serial-number] [-v valid-months] [-w offset-months] [-p phone] [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names] [--extAIA] [--extSIA] [--extCP] [--extPM] [--extPC] [--extIA] [--extSKID]

The series of numbers and --ext* options set certificate extensions that can be added to the certificate when it is generated by the CA. Interactive prompts will result.

For example, this creates a self-signed certificate:

$ certutil -S -s "CN=Example CA" -n my-ca-cert -x -t "C,C,C" -1 -2 -5 -m 3650

The interative prompts for key usage and whether any extensions are critical and responses have been ommitted for brevity.

From there, new certificates can reference the self-signed certificate:

$ certutil -S -s "CN=My Server Cert" -n my-server-cert -c "my-ca-cert" -t "u,u,u" -1 -5 -6 -8 -m 730

Generating a Certificate from a Certificate Request

When a certificate request is created, a certificate can be generated by using the request and then referencing a certificate authority signing certificate (the issuer specified in the -c argument). The issuing certificate must be in the certificate database in the specified directory.

certutil -C -c issuer -i cert-request-file -o output-file [-m serial-number] [-v valid-months] [-w offset-months] -d [sql:]directory [-1] [-2] [-3] [-4] [-5 keyword] [-6 keyword] [-7 emailAddress] [-8 dns-names]

For example:

$ certutil -C -c "my-ca-cert" -i /home/certs/cert.req -o cert.cer -m 010 -v 12 -w 1 -d sql:$HOME/nssdb -1 nonRepudiation,dataEncipherment -5 sslClient -6 clientAuth -7 jsmith@example.com

Listing Certificates

The -L command option lists all of the certificates listed in the certificate database. The path to the directory (-d) is required.

$ certutil -L -d sql:/home/my/sharednssdb

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

CA Administrator of Instance pki-ca1's Example Domain ID     u,u,u
TPS Administrator's Example Domain ID                        u,u,u
Google Internet Authority                                    ,,   
Certificate Authority - Example Domain                       CT,C,C

Using additional arguments with -L can return and print the information for a single, specific certificate. For example, the -n argument passes the certificate name, while the -a argument prints the certificate in ASCII format:

$ certutil -L -d sql:$HOME/nssdb -a -n my-ca-cert
-----BEGIN CERTIFICATE-----
MIIB1DCCAT2gAwIBAgICDkIwDQYJKoZIhvcNAQEFBQAwFTETMBEGA1UEAxMKRXhh
bXBsZSBDQTAeFw0xMzAzMTMxOTEwMjlaFw0xMzA2MTMxOTEwMjlaMBUxEzARBgNV
BAMTCkV4YW1wbGUgQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJ4Kzqvz
JyBVgFqDXRYSyTBNw1DrxUU/3GvWA/ngjAwHEv0Cul/6sO/gsCvnABHiH6unns6x
XRzPORlC2WY3gkk7vmlsLvYpyecNazAi/NAwVnU/66HOsaoVFWE+gBQo99UrN2yk
0BiK/GMFlLm5dXQROgA9ZKKyFdI0LIXtf6SbAgMBAAGjMzAxMBEGCWCGSAGG+EIB
AQQEAwIHADAMBgNVHRMEBTADAQH/MA4GA1UdDwEB/wQEAwICBDANBgkqhkiG9w0B
AQUFAAOBgQA6chkzkACN281d1jKMrc+RHG2UMaQyxiteaLVZO+Ro1nnRUvseDf09
XKYFwPMJjWCihVku6bw/ihZfuMHhxK22Nue6inNQ6eDu7WmrqL8z3iUrQwxs+WiF
ob2rb8XRVVJkzXdXxlk4uo3UtNvw8sAz7sWD71qxKaIHU5q49zijfg==
-----END CERTIFICATE-----

For a human-readable display

$ certutil -L -d sql:$HOME/nssdb -n my-ca-cert
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 3650 (0xe42)
        Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
        Issuer: "CN=Example CA"
        Validity:
            Not Before: Wed Mar 13 19:10:29 2013
            Not After : Thu Jun 13 19:10:29 2013
        Subject: "CN=Example CA"
        Subject Public Key Info:
            Public Key Algorithm: PKCS #1 RSA Encryption
            RSA Public Key:
                Modulus:
                    9e:0a:ce:ab:f3:27:20:55:80:5a:83:5d:16:12:c9:30:
                    4d:c3:50:eb:c5:45:3f:dc:6b:d6:03:f9:e0:8c:0c:07:
                    12:fd:02:ba:5f:fa:b0:ef:e0:b0:2b:e7:00:11:e2:1f:
                    ab:a7:9e:ce:b1:5d:1c:cf:39:19:42:d9:66:37:82:49:
                    3b:be:69:6c:2e:f6:29:c9:e7:0d:6b:30:22:fc:d0:30:
                    56:75:3f:eb:a1:ce:b1:aa:15:15:61:3e:80:14:28:f7:
                    d5:2b:37:6c:a4:d0:18:8a:fc:63:05:94:b9:b9:75:74:
                    11:3a:00:3d:64:a2:b2:15:d2:34:2c:85:ed:7f:a4:9b
                Exponent: 65537 (0x10001)
        Signed Extensions:
            Name: Certificate Type
            Data: none

            Name: Certificate Basic Constraints
            Data: Is a CA with no maximum path length.

            Name: Certificate Key Usage
            Critical: True
            Usages: Certificate Signing

    Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
    Signature:
        3a:72:19:33:90:00:8d:db:cd:5d:d6:32:8c:ad:cf:91:
        1c:6d:94:31:a4:32:c6:2b:5e:68:b5:59:3b:e4:68:d6:
        79:d1:52:fb:1e:0d:fd:3d:5c:a6:05:c0:f3:09:8d:60:
        a2:85:59:2e:e9:bc:3f:8a:16:5f:b8:c1:e1:c4:ad:b6:
        36:e7:ba:8a:73:50:e9:e0:ee:ed:69:ab:a8:bf:33:de:
        25:2b:43:0c:6c:f9:68:85:a1:bd:ab:6f:c5:d1:55:52:
        64:cd:77:57:c6:59:38:ba:8d:d4:b4:db:f0:f2:c0:33:
        ee:c5:83:ef:5a:b1:29:a2:07:53:9a:b8:f7:38:a3:7e
    Fingerprint (MD5):
        86:D8:A5:8B:8A:26:BE:9E:17:A8:7B:66:10:6B:27:80
    Fingerprint (SHA1):
        48:78:09:EF:C5:D4:0C:BD:D2:64:45:59:EB:03:13:15:F7:A9:D6:F7

    Certificate Trust Flags:
        SSL Flags:
            Valid CA
            Trusted CA
            User
        Email Flags:
            Valid CA
            Trusted CA
            User
        Object Signing Flags:
            Valid CA
            Trusted CA
            User

Listing Keys

Keys are the original material used to encrypt certificate data. The keys generated for certificates are stored separately, in the key database.

To list all keys in the database, use the -K command option and the (required) -d argument to give the path to the directory.

$ certutil -K -d sql:$HOME/nssdb
certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services                  "
< 0> rsa      455a6673bde9375c2887ec8bf8016b3f9f35861d   Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID
< 1> rsa      40defeeb522ade11090eacebaaf1196a172127df   Example Domain Administrator Cert
< 2> rsa      1d0b06f44f6c03842f7d4f4a1dc78b3bcd1b85a5   John Smith user cert

There are ways to narrow the keys listed in the search results:

Listing Security Modules

The devices that can be used to store certificates -- both internal databases and external devices like smart cards -- are recognized and used by loading security modules. The -U command option lists all of the security modules listed in the secmod.db database. The path to the directory (-d) is required.

$ certutil -U -d sql:/home/my/sharednssdb

    slot: NSS User Private Key and Certificate Services                  
   token: NSS Certificate DB

    slot: NSS Internal Cryptographic Services                            
   token: NSS Generic Crypto Services

Adding Certificates to the Database

Existing certificates or certificate requests can be added manually to the certificate database, even if they were generated elsewhere. This uses the -A command option.

certutil -A -n certname -t trustargs -d [sql:]directory [-a] [-i input-file]

For example:

$ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d sql:/home/my/sharednssdb -i /home/example-certs/cert.cer

A related command option, -E, is used specifically to add email certificates to the certificate database. The -E command has the same arguments as the -A command. The trust arguments for certificates have the format SSL,S/MIME,Code-signing, so the middle trust settings relate most to email certificates (though the others can be set). For example:

$ certutil -E -n "CN=John Smith Email Cert" -t ",Pu," -d sql:/home/my/sharednssdb -i /home/example-certs/email.cer

Deleting Certificates to the Database

Certificates can be deleted from a database using the -D option. The only required options are to give the security database directory and to identify the certificate nickname.

certutil -D -d [sql:]directory -n "nickname"

For example:

$ certutil -D -d sql:/home/my/sharednssdb -n "my-ssl-cert"

Validating Certificates

A certificate contains an expiration date in itself, and expired certificates are easily rejected. However, certificates can also be revoked before they hit their expiration date. Checking whether a certificate has been revoked requires validating the certificate. Validation can also be used to ensure that the certificate is only used for the purposes it was initially issued for. Validation is carried out by the -V command option.

certutil -V -n certificate-name [-b time] [-e] [-u cert-usage] -d [sql:]directory

For example, to validate an email certificate:

$ certutil -V -n "John Smith's Email Cert" -e -u S,R -d sql:/home/my/sharednssdb

Modifying Certificate Trust Settings

The trust settings (which relate to the operations that a certificate is allowed to be used for) can be changed after a certificate is created or added to the database. This is especially useful for CA certificates, but it can be performed for any type of certificate.

certutil -M -n certificate-name -t trust-args -d [sql:]directory

For example:

$ certutil -M -n "My CA Certificate" -d sql:/home/my/sharednssdb -t "CTu,CTu,CTu"

Printing the Certificate Chain

Certificates can be issued in chains because every certificate authority itself has a certificate; when a CA issues a certificate, it essentially stamps that certificate with its own fingerprint. The -O prints the full chain of a certificate, going from the initial CA (the root CA) through ever intermediary CA to the actual certificate. For example, for an email certificate with two CAs in the chain:

$ certutil -d sql:/home/my/sharednssdb -O -n "jsmith@example.com"
"Builtin Object Token:Thawte Personal Freemail CA" [E=personal-freemail@thawte.com,CN=Thawte Personal Freemail CA,OU=Certification Services Division,O=Thawte Consulting,L=Cape Town,ST=Western Cape,C=ZA]

  "Thawte Personal Freemail Issuing CA - Thawte Consulting" [CN=Thawte Personal Freemail Issuing CA,O=Thawte Consulting (Pty) Ltd.,C=ZA]

    "(null)" [E=jsmith@example.com,CN=Thawte Freemail Member]

Resetting a Token

The device which stores certificates -- both external hardware devices and internal software databases -- can be blanked and reused. This operation is performed on the device which stores the data, not directly on the security databases, so the location must be referenced through the token name (-h) as well as any directory path. If there is no external token used, the default value is internal.

certutil -T -d [sql:]directory -h token-name -0 security-officer-password

Many networks have dedicated personnel who handle changes to security tokens (the security officer). This person must supply the password to access the specified token. For example:

$ certutil -T -d sql:/home/my/sharednssdb -h nethsm -0 secret

Upgrading or Merging the Security Databases

Many networks or applications may be using older BerkeleyDB versions of the certificate database (cert8.db). Databases can be upgraded to the new SQLite version of the database (cert9.db) using the --upgrade-merge command option or existing databases can be merged with the new cert9.db databases using the ---merge command.

The --upgrade-merge command must give information about the original database and then use the standard arguments (like -d) to give the information about the new databases. The command also requires information that the tool uses for the process to upgrade and write over the original database.

certutil --upgrade-merge -d [sql:]directory [-P dbprefix] --source-dir directory --source-prefix dbprefix --upgrade-id id --upgrade-token-name name [-@ password-file]

For example:

$ certutil --upgrade-merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ --source-prefix serverapp- --upgrade-id 1 --upgrade-token-name internal

The --merge command only requires information about the location of the original database; since it doesn't change the format of the database, it can write over information without performing interim step.

certutil --merge -d [sql:]directory [-P dbprefix] --source-dir directory --source-prefix dbprefix [-@ password-file]

For example:

$ certutil --merge -d sql:/home/my/sharednssdb --source-dir /opt/my-app/alias/ --source-prefix serverapp-

Running certutil Commands from a Batch File

A series of commands can be run sequentially from a text file with the -B command option. The only argument for this specifies the input file.

$ certutil -B -i /path/to/batch-file

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 BerkeleyDB. 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 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:

$ certutil -L -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:

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

See Also

pk12util (1)

modutil (1)

certutil has arguments or operations that use features defined in several IETF RFCs.

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