SupportConsoleDevelopersStart a trialContact

17.6. Managing the Certificate Database

Each Certificate System instance has a certificate database, which is maintained in its internal token. This database contains certificates belonging to the subsystem installed in the Certificate System 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, Certificate System 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 Certificate System window. For information on adding certificates to the database, see Section 17.6.1, “Installing Certificates in the Certificate System Database”.

Note

The Certificate System 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.

17.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.

17.6.1.1. Installing Certificates through the Console

Note

pkiconsole is being deprecated.
The Certificate Setup Wizard can install or import the following certificates into either an internal or external token used by the Certificate System instance:
  • Any of the certificates used by a Certificate System subsystem
  • Any trusted CA certificates from external CAs or other Certificate System 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:
  1. Open the console. 
    pkiconsole https://server.example.com:secure_port/subsystem_type
  2. In the Configuration tab, select System Keys and Certificates from the left navigation tree.
  3. 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 Certificate System 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.
  4. 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.
    1. When the wizard opens, select the Install a certificate radio button, and click Next.
    2. 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.
    3. 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-----
MIICKzCCAZSgAwIBAgIBAzANgkqkiG9w0BAQQFADA3MQswCQYDVQQGEw
JVUzERMA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncy
BDQTAeFw05NzEwMTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBg
NVBAYTAlVTMREwDwYDVQQKEwhOZXRzY2FwZTENMAsGA1UECxMEUHawcz
EXMBUGA1UEAxMOU3Vwcml5YSBTaGV0dHkwgZ8wDQYJKoZIhdfNAQEBBQ
ADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG7SdATYzBcABu1AVyd7
chRFOGD3wNktbf6hRo6EAmM5R1Askzf8AW7LiQZBcrXpc0k4du+2j6xJ
u2MPm8WKuMOTuvzpo+SGXelmHVChEqooCwfdiZywyZNmgaMa2MS6pUkf
QVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgD
-----END CERTIFICATE-----
  5. 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.
  6. 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 Section 17.7, “Changing the Trust Settings of a CA Certificate”.
    When installing a certificate issued by a CA that is not stored in the Certificate System 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.

17.6.1.2. Installing Certificates Using certutil

To install subsystem certificates in the Certificate System instance's security databases using certutil, do the following:
  1. Open the subsystem's security database directory. 
    cd /var/lib/pki/instance_name/alias
  2. Run the certutil command with the -A to add the certificate and -i pointing 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 Certificate System instance's certificates and keys are stored on an HSM, then specify the token name using the -h option.
    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.

17.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 Red Hat 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.

17.6.2. Viewing Database Content

The certificates stored in the subsystem certificates database, cert9.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.

Note

The certificates listed in the cert9.db database are the subsystem certificates used for subsystem operations. User certificates are stored with the user entries in the LDAP internal database.

17.6.2.1. Viewing Database Content through the Console

Note

pkiconsole is being deprecated.
To view the contents of the database through the administrative console, do the following:
  1. Open the subsystem console. 
    pkiconsole https://server.example.com:secure_port/subsystem_type
  2. In the Configuration tab, select System Keys and Certificates from the left navigation tree.
  3. 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 Certificate System Certificate Managers.
    • Local Certificates lists certificates kept by the Certificate System subsystem instance, such as the KRA transport certificate or OCSP signing certificate.
    Certificate Database Tab

    Figure 17.2. Certificate Database Tab

  4. 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.

17.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/alias

certutil -L -d .

Certificate Authority - Example Domain    CT,c,
subsystemCert cert-instance name          u,u,u
Server-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/alias

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

17.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 Section 17.7, “Changing the Trust Settings of a CA Certificate”.

17.6.3.1. Deleting Certificates through the Console

Note

pkiconsole is being deprecated.
To delete a certificate through the Console, do the following:
  1. Open the subsystem console. 
    pkiconsole https://server.example.com:secure_port/subsystem_type
  2. In the Configuration tab, select System Keys and Certificates from the left navigation tree.
  3. Select the certificate to delete, and click Delete.
  4. When prompted, confirm the delete.

17.6.3.2. Deleting Certificates Using certutil

To delete a certificate from the database using certutil:
  1. Open the instance's certificate databases directory. 
    /var/lib/pki/instance_name/alias
  2. List the certificates in the database by running the certutil with the -L option. For example: 
    certutil -L -d .

Certificate Authority - Example Domain    CT,c,
subsystemCert cert-instance_name          u,u,u
Server-Cert cert-instance_name            u,u,u
  3. Delete the certificate by running the certutil with the -D option. 
    certutil -D -d . -n certificate_nickname
    For example: 
    certutil -D -d . -n "ServerCert cert-instance_name"
  4. 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.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.