Chapter 14. Managing Certificate/Key Crypto Token

This chapter contains instructions on how to manage certificate/key token database on the crypto tokens, specifically on how to import and verify certificates for various scenarios.

About Crypto Tokens

For information about NSS soft token, please see Section 2.3.7.1, “NSS Soft Token (internal token)”.

14.1. About certutil and PKICertImport

The certutil command is provided by Netscape Security Services (NSS). certutil is used for validating and importing certificates. A basic overview of how we use certutil is presented below, however, PKICertImport is our wrapper script of choice for safely validating and importing certificates. Using certutil to do so requires multiple command invocations and correct usage is outside the scope of this documentation.

14.1.1. certutil Basic Usage

certutil [command] [options]
Each certutil invocation takes a command flag, usually denoted by a capital letter, and a series of options which control what the command does. If an option takes a value, that value is named between "<" and ">" symbols.

14.1.2. PKICertImport Basic Usage

PKICertImport [options]
Each PKICertImport invocation takes a series of options to validate and import a specified certificate. Unlike the broad use cases of certutil, PKICertImport is only focused on safely importing and validating certificates. See Section 14.1.4, “Common certutil and PKICertImport Options” for more information about available options.

Note

PKICertImport prompts for the NSS DB and/or HSM passwords multiple times throughout the course of its execution. This is expected as PKICertImport has to interact with the NSS DB multiple times. To avoid having to input the NSS DB password repetitively, specify a password file via -f <filename>. When done, be sure to delete the password file.

14.1.3. certutil Common Commands

The following commands are specific to certutil and provide a brief overview of several common commands. PKICertImport is not compatible with nor require these command flags.

certutil -A

The -A command denotes "adding" a certificate. It requires a certificate to import (-i), a nickname (-n) for that certificate, and a series of trust flags (-t) for the certificate.

certutil -V

The -V command denotes "verifying" a certificate. It requires a certificate nickname to validate (-n) and a type of verification (-u) to perform.

certutil -D

The -D command denotes "deleting" a certificate. It requires a certificate nickname (-n) to remove.
Note that it ONLY removes the PUBLIC KEY portion of the certificate, and WILL NOT remove any private keys, if present.

certutil -M

The -M command denotes "modifying" a certificate. It requires a certificate nickname (-n) to modify, and a series of trust flags (-t) to give the certificate.

certutil -L

The -L command denotes "listing" a certificate or all certificates. If given the nickname option (-n), it will list detailed information about that certificate, else if omitted, it will list general information about all certificates present.
The result of certutil -L would show each certificate by its nickname along with its trust info. For example:

Table 14.1. Certificate nickname and trust info

Certificate Nickname

Trust Attributes
SSL, S/MIME, JAR/XPI

caSigningCert pki-ca1
CT, C, C

Note

The trust attributes displayed by certutil -L correspond to what is specified with the -t option.
The certutil -L does not modify the database, and can thus be executed safely as many times as desired.

14.1.4. Common certutil and PKICertImport Options

When following the steps below, ensure the values are relevant and correct for your specific deployment scenario. Many of these options are available to PKICertImport as well.

-n <nickname>

The -n <nickname> option specifies the nickname for a certificate. This can be any text and is only used as a reference to the certificate. It MUST be unique.
Update this value as appropriate for your configuration.

-d <directory>

The -d <directory> option specifies the path to the NSS DB directory in use. We usually assume you are already in this directory and use "." to refer to the current directory.
Update this value as appropriate for your configuration.

-t <trust>

The -t <trust> option specifies the trust level for the certificate.
There are three main categories of trust:
  • trust for TLS
  • trust for email
  • trust for object signing
Each trust position can have one or more trust letters which specify the desired level of trust. The trust letters we use below are c, C, and T.
  • c states that this certificate should be a Certificate Authority (CA).
  • C states that this is a trusted certificate authority for signing server certificates (C implies lowercase c, hence you do not need to specify both).
  • T states that this certificate is a trusted authority for signing client certificates (T implies lowercase c, hence you do not need to specify both T and c).
To specify the trust flags for each position, join the letters with commas. For example, the option -t CT,C,c means that the certificate is trusted for signing client and server TLS certificates, signing server email certificates (S/MIME), and is a valid CA for object signing (though untrusted).
  • This ensures that, if this certificate signs another certificate, which in turn is used for object signing, it will be deemed invalid.
No trust (or the lack of trust) can be specified by using -t ,,.
To see the trust levels of all certificates in the database, run:
  • certutil -L -d
  • Each certificate's nickname will be listed and the trust flags will be specified at the end of the line.
See the notes about HSMs in the -h option.
Note that more trust levels are specified in the certutil manpage. To reference this documentation, please run the man certutil command on a system with certutil properly installed.

-h <HSM>

The -h <HSM> option specifies the name of the HSM to perform operations on.
-h option is incompatible with the -t option, as HSMs cannot store trust. Only an NSS DB can store trust, so using the certutil -A command or the certutil -M command in conjunction with -h <HSM> will fail. Instead, specify the desired trust level on a separate certutil -M command without the -h option.
Update this value as appropriate for your configuration.

-e

The -e option specifies that the validity of the signature is checked as well, when used in conjunction with the certutil -V command. PKICertImport always performs the certificate signature validation and does not understand the -e option.

-a

The -a option specifies that the key in question is in PEM (ASCII) format.

-i <certificate>

The -i <certificate> option specifies the path to the certificate. This is only used in the certutil -A command to specify the path to the certificate to import.
Update this value as appropriate for your configuration.

-u <usage>

The -u <usage> option specifies that usage of the certificate to verify when used in conjunction with the certutil -V command.
There are several usage letters referenced in the following sections.
  • -u C stands for verify a client TLS certificate. Note that this mostly accepts any certificate, but will check expiration date and signature.
  • -u V stands for verify a server TLS certificate. Note that this will reject CA certificates and will check expiration date and signature.
  • -u L stands for verify a CA TLS certificate. Note that this will validate trust flags (to see if c is present) and will check key usage to ensure that the key is a CA key. This also checks expiration and signatures.
  • -u O stands for verify a OCSP status responder certificate. Note that this checks expiry and signatures.
  • -u J stands for verify an object signing certificate. Note that this checks expiry and signatures.
If the wrong usage option is specified or the trust flags on the certificate are wrong (such as a missing c flag for an CA TLS certificate), certutil -V will give incorrect results.

Note

More usage options are specified in the certutil manpage. To reference this documentation, run the man certutil command on a system with certutil properly installed.