The Certificate Database Tool,
certutil
, is a command-line utility that can create and modify
cert8.db
and
key3.db
database files. It can also list, generate, modify, or delete certificates within the
cert8.db
file and 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
key3.db
file.
The key and certificate management process generally begins with creating keys in the key database, then generating and managing certificates in the certificate database. This document discusses certificate and key database management. For information security module database management, see the
modutil
manpages.
Running certutil always requires one (and only one) option to specify the type of certificate operation. Each option may take arguments, anywhere from none to multiple arguments. Run the command option and -H to see the arguments available for each command option.
Options
Options specify an action and are uppercase.
-d argument. Use the -k argument to specify explicitly whether to delete a DSA, RSA, or ECC key. If you don't use the -k argument, the option looks for an RSA key matching the specified nickname.
Use the -a argument to specify ASCII output.
Arguments
Option arguments modify an action and are lowercase.
The cert8.db and key3.db database files must reside in the same directory.
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:
* cert8.db
* key3.db
* secmod.db
These databases must be created before certificates or keys can be generated.
certutil -N -d <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 certdir [-p phone] [-o output-file] [-a]
The
-R
command options requires four arguments:
*
-k
to specify either the key type to generate or, when renewing a certificate, the existing key pair to use
*
-g
to set the keysize of the key to generate
*
-s
to set the subject name of the certificate
*
-d
to give the security database directory
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 ec -q nistb409 -g 512 -s "CN=John Smith,O=Example Corp,L=Mountain View,ST=California,C=US" -d . -p 650-555-0123 -a -o cert. Generating key. This may take a few moments... Certificate request generated by Netscape Phone: 650-555-0123 Common Name: John Smith Email: (not ed) Organization: Example Corp State: California Country: US -----BEGIN NEW CERTIFICATE REQUEST----- MIIBIDCBywIBADBmMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEW MBQGA1UEBxMNTW91bnRhaW4gVmlldzEVMBMGA1UEChMMRXhhbXBsZSBDb3JwMRMw EQYDVQQDEwpKb2huIFNtaXRoMFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAMVUpDOZ KmHnOx7reP8Cc0Lk+fFWEuYIDX9W5K/BioQOKvEjXyQZhit9aThzBVMoSf1Y1S8J CzdUbCg1+IbnXaECAwEAAaAAMA0GCSqGSIb3DQEBBQUAA0EAryqZvpYrUtQ486Ny qmtyQNjIi1F8c1Z+TL4uFYlMg8z6LG/J/u1E5t1QqB5e9Q4+BhRbrQjRR1JZx3tB 1hP9Gg== -----END NEW CERTIFICATE REQUEST-----
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 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.
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
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
cert8.db
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 certdir [-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 . -1 nonRepudiation,dataEncipherment -5 sslClient -6 clientAuth -7 jsmith@example.com
Generating Key Pairs
Key pairs are generated automatically with a certificate request or certificate, but they can also be generated independently using the
-G
command option.
certutil -G -d directory | -h tokenname -k key-type -g key-size [-y exponent-value] -q pqgfile|curve-name
For example:
$ certutil -G -h lunasa -k ec -g 256 -q sect193r2
Listing Certificates
The
-L
command option lists all of the certificates listed in the
cert8.db
database. The path to the directory (
-d
) is required.
$ certutil -L -d .
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 . -a -n "Certificate Authority - Example Domain" -----BEGIN CERTIFICATE----- MIIDmTCCAoGgAwIBAgIBATANBgkqhkiG9w0BAQUFADA5MRcwFQYDVQQKEw5FeGFt cGxlIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTEw MDQyOTIxNTY1OFoXDTEyMDQxODIxNTY1OFowOTEXMBUGA1UEChMORXhhbXBsZSBE b21haW4xHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTCCASIwDQYJKoZI hvcNAQEBBQADggEPADCCAQoCggEBAO/bqUli2KwqXFKmMMG93KN1SANzNTXA/Vlf Tmrih3hQgjvR1ktIY9aG6cB7DSKWmtHp/+p4PUCMqL4ZrSGt901qxkePyZ2dYmM2 RnelK+SEUIPiUtoZaDhNdiYsE/yuDE8vQWj0vHCVL0w72qFUcSQ/WZT7FCrnUIUI udeWnoPSUn70gLhcj/lvxl7K9BHyD4Sq5CzktwYtFWLiiwV+ZY/Fl6JgbGaQyQB2 bP4iRMfloGqsxGuB1evWVDF1haGpFDSPgMnEPSLg3/3dXn+HDJbZ29EU8/xKzQEb 3V0AHKbu80zGllLEt2Zx/WDIrgJEN9yMfgKFpcmL+BvIRsmh0VsCAwEAAaOBqzCB qDAfBgNVHSMEGDAWgBQATgxHQyRUfKIZtdp55bZlFr+tFzAPBgNVHRMBAf8EBTAD AQH/MA4GA1UdDwEB/wQEAwIBxjAdBgNVHQ4EFgQUAE4MR0MkVHyiGbXaeeW2ZRa/ rRcwRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vbG9jYWxob3N0 LmxvY2FsZG9tYWluOjkxODAvY2Evb2NzcDANBgkqhkiG9w0BAQUFAAOCAQEAi8Gk L3XO43u7/TDOeEsWPmq+jZsDZ3GZ85Ajt3KROLWeKVZZZa2E2Hnsvf2uXbk5amKe lRxdSeRH9g85pv4KY7Z8xZ71NrI3+K3uwmnqkc6t0hhYb1mw/gx8OAAoluQx3biX JBDxjI73Cf7XUopplHBjjiwyGIJUO8BEZJ5L+TF4P38MJz1snLtzZpEAX5bl0U76 bfu/tZFWBbE8YAWYtkCtMcalBPj6jn2WD3M01kGozW4mmbvsj1cRB9HnsGsqyHCu U0ujlL1H/RWcjn607+CTeKH9jLMUqCIqPJNOa+kq/6F7NhNRRiuzASIbZc30BZ5a nI7q5n1USM3eWQlVXw== -----END CERTIFICATE-----
Listing Keys
Keys are the original material used to encrypt certificate data. The keys generated for certificates are stored separately, in the
key3.db
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 . 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:
* To return a specific key, use the -n
name
argument with the name of the key.
* If there are multiple security devices loaded, then the -h
tokenname
argument can search a specific token or all tokens.
* If there are multiple key types available, then the -k
key-type
argument can search a specific type of key, like RSA, DSA, or ECC.
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 .
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
cert8.db
database, even if they were generated elsewhere. This uses the
-A
command option.
certutil -A -n certname -t trustargs -d certdir [-a] [-i input-file]
For example:
$ certutil -A -n "CN=My SSL Certificate" -t "u,u,u" -d . -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 . -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 directory -n "nickname"
For example:
$ certutil -D -d . -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 directory
For example, to validate an email certificate:
$ certutil -V -n "John Smith's Email Cert" -e -u S,R -d .
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 directory
For example:
$ certutil -M -n "My CA Certificate" -d . -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 . -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 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 . -h nethsm -0 secret
Upgrading or Merging the Security Databases
Some networks or applications may be using older versions of the certificate database, like a
cert7.db
database, or there may be multiple certificate databases in use. Databases can be upgraded to a new version using the
--upgrade-merge
command option or merged with other 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 directory [-P dbprefix] --source-dir directory --source-prefix dbprefix --upgrade-id id --upgrade-token-name name [-@ password-file]
For example:
$ certutil --upgrade-merge -d . --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 directory [-P dbprefix] --source-dir directory --source-prefix dbprefix [-@ password-file]
For example:
$ certutil --merge -d . --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
certutil has arguments or operations that use features defined in several IETF RFCs.
* http://tools.ietf.org/html/rfc5280
* http://tools.ietf.org/html/rfc1113
* http://tools.ietf.org/html/rfc1485
NSS is maintained in conjunction with PKI and security-related projects through Mozilla dn Fedora. The most closely-related project is Dogtag PKI, with a project wiki at http://pki.fedoraproject.org/wiki/.
For information specifically about NSS, the NSS project wiki is located at http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates directly to NSS code changes and releases.
Mailing lists: pki-devel@redhat.com and pki-users@redhat.com
The NSS tools were written and maintained by developers with Netscape and now with Red Hat.
Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey <dlackey@redhat.com>.
(c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2.