Each CertificateSystem instance has a certificate database, which is maintained in its internal token. This database contains certificates belonging to the subsystem installed in the CertificateSystem instance and various CA certificates the subsystems use for validating the certificates they receive.
Even if an external token is used to generate and store key pairs, CertificateSystem always maintains its list of trusted and untrusted CA certificates in its internal token.
This section explains how to view the contents of the certificate database, delete unwanted certificates, and change the trust settings of CA certificates installed in the database using the CertificateSystem window. For information on adding certificates to the database, see Section16.6.1, “Installing Certificates in the Certificate System Database”.
Note
The CertificateSystem command-line utility certutil can be used to manage the certificate database by editing trust settings and adding and deleting certificates. For details about this tool, see http://www.mozilla.org/projects/security/pki/nss/tools/.
Administrators should periodically check the contents of the certificate database to make sure that it does not include any unwanted CA certificates. For example, if the database includes CA certificates that should not ever be trusted within the PKI setup, delete them.
16.6.1.Installing Certificates in the Certificate System Database
If new server certificates are issued for a subsystem, they must be installed in that subsystem database. Additionally, user and agent certificates must be installed in the subsystem databases. If the certificates are issued by an external CA, then usually the corresponding CA certificate or certificate chain needs to be installed.
Certificates can be installed in the subsystem certificate database through the Console's Certificate Setup Wizard or using the certutil utility.
Section16.6.1.1, “Installing Certificates through the Console”
Section16.6.1.2, “Installing Certificates Using certutil”
Section16.6.1.3, “About CA Certificate Chains”
16.6.1.1.Installing Certificates through the Console
The Certificate Setup Wizard can install or import the following certificates into either an internal or external token used by the CertificateSystem instance:
Any of the certificates used by a CertificateSystem subsystem
Any trusted CA certificates from external CAs or other CertificateSystem CAs
Certificate chains
A certificate chain includes a collection of certificates: the subject certificate, the trusted root CA certificate, and any intermediate CA certificates needed to link the subject certificate to the trusted root. However, the certificate chain the wizard imports must include only CA certificates; none of the certificates can be a user certificate.
In a certificate chain, each certificate in the chain is encoded as a separate DER-encoded object. When the wizard imports a certificate chain, it imports these objects one after the other, all the way up the chain to the last certificate, which may or may not be the root CA certificate. If any of the certificates in the chain are already installed in the local certificate database, the wizard replaces the existing certificates with the ones in the chain. If the chain includes intermediate CA certificates, the wizard adds them to the certificate database as untrusted CA certificates.
The subsystem console uses the same wizard to install certificates and certificate chains. To install certificates in the local security database, do the following:
Open the console.
pkiconsole https://server.example.com:secure_port/subsystem_type
In the Configuration tab, select System Keys and Certificates from the left navigation tree.
There are two tabs where certificates can be installed, depending on the subsystem type and the type of certificate.
The CA Certificates tab is for installing CA certificates and certificate chains. For Certificate Managers, this tab is used for third-party CA certificates or other CertificateSystem CA certificates; all of the local CA certificates are installed in the Local Certificates tab. For all other subsystems, all CA certificates and chains are installed through this tab.
The Local Certificates tab is where all server certificates, subsystem certificates, and local certificates such as OCSP signing or KRA transport are installed.
Select the appropriate tab.
To install a certificate in the Local Certificates tab, click Add/Renew. To install a certificate in the CA Certificates tab, click Add. Both will open the Certificate Setup Wizard.
When the wizard opens, select the Install a certificate radio button, and click Next.
Select the type of certificate to install. The options for the drop-down menu are the same options available for creating a certificate, depending on the type of subsystem, with the additional option to install a cross-pair certificate.
Paste in the certificate body, including the
-----BEGIN CERTIFICATE-----and-----END CERTIFICATE-----, into the text area, or specify the absolute file location; this must be a local file.The certificate will look like the following:
-----BEGIN CERTIFICATE-----MIICKzCCAZSgAwIBAgIBAzANgkqkiG9w0BAQQFADA3MQswCQYDVQQGEwJVUzERMA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncyBDQTAeFw05NzEwMTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBgNVBAYTAlVTMREwDwYDVQQKEwhOZXRzY2FwZTENMAsGA1UECxMEUHawczEXMBUGA1UEAxMOU3Vwcml5YSBTaGV0dHkwgZ8wDQYJKoZIhdfNAQEBBQADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG7SdATYzBcABu1AVyd7chRFOGD3wNktbf6hRo6EAmM5R1Askzf8AW7LiQZBcrXpc0k4du+2j6xJu2MPm8WKuMOTuvzpo+SGXelmHVChEqooCwfdiZywyZNmgaMa2MS6pUkfQVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgD-----END CERTIFICATE-----
The wizard displays the certificate details. Review the fingerprint to make sure this is the correct certificate, or use the Back button to go back and submit a different one. Give a nickname for the certificate.
The wizard installs the certificate.
Any CA that signed the certificate must be trusted by the subsystem. Make sure that this CA's certificate exists in the subsystem's certificate database (internal or external) and that it is trusted.
If the CA certificate is not listed, add the certificate to the certificate database as a trusted CA. If the CA's certificate is listed but untrusted, change the trust setting to trusted, as shown in Section16.7, “Changing the Trust Settings of a CA Certificate”.
When installing a certificate issued by a CA that is not stored in the CertificateSystem certificate database, add that CA's certificate chain to the database. To add the CA chain to the database, copy the CA chain to a text file, start the wizard again, and install the CA chain.
16.6.1.2.Installing Certificates Using certutil
To install subsystem certificates in the CertificateSystem instance's security databases using certutil, do the following:
Open the subsystem's security database directory.
cd /var/lib/pki/instance_name/alias
Run the
certutilcommand with the-Ato add the certificate and-ipointing to the file containing the certificate issued by the CA.certutil -A -n cert-name -t trustargs -d . -a -i certificate_file
Note
If the CertificateSystem instance's certificates and keys are stored on an HSM, then specify the token name using the
-hoption.For example:
certutil -A -n "ServerCert cert-instance_name" -t u,u,u -d . -a -i /tmp/example.cert
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.
16.6.1.3.About CA Certificate Chains
Any client or server software that supports certificates maintains a collection of trusted CA certificates in its certificate database. These CA certificates determine which other certificates the software can validate. In the simplest case, the software can validate only certificates issued by one of the CAs for which it has a certificate. It is also possible for a trusted CA certificate to be part of a chain of CA certificates, each issued by the CA above it in a certificate hierarchy.
The first certificate in the chain is processed in a context-specific manner, which varies according to how it is being imported. For Mozilla Firefox, this handling depends upon the MIME content type used on the object being downloaded. For RedHat servers, it depends upon the options selected in the server administration interface.
Subsequent certificates are all treated the same. If the certificates contain the SSL-CA bit in the Netscape Certificate Type certificate extension and do not already exist in the local certificate database, they are added as untrusted CAs. They can be used for certificate chain validation as long as there is a trusted CA somewhere in the chain.
16.6.2.Viewing Database Content
The certificates stored in the subsystem certificates database, cert8.db, can be viewed through the subsystem administrative console. Alternatively, the certificates can be listed using the certutil utility. certutil must be used to view the TPS certificates because the TPS subsystem does not use an administrative console.
Section16.6.2.1, “Viewing Database Content through the Console”
Section16.6.2.2, “Viewing Database Content Using certutil”
Note
The certificates listed in the cert8.db database are the subsystem certificates used for subsystem operations. User certificates are stored with the user entries in the LDAP internal database.
16.6.2.1.Viewing Database Content through the Console
Open the subsystem console.
pkiconsole https://server.example.com:secure_port/subsystem_type
In the Configuration tab, select System Keys and Certificates from the left navigation tree.
There are two tabs, CA Certificates and Local Certificates, which list different kinds of certificates.
CA Certificates lists CA certificates for which the corresponding private key material is not available, such as certificates issued by third-party CAs such as Entrust or Verisign or external CertificateSystem Certificate Managers.
Local Certificates lists certificates kept by the CertificateSystem subsystem instance, such as the KRA transport certificate or OCSP signing certificate.
Figure16.2.Certificate Database Tab
The Certificate Database Management table lists the all of the certificates installed on the subsystem. The following information is supplied for each certificate:
Certificate Name
Serial Number
Issuer Names, the common name (
cn) of the issuer of this certificate.Token Name, the name of the cryptographic token holding the certificate; for certificate stored in the database, this is
internal.
To view more detailed information about the certificate, select the certificate, and click View. This opens a window which shows the serial number, validity period, subject name, issuer name, and certificate fingerprint of the certificate.
16.6.2.2.Viewing Database Content Using certutil
To view the certificates in the subsystem database using certutil, open the instance's certificate database directory, and run the certutil with the -L option. For example:
cd /var/lib/pki/instance_name/aliascertutil -L -d .Certificate Authority - Example Domain CT,c,subsystemCert cert-instance name u,u,uServer-Cert cert-instance_name u,u,u
To view the keys stored in the subsystem databases using certutil, run the certutil with the -K option. For example:
cd /var/lib/pki/instance_name/aliascertutil -K -d .Enter Password or Pin for "NSS Certificate DB":<0> subsystemCert cert-instance_name<1><2> Server-Cert cert-instance_name
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.
16.6.3.Deleting Certificates from the Database
Removing unwanted certificates reduces the size of the certificate database.
Note
When deleting CA certificates from the certificate database, be careful not to delete the intermediate CA certificates, which help a subsystem chain up to the trusted CA certificate. If in doubt, leave the certificates in the database as untrusted CA certificates; see Section16.7, “Changing the Trust Settings of a CA Certificate”.
Section16.6.3.1, “Deleting Certificates through the Console”
Section16.6.3.2, “Deleting Certificates Using certutil”
16.6.3.1.Deleting Certificates through the Console
To delete a certificate through the Console, do the following:
Open the subsystem console.
pkiconsole https://server.example.com:secure_port/subsystem_type
In the Configuration tab, select System Keys and Certificates from the left navigation tree.
Select the certificate to delete, and click Delete.
When prompted, confirm the delete.
16.6.3.2.Deleting Certificates Using certutil
To delete a certificate from the database using certutil:
Open the instance's certificate databases directory.
/var/lib/pki/instance_name/alias
List the certificates in the database by running the
certutilwith the-Loption. For example:certutil -L -d .Certificate Authority - Example Domain CT,c,subsystemCert cert-instance_name u,u,uServer-Cert cert-instance_name u,u,u
Delete the certificate by running the
certutilwith the-Doption.certutil -D -d . -n certificate_nickname
For example:
certutil -D -d . -n "ServerCert cert-instance_name"
List the certificates again to confirm that the certificate was removed.
certutil -L -d .Certificate Authority - Example Domain CT,c,subsystemCert cert-instance_name u,u,u
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.
