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)”.
For information about HSM, please see Section 2.3.7.2, “Hardware Security Module (HSM, external token)”.
14.1. About certutil
and PKICertImport
The
certutil
command is provided by Network 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:
Certificate Nickname
|
Trust Attributes |
---|---|
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 lowercasec
, hence you do not need to specify both).T
states that this certificate is a trusted authority for signing client certificates (T
implies lowercasec
, hence you do not need to specify bothT
andc
).
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 ifc
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.