certutil - Man Page

Manage keys and certificate in both NSS databases and other NSS tokens

Examples (TL;DR)

Create a [N]ew certificate database in the current [d]irectory: certutil -N -d .
List all certificates in a database: certutil -L -d .
List all private [K]eys in a database specifying the password [f]ile: certutil -K -d . -f path/to/password_file.txt
[A]dd the signed certificate to the requesters database specifying a [n]ickname, [t]rust attributes and an [i]nput CRT file: certutil -A -n "server_certificate" -t ",," -i path/to/file.crt -d .
Add subject alternative names to a given [c]ertificate with a specific key size ([g]): certutil -S -f path/to/password_file.txt -d . -t ",," -c "server_certificate" -n "server_name" -g 2048 -s "CN=common_name,O=organization"

Status

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

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

-A

Add an existing certificate to a certificate database. The certificate database should already exist; if one is not present, this command option will initialize one by default.

-B

Run a series of commands from the specified batch file. This requires the -i argument.

-C

Create a new binary certificate file from a binary certificate request file. Use the -i argument to specify the certificate request file. If this argument is not used, certutil prompts for a filename.

-D

Delete a certificate from the certificate database.

--rename

Change the database nickname of a certificate.

-E

Add an email certificate to the certificate database.

-F

Delete a private key and the associated certificate from a database. Specify the key to delete with the -n argument or the -k argument. Specify the database from which to delete the key with the -d argument.

Some smart cards do not let you remove a public key you have generated. In such a case, only the private key is deleted from the key pair.

-G

Generate a new public and private key pair within a key database. The key database should already exist; if one is not present, this command option will initialize one by default. Some smart cards can store only one key pair. If you create a new key pair for such a card, the previous pair is overwritten.

-H

Display a list of the command options and arguments.

-K

List the key ID of keys in the key database. A key ID is the modulus of the RSA key or the publicValue of the DSA key. IDs are displayed in hexadecimal ("0x" is not shown).

-L

List all the certificates, or display information about a named certificate, in a certificate database. Use the -h tokenname argument to specify the certificate database on a particular hardware or software token.

-M

Modify a certificate's trust attributes using the values of the -t argument.

-N

Create new certificate and key databases.

-O

Print the certificate chain.

-R

Create a certificate request file that can be submitted to a Certificate Authority (CA) for processing into a finished certificate. Output defaults to standard out unless you use -o output-file argument. Use the -a argument to specify ASCII output.

-S

Create an individual certificate and add it to a certificate database.

-T

Reset the key database or token.

-U

List all available modules or print a single named module.

-V

Check the validity of a certificate and its attributes.

-W

Change the password to a key database.

--merge

Merge two databases into one.

--upgrade-merge

Upgrade an old database and merge it into a new database. This is used to migrate legacy NSS databases (cert8.db and key3.db) into the newer SQLite databases (cert9.db and key4.db).

Arguments

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

-a

Use ASCII format or allow the use of ASCII format for input or output. This formatting follows RFC 1113. For certificate requests, ASCII output defaults to standard output unless redirected.

--simple-self-signed

When printing the certificate chain, don't search for a chain if issuer name equals to subject name.

-b validity-time

Specify a time at which a certificate is required to be valid. Use when checking certificate validity with the -V option. The format of the validity-time argument is YYMMDDHHMMSS[+HHMM|-HHMM|Z], which allows offsets to be set relative to the validity end time. Specifying seconds (SS) is optional. When specifying an explicit time, use a Z at the end of the term, YYMMDDHHMMSSZ, to close it. When specifying an offset time, use YYMMDDHHMMSS+HHMM or YYMMDDHHMMSS-HHMM for adding or subtracting time, respectively.

If this option is not used, the validity check defaults to the current system time.

-c issuer

Identify the certificate of the CA from which a new certificate will derive its authenticity. Use the exact nickname or alias of the CA certificate, or use the CA's email address. Bracket the issuer string with quotation marks if it contains spaces.

-d [prefix]directory

Specify the database directory containing the certificate and key database files.

certutil 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).

NSS recognizes the following prefixes:

sql: requests the sql-lite database

If no prefix is specified the default type is retrieved from NSS_DEFAULT_DB_TYPE. If NSS_DEFAULT_DB_TYPE is not set then sql: is the default.

--dump-ext-val OID

For single cert, print binary DER encoding of extension OID.

-e

Check a certificate's signature during the process of validating a certificate.

--email email-address

Specify the email address of a certificate to list. Used with the -L command option.

--extGeneric OID:critical-flag:filename[,OID:critical-flag:filename]...

Add one or multiple extensions that certutil cannot encode yet, by loading their encodings from external files.

OID (example): 1.2.3.4
critical-flag: critical or not-critical
filename: full path to a file containing an encoded extension

-f password-file

Specify a file that will automatically supply the password to include in a certificate or to access a certificate database. This is a plain-text file containing one password. Be sure to prevent unauthorized access to this file.

-g keysize

Set a key size to use when generating new public and private key pairs. The minimum is 512 bits and the maximum is 16384 bits. The default is 2048 bits. Any size between the minimum and maximum is allowed.

-h tokenname

Specify the name of a token to use or act on. If not specified the default token is the internal database slot.

The name can also be a PKCS #11 URI. For example, the NSS internal certificate store can be unambiguously specified as "pkcs11:token=NSS%20Certificate%20DB". For details about the format, see RFC 7512.

-i input_file

Pass an input file to the command. Depending on the command option, an input file can be a specific certificate, a certificate request file, or a batch file of commands.

-k key-type-or-id

Specify the type or specific ID of a key.

The valid key type options are rsa, dsa, ec, or all. The default value is rsa. Specifying the type of key can avoid mistakes caused by duplicate nicknames. Giving a key type generates a new key pair; giving the ID of an existing key reuses that key pair (which is required to renew certificates).

-l

Display detailed information when validating a certificate with the -V option.

-m serial-number

Assign a unique serial number to a certificate being created. This operation should be performed by a CA. If no serial number is provided a default serial number is made from the current time. Serial numbers are limited to integers

-n nickname

Specify the nickname of a certificate or key to list, create, add to a database, modify, or validate. Bracket the nickname string with quotation marks if it contains spaces.

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.

-o output-file

Specify the output file name for new certificates or binary certificate requests. Bracket the output-file string with quotation marks if it contains spaces. If this argument is not used the output destination defaults to standard output.

-P dbPrefix

Specify the prefix used on the certificate and key database file. This argument is provided to support legacy servers. Most applications do not use a database prefix.

-p phone

Specify a contact telephone number to include in new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces.

-q pqgfile or curve-name

Read an alternate PQG value from the specified file when generating DSA key pairs. If this argument is not used, certutil generates its own PQG value. PQG files are created with a separate DSA utility.

Elliptic curve name is one of the ones from nistp256, nistp384, nistp521, curve25519.

If a token is available that supports more curves, the foolowing curves are supported as well: sect163k1, nistk163, sect163r1, sect163r2, nistb163, sect193r1, sect193r2, sect233k1, nistk233, sect233r1, nistb233, sect239k1, sect283k1, nistk283, sect283r1, nistb283, sect409k1, nistk409, sect409r1, nistb409, sect571k1, nistk571, sect571r1, nistb571, secp160k1, secp160r1, secp160r2, secp192k1, secp192r1, nistp192, secp224k1, secp224r1, nistp224, secp256k1, secp256r1, secp384r1, secp521r1, prime192v1, prime192v2, prime192v3, prime239v1, prime239v2, prime239v3, c2pnb163v1, c2pnb163v2, c2pnb163v3, c2pnb176v1, c2tnb191v1, c2tnb191v2, c2tnb191v3, c2pnb208w1, c2tnb239v1, c2tnb239v2, c2tnb239v3, c2pnb272w1, c2pnb304w1, c2tnb359w1, c2pnb368w1, c2tnb431r1, secp112r1, secp112r2, secp128r1, secp128r2, sect113r1, sect113r2, sect131r1, sect131r2

-r

Display a certificate's binary DER encoding when listing information about that certificate with the -L option.

-s subject

Identify a particular certificate owner for new certificates or certificate requests. Bracket this string with quotation marks if it contains spaces. The subject identification format follows RFC #1485.

-t trustargs

Specify the trust attributes to modify in an existing certificate or to apply to a certificate when creating it or adding it to a database. There are three available trust categories for each certificate, expressed in the order SSL, email, object signing for each trust setting. In each category position, use none, any, or all of the attribute codes:

p - Valid peer
P - Trusted peer (implies p)
c - Valid CA
C - Trusted CA (implies c)
T - trusted CA for client authentication (ssl server only)

The attribute codes for the categories are separated by commas, and the entire set of attributes enclosed by quotation marks. For example:

-t "TC,C,T"

Use the -L option to see a list of the current certificates and trust attributes in a certificate database.

Note that the output of the -L option may include "u" flag, which means that there is a private key associated with the certificate. It is a dynamic flag and you cannot set it with certutil.

-u certusage

Specify a usage context to apply when validating a certificate with the -V option.

The contexts are the following:

C (as an SSL client)
V (as an SSL server)
L (as an SSL CA)
A (as Any CA)
Y (Verify CA)
S (as an email signer)
R (as an email recipient)
O (as an OCSP status responder)
J (as an object signer)
I (as an IPSEC user)

-v valid-months

Set the number of months a new certificate will be valid. The validity period begins at the current system time unless an offset is added or subtracted with the -w option. If this argument is not used, the default validity period is three months.

-w offset-months

Set an offset from the current system time, in months, for the beginning of a certificate's validity period. Use when creating the certificate or adding it to a database. Express the offset in integers, using a minus sign (-) to indicate a negative offset. If this argument is not used, the validity period begins at the current system time. The length of the validity period is set with the -v argument.

-X

Force the key and certificate database to open in read-write mode. This is used with the -U and -L command options.

-x

Use certutil to generate the signature for a certificate being created or added to a database, rather than obtaining a signature from a separate CA.

-y exp

Set an alternate exponent value to use in generating a new RSA public key for the database, instead of the default value of 65537. The available alternate values are 3 and 17.

--pss

Restrict the generated certificate (with the -S option) or certificate request (with the -R option) to be used with the RSA-PSS signature scheme. This only works when the private key of the certificate or certificate request is RSA.

--pss-sign

Sign the generated certificate with the RSA-PSS signature scheme (with the -C or -S option). This only works when the private key of the signer's certificate is RSA. If the signer's certificate is restricted to RSA-PSS, it is not necessary to specify this option.

-z noise-file

Read a seed value from the specified file to generate a new private and public key pair. This argument makes it possible to use hardware-generated seed values or manually create a value from the keyboard. The minimum file size is 20 bytes.

-Z hashAlg

Specify the hash algorithm to use with the -C, -S or -R command options. Possible keywords:

MD2
MD4
MD5
SHA1
SHA224
SHA256
SHA384
SHA512

-0 SSO_password

Set a site security officer password on a token.

-1 | --keyUsage keyword,keyword

Set an X.509 V3 Certificate Type Extension in the certificate. There are several available keywords:

digitalSignature
nonRepudiation
keyEncipherment
dataEncipherment
keyAgreement
certSigning
crlSigning
critical

-2

Add a basic constraint extension to a certificate that is being created or added to a database. This extension supports the certificate chain verification process. certutil prompts for the certificate constraint extension to select.