Chapter 13. Managing subsystem certificates
This chapter gives an overview of using certificates: what types and formats are available, how to request and create them through the HTML end-entity forms and through the Certificate System Console, and how to install certificates in the Certificate System and on different clients. Additionally, there is information on managing certificates through the Console and configuring the servers to use them.
13.1. Required subsystem certificates
Each subsystem has a defined set of certificates which must be issued to the subsystem instance for it to perform its operations. There are certain details of the certificate contents that are set during the Certificate Manager configuration, with different considerations for constraints, settings, and attributes depending on the types of certificates.
13.1.1. Certificate Manager certificates
When a Certificate Manager is installed, the keys and requests for the CA signing certificate, SSL server certificate, and OCSP signing certificate are generated. The certificates are created before the configuration can be completed.
The CA certificate request is either submitted as a self-signing request to the CA, which then issues the certificate and finishes creating the self-signed root CA, or is submitted to a third-party public CA or another Certificate System CA. When the external CA returns the certificate, the certificate is installed, and installation of the subordinate CA is completed.
13.1.1.1. CA signing key pair and certificate
Every Certificate Manager has a CA signing certificate with a public key corresponding to the private key the Certificate Manager uses to sign the certificates and CRLs it issues. This certificate is created and installed when the Certificate Manager is installed. The default nickname for the certificate is caSigningCert cert-instance_ID CA, where instance_ID identifies the Certificate Manager instance. The default validity period for the certificate is five years.
The subject name of the CA signing certificate reflects the name of the CA that was set during installation. All certificates signed or issued by the Certificate Manager include this name to identify the issuer of the certificate.
The Certificate Manager’s status as a root or subordinate CA is determined by whether its CA signing certificate is self-signed or is signed by another CA, which affects the subject name on the certificates.
- If the Certificate Manager is a root CA, its CA signing certificate is self-signed, meaning the subject name and issuer name of the certificate are the same.
- If the Certificate Manager is a subordinate CA, its CA signing certificate is signed by another CA, usually the one that is a level above in the CA hierarchy (which may or may not be a root CA). The root CA’s signing certificate must be imported into individual clients and servers before the Certificate Manager can be used to issue certificates to them.
The CA name cannot be changed or all previously-issued certificates are invalidated. Similarly, reissuing a CA signing certificate with a new key pair invalidates all certificates that were signed by the old key pair.
13.1.1.2. OCSP signing key pair and certificate
The subject name of the OCSP signing certificate is in the form cn=OCSP cert-instance_ID CA, and it contains extensions, such as OCSPSigning and OCSPNoCheck, required for signing OCSP responses.
The default nickname for the OCSP signing certificate is ocspSigningCert cert-instance_ID CA, where instance_ID CA identifies the Certificate Manager instance.
The OCSP private key, corresponding to the OCSP signing certificate’s public key, is used by the Certificate Manager to sign the OCSP responses to the OCSP-compliant clients when queried about certificate revocation status.
13.1.1.3. Subsystem certificate
Every member of the security domain is issued a server certificate to use for communications among other domain members, which is separate from the server SSL certificate. This certificate is signed by the security domain CA; for the security domain CA itself, its subsystem certificate is signed by itself.
The default nickname for the certificate is subsystemCert cert-instance_ID.
13.1.1.4. SSL server key pair and certificate
Every Certificate Manager has at least one SSL server certificate that was first generated when the Certificate Manager was installed. The default nickname for the certificate is Server-Cert cert-instance_ID, where instance_ID identifies the Certificate Manager instance.
By default, the Certificate Manager uses a single SSL server certificate for authentication. However, additional server certificates can be requested to use for different operations, such as configuring the Certificate Manager to use separate server certificates for authenticating to the end-entity services interface and agent services interface.
If the Certificate Manager is configured for SSL-enabled communication with a publishing directory, it uses its SSL server certificate for client authentication to the publishing directory by default. The Certificate Manager can also be configured to use a different certificate for SSL client authentication.
13.1.1.5. Audit log signing key pair and certificate
The CA keeps a secure audit log of all events which occurred on the server. To guarantee that the audit log has not been tampered with, the log file is signed by a special log signing certificate.
The audit log signing certificate is issued when the server is first configured.
13.1.2. Online Certificate Status Manager certificates
When the Online Certificate Status Manager is first configured, the keys for all required certificates are created, and the certificate requests for the OCSP signing, SSL server, audit log signing, and subsystem certificates are made. These certificate requests are submitted to a CA (either a Certificate System CA or a third-party CA) and must be installed in the Online Certificate Status Manager database to complete the configuration process.
13.1.2.1. OCSP signing key pair and certificate
Every Online Certificate Status Manager has a certificate, the OCSP signing certificate, which has a public key corresponding to the private key the Online Certificate Status Manager uses to sign OCSP responses. The Online Certificate Status Manager’s signature provides persistent proof that the Online Certificate Status Manager has processed the request. This certificate is generated when the Online Certificate Status Manager is configured. The default nickname for the certificate is ocspSigningCert cert-instance_ID, where instance_ID OSCP is the Online Certificate Status Manager instance name.
13.1.2.2. SSL server key pair and certificate
Every Online Certificate Status Manager has at least one SSL server certificate which was generated when the Online Certificate Status Manager was configured. The default nickname for the certificate is Server-Cert cert-instance_ID, where instance_ID identifies the Online Certificate Status Manager instance name.
The Online Certificate Status Manager uses its server certificate for server-side authentication for the Online Certificate Status Manager agent services page.
The Online Certificate Status Manager uses a single server certificate for authentication purposes. Additional server certificates can be installed and used for different purposes.
13.1.2.3. Subsystem certificate
Every member of the security domain is issued a server certificate to use for communications among other domain members, which is separate from the server SSL certificate. This certificate is signed by the security domain CA.
The default nickname for the certificate is subsystemCert cert-instance_ID.
13.1.2.4. Audit log signing key pair and certificate
The OCSP keeps a secure audit log of all events which occurred on the server. To guarantee that the audit log has not been tampered with, the log file is signed by a special log signing certificate.
The audit log signing certificate is issued when the server is first configured.
13.1.2.5. Recognizing Online Certificate Status Manager certificates
Depending on the CA which signed the Online Certificate Status Manager’s SSL server certificate, it may be necessary to get the certificate and issuing CA recognized by the Certificate Manager.
- If the Online Certificate Status Manager’s server certificate is signed by the CA that is publishing CRLs, then nothing needs to be done.
- If the Online Certificate Status Manager’s server certificate is signed by the same root CA that signed the subordinate Certificate Manager’s certificates, then the root CA must be marked as a trusted CA in the subordinate Certificate Manager’s certificate database.
- If the Online Certificate Status Manager’s SSL server certificate is signed by a different root CA, then the root CA certificate must be imported into the subordinate Certificate Manager’s certificate database and marked as a trusted CA.
If the Online Certificate Status Manager’s server certificate is signed by a CA within the selected security domain, the certificate chain is imported and marked when the Online Certificate Status Manager is configured. No other configuration is required. However, if the server certificate is signed by an external CA, the certificate chain has to be imported for the configuration to be completed.
Not every CA within the security domain is automatically trusted by the OCSP Manager when it is configured. Every CA in the certificate chain of the CA configured in the CA panel is, however, trusted automatically by the OCSP Manager. Other CAs within the security domain but not in the certificate chain must be added manually.
13.1.3. Key Recovery Authority certificates
The KRA uses the following key pairs and certificates:
13.1.3.1. Transport key pair and certificate
Every KRA has a transport certificate. The public key of the key pair that is used to generate the transport certificate is used by the client software to encrypt an end entity’s private encryption key before it is sent to the KRA for archival; only those clients capable of generating dual-key pairs use the transport certificate.
13.1.3.2. Storage key pair
Every KRA has a storage key pair. The KRA uses the public component of this key pair to encrypt (or wrap) private encryption keys when archiving the keys. It uses the private component to decrypt (or unwrap) the archived key during recovery. For more information on how this key pair is used, see Chapter 4, Setting up key archival and recovery.
Keys encrypted with the storage key can be retrieved only by authorized key recovery agents.
13.1.3.3. SSL server certificate
Every Certificate System KRA has at least one SSL server certificate. The first SSL server certificate is generated when the KRA is configured. The default nickname for the certificate is Server-Cert cert-instance_ID, where instance_id identifies the KRA instance is installed.
The KRA’s SSL server certificate was issued by the CA to which the certificate request was submitted, which can be a Certificate System CA or a third-party CA. To view the issuer name, open the certificate details in the System Keys and Certificates option in the KRA Console.
The KRA uses its SSL server certificate for server-side authentication to the KRA agent services interface. By default, the Key Recovery Authority uses a single SSL server certificate for authentication. However, additional SSL server certificates can be requested and installed for the KRA.
13.1.3.4. Subsystem certificate
Every member of the security domain is issued a server certificate to use for communications among other domain members, which is separate from the server SSL certificate. This certificate is signed by the security domain CA.
The default nickname for the certificate is subsystemCert cert-instance_ID.
13.1.3.5. Audit log signing key pair and certificate
The KRA keeps a secure audit log of all events which occurred on the server. To guarantee that the audit log has not been tampered with, the log file is signed by a special log signing certificate.
The audit log signing certificate is issued when the server is first configured.
13.1.4. TKS certificates
The TKS has three certificates. The SSL server and subsystem certificates are used for standard operations. An additional signing certificate is used to protect audit logs.
13.1.4.1. SSL server certificate
Every Certificate System TKS has at least one SSL server certificate. The first SSL server certificate is generated when the TKS is configured. The default nickname for the certificate is Server-Cert cert-instance_ID.
13.1.4.2. Subsystem certificate
Every member of the security domain is issued a server certificate to use for communications among other domain members, which is separate from the server SSL certificate. This certificate is signed by the security domain CA.
The default nickname for the certificate is subsystemCert cert-instance_ID.
13.1.4.3. Audit log signing key pair and certificate
The TKS keeps a secure audit log of all events which occurred on the server. To guarantee that the audit log has not been tampered with, the log file is signed by a special log signing certificate.
The audit log signing certificate is issued when the server is first configured.
13.1.5. TPS Certificates
The TPS only uses three certificates: a server certificate, subsystem certificate, and audit log signing certificate.
13.1.5.1. SSL server certificate
Every Certificate System TPS has at least one SSL server certificate. The first SSL server certificate is generated when the TPS is configured. The default nickname for the certificate is Server-Cert cert-instance_ID.
13.1.5.2. Subsystem certificate
Every member of the security domain is issued a server certificate to use for communications among other domain members, which is separate from the server SSL certificate. This certificate is signed by the security domain CA.
The default nickname for the certificate is subsystemCert cert-instance_ID.
13.1.5.3. Audit log signing key pair and certificate
The TPS keeps a secure audit log of all events which occurred on the server. To guarantee that the audit log has not been tampered with, the log file is signed by a special log signing certificate.
The audit log signing certificate is issued when the server is first configured.
13.1.6. About subsystem certificate key types
When you create a new instance, you can specify the key type and key size in the configuration file passed to the pkispawn utility.
Example 13.1. Key type-related Configuration Parameters for a CA
The following are key type-related parameters including example values. You can set these parameters in the configuration file which you pass to pkispawn when creating a new CA.
pki_ocsp_signing_key_algorithm=SHA256withRSA pki_ocsp_signing_key_size=2048 pki_ocsp_signing_key_type=rsa pki_ca_signing_key_algorithm=SHA256withRSA pki_ca_signing_key_size=2048 pki_ca_signing_key_type=rsa pki_sslserver_key_algorithm=SHA256withRSA pki_sslserver_key_size=2048 pki_sslserver_key_type=rsa pki_subsystem_key_algorithm=SHA256withRSA pki_subsystem_key_size=2048 pki_subsystem_key_type=rsa pki_admin_keysize=2048 pki_admin_key_size=2048 pki_admin_key_type=rsa pki_audit_signing_key_algorithm=SHA256withRSA pki_audit_signing_key_size=2048 pki_audit_signing_key_type=rsa
The values in the example are for a CA. Other subsystems require different parameters.
For further details, see:
- 7.2 Installing RHCS using the pkispawn utility in the Planning, Installation and Deployment Guide (Common Criteria Edition).
-
The
pki_default.cfg(5)man page for descriptions of the parameters and examples.
13.1.7. Using an HSM to store subsystem certificates
By default, keys and certificates are stored in locally-managed databases, key4.db and cert9.db, respectively, in the /var/lib/pki/instance_name/alias directory. However, Red Hat Certificate System also supports hardware security modules (HSM), external devices which can store keys and certificates in a centralized place on the network. Using an HSM can make some functions, like cloning, easier because the keys and certificates for the instance are readily accessible.
When an HSM is used to store certificates, then the HSM name is prepended to the certificate nickname, and the full name is used in the subsystem configuration, such as the server.xml file. For example:
serverCert="nethsm:Server-Cert cert-instance_ID
A single HSM can be used to store certificates and keys for mulitple subsystem instances, which may be installed on multiple hosts. When an HSM is used, any certificate nickname for a subsystem must be unique for every subsystem instance managed on the HSM.
Certificate System supports two types of HSM, nShield Connect XC and Luna.
13.2. Renewing subsystem certificates
For details about renewing subsystem certificates, see Section 3.4.1, “The renewal process”.
The process for renewing a subsystem certificate is the same as for renewing a user certificate.
To renew a system certificate, submit the request using the corresponding enrollment profile when using the HttpClient utility. For details about the different system certificate profiles, see Section 5.3.2.1, “Obtaining system and server certificates”.
13.2.1. Renewing certificates using certutil
certutil can be used to generate a certificate request using an existing key pair in the certificate database. The new certificate request can then be submitted through the regular profile pages for the CA to issue a renewed certificate.
Encryption and signing certificates are created in a single step. However, the renewal process only renews one certificate at a time.
To renew both certificates in a certificate pair, each one has to be renewed individually.
Get the password for the token database.
# cat /var/lib/pki/instance_name/conf/password.conf internal=263163888660Open the certificate database directory of the instance whose certificate is being renewed.
# cd /var/lib/pki/instance_name/aliasList the key and nickname for the certificate being renewed. In order to renew a certificate, the key pairs used to generate and the subject name given to the new certificate must be the same as the one in the old certificate.
# certutil -K -d . certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services" Enter Password or Pin for "NSS Certificate DB": < 0> rsa 69481646e38a6154dc105960aa24ccf61309d37d caSigningCert cert-pki-tomcat CACopy the
aliasdirectory as a backup, then delete the original certificate from the certificate database. For example:# certutil -D -n "ServerCert cert-example" -d .Run the
certutilcommand with the options set to the values in the existing certificate.# certutil -d . -R -n "NSS Certificate DB:cert-pki-tomcat CA" -s "cn=CA Authority,o=Example Domain" -a -o example.req2.txtThe difference between generating a new certificate and key pair and renewing the certificate is the value of the -n option. To generate an entirely new request and key pair, then -k sets the key type and is used with -g, which sets the bit length. For a renewal request, the -n option uses the certificate nickname to access the existing key pair stored in the security database.
For further details about the parameters, see the
certutil(1)man page.- Submit the certificate request and then retrieve it and install it, as described in Section 5.3, “Requesting and receiving certificates using CMC”.
13.2.2. Renewing expired Certificate System server certificates
Certificate System does not automatically renew its server certificates online while the PKI server is running. In general, administrators should renew the system certificates before they expire. However, if a system certificate expires, Certificate System will fail to start.
To renew system certificates after expiration, you can set up a temporary server certificate:
If the system certificate is expired:
Create a temporary certificate:
# pki-server cert-create sslserver --tempImport the temporary certificate into Certificate System’s Network Security Services (NSS) database:
# pki-server cert-import sslserverStart Certificate System:
# pki-server start instance_name
Display the certificates and note the ID of the expired system certificate:
# pki-server cert-findCreate the new permanent certificate:
# pki-server cert-create certificate_IDStop Certificate System:
# pki-server stop instance_nameImport the new certificate to replace the expired certificate:
# pki-server cert-import certificate_IDStart Certificate System:
# pki-server start instance_name
13.3. Changing the Names of Subsystem Certificates
One alternative to renewing certificates is replacing them with new certificates, meaning that a new certificate is generated with new keys. Generally, a new certificate can be added to the database and the old one deleted, a simple one-to-one swap. This is possible because the individual subsystem servers identify certificates based on their nickname; as long as the certificate nickname remains the same, the server can find the required certificate even if other factors -like the subject name, serial number, or key -are different.
However, in some situations, the new certificate may have a new certificate nickname, as well. In that case, the certificate nickname needs to be updated in all of the required settings in the subsystem’s CS.cfg configuration file.
Always restart a subsystem after editing the CS.cfg file.
These tables list all of the configuration parameters for each of the subsystem’s certificates:
| CA Signing Certificate |
|
| OCSP Signing Certificate |
|
| Subsystem Certificate |
|
| Server Certificate |
|
| Audit Signing Certificate |
|
| Transport Certificate |
|
| Storage Certificate |
|
| Server Certificate |
|
| Subsystem Certificate |
|
| Audit Log Signing Certificate |
|
| OCSP Signing Certificate |
|
| Server Certificate |
|
| Subsystem Certificate |
|
| Audit Log Signing Certificate |
|
| KRA Transport Certificate[a] |
|
| Server Certificate |
|
| Subsystem Certificate |
|
| Audit Log Signing Certificate |
|
[a]
This needs to be changed in the TKS configuration if the KRA transport certificate nickname changes, even if the TKS certificates all stay the same.
| |
| Server Certificate |
|
| Subsystem Certificate |
|
| Audit Log Signing Certificate |
|
13.4. Using cross-pair certificates
In the late 1990s, as the US government began enhancing its public key infrastructure, it became apparent that branches of government with their own, separate PKI deployments still needed to be able to recognize and trust each others certificates as if the certificates were issued from their own CA. (The method of getting certificates trusted outside a network for external clients to use is a serious, not easily resolved issue for any PKI administrator.)
The US government devised a standard for issuing cross-pair certificates called the Federal Bridge Certificate Authority. These certificates are also called bridge certificates, for obvious reasons. Bridge or cross-pair certificates are CA signing certificate that are framed as dual certificate pairs, similar to encryption and signing certificate pairs for users, only each certificate in the pair is issued by a different CA. Both partner CAs store the other CA signing certificate in its database, so all of the certificates issued within the other PKI are trusted and recognized.
Bridging certificates honors certificates issued by a CA that is not chained to the root CA in its own PKI. By establishing a trust between the Certificate System CA and another CA through a cross-pair CA certificate, the cross-pair certificate can be downloaded and used to trust the certificates issued by the other CA, just as downloading and installing a single CA certificate trusts all certificates issued by the CA.
The Certificate System can issue, import, and publish cross-pair CA certificates. A special profile must be created for issuing cross-pair certificates, and then the certificates can be requested and installed for the CA using the Certificate Wizard for the CA subsystem.
For more information on creating cross-pair certificate profiles, see the Configuring Cross-Pair profiles in the Planning, Installation and Deployment Guide (Common Criteria Edition).
For more information on publishing cross-pair certificates, see Section 7.8, “Publishing cross-pair certificates”.
13.4.1. Installing cross-pair certificates
Both cross-pair certificates can be imported into the Certificate System databases using the certutil tool or by selecting the Cross-Pair Certificates option from the Certificate Setup Wizard, as described in Section 13.5.1, “Installing certificates in the Certificate System database”.
When both certificates have been imported into the database, a crossCertificatePair entry is formed and stored in the database. The original individual cross-pair CA certificates are deleted once the crossCertificatePair entry is created.
13.4.2. Searching for cross-pair certificates
Both CAs in bridge certificates can store or publish the cross-pair certificates as a crossCertificatePair entry in an LDAP database. The Certificate Manager’s internal database can be searched for the crossCertificatePair entry with ldapsearch.
/usr/lib[64]/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "o=server.example.com-pki-ca" -s sub "(crossCertificatePair=*)"
13.5. 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 13.5.1, “Installing certificates in the Certificate System database”.
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.
13.5.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.
13.5.1.1. Installing certificates through the console
pkiconsole is being deprecated and will be replaced by a new browser-based UI in a future major release. Although pkiconsole will continue to be available until the replacement UI is released, we encourage using the command line equivalent of pkiconsole at this time, as the pki CLI will continue to be supported and improved upon even when the new browser-based UI becomes available in the future.
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:
Open the console.
# pkiconsole -d nssdb -n 'optional client cert nickname' 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 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.
To install a certificate in the Local Certificates tab, click . To install a certificate in the CA Certificates tab, click . Both will open the Certificate Setup Wizard.
- When the wizard opens, select the Install a certificate radio button, and click .
- 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----- MIICKzCCAZSgAwIBAgIBAzANgkqkiG9w0BAQQFADA3MQswCQYDVQQGEw JVUzERMA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncy BDQTAeFw05NzEwMTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBg NVBAYTAlVTMREwDwYDVQQKEwhOZXRzY2FwZTENMAsGA1UECxMEUHawcz EXMBUGA1UEAxMOU3Vwcml5YSBTaGV0dHkwgZ8wDQYJKoZIhdfNAQEBBQ ADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG7SdATYzBcABu1AVyd7 chRFOGD3wNktbf6hRo6EAmM5R1Askzf8AW7LiQZBcrXpc0k4du+2j6xJ u2MPm8WKuMOTuvzpo+SGXelmHVChEqooCwfdiZywyZNmgaMa2MS6pUkf QVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgD -----END CERTIFICATE-----
The wizard displays the certificate details. Review the fingerprint to make sure this is the correct certificate, or use the 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 Section 13.6, “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.
13.5.1.2. Installing certificates using certutil
To install subsystem certificates in the Certificate System instance’s security databases using certutil, do the following:
Open the subsystem’s security database directory.
# cd /var/lib/pki/instance_name/aliasRun 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_fileNoteIf the Certificate System 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.
13.5.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.
13.5.1.4. 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.
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.
13.5.1.4.1. Viewing Database Content through the Console
pkiconsole is being deprecated and will be replaced by a new browser-based UI in a future major release. Although pkiconsole will continue to be available until the replacement UI is released, we encourage using the command line equivalent of pkiconsole at this time, as the pki CLI will continue to be supported and improved upon even when the new browser-based UI becomes available in the future.
To view the contents of the database through the administrative console, do the following:
Open the subsystem console.
# pkiconsole -d nssdb -n 'optional client cert nickname' 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 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 image::cert-db1.png[]
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 . This opens a window which shows the serial number, validity period, subject name, issuer name, and certificate fingerprint of the certificate.
13.5.1.5. 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,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/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.
13.5.2. Deleting certificates from the database
Removing unwanted certificates reduces the size of the certificate database.
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 13.6, “Changing the trust settings of a CA certificate”.
13.5.2.1. Deleting certificates through the console
pkiconsole is being deprecated and will be replaced by a new browser-based UI in a future major release. Although pkiconsole will continue to be available until the replacement UI is released, we encourage using the command line equivalent of pkiconsole at this time, as the pki CLI will continue to be supported and improved upon even when the new browser-based UI becomes available in the future.
To delete a certificate through the Console, do the following:
Open the subsystem console.
# pkiconsole -d nssdb -n 'optional client cert nickname' 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 .
- When prompted, confirm the deletion.
13.5.2.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,u Server-Cert cert-instance_name u,u,uDelete the certificate by running the
certutilwith the-Doption.# certutil -D -d . -n certificate_nicknameFor 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.
13.6. Changing the trust settings of a CA certificate
Certificate System subsystems use the CA certificates in their certificate databases to validate certificates received during an SSL-enabled communication.
It can be necessary to change the trust settings on a CA stored in the certificate database, temporarily or permanently. For example, if there is a problem with access or compromised certificates, marking the CA certificate as untrusted prevents entities with certificates signed by that CA from authenticating to the Certificate System. When the problem is resolved, the CA can be marked as trusted again.
To untrust a CA permanently, consider removing its certificate from the trust database. For instructions, see Section 13.5.2, “Deleting certificates from the database”.
13.6.1. Changing trust settings through the console
pkiconsole is being deprecated and will be replaced by a new browser-based UI in a future major release. Although pkiconsole will continue to be available until the replacement UI is released, we encourage using the command line equivalent of pkiconsole at this time, as the pki CLI will continue to be supported and improved upon even when the new browser-based UI becomes available in the future.
To change the trust setting of a CA certificate, do the following:
Open the subsystem console.
# pkiconsole -d nssdb -n 'optional client cert nickname' https://server.example.com:secure_port/subsystem_type- In the Configuration tab, System Keys and Certificates from the left navigation tree.
- Select the CA certificates tab.
- Select the CA certificate to modify, and click .
A prompt opens which reads The Certificate chain is (un)trusted, are you sure you want to (un)trust it?
Clicking yes changes the trust setting of the certificate chain; pressing no preserves the original trust relationship.
13.6.2. Changing trust settings using certutil
To change the trust setting of a certificate using certutil, do the following:
Open the instance’s certificate databases directory.
# cd /var/lib/pki/instance_name/aliasList 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,u Server-Cert cert-instance_name u,u,uChange the trust settings for the certificate by running the
certutilwith the-Moption.# certutil -M -n cert_nickname -t trust -d .For example:
# certutil -M -n "Certificate Authority - Example Domain" -t TCu,TCu,TCu -d .List the certificates again to confirm that the certificate trust was changed.
# certutil -L -d . Certificate Authority - Example Domain CTu,CTu,CTu subsystemCert cert-instance_name u,u,u Server-Cert 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.
13.7. Managing tokens used by the subsystems
Certificate System manages two groups of tokens: tokens used by the subsystems to perform PKI tasks and tokens issued through the subsystem. These management tasks refer specifically to tokens that are used by the subsystems.
13.7.1. Detecting tokens
To see if a token can be detected by Certificate System to be installed or configured, use the TokenInfo utility. For example:
TokenInfo /var/lib/pki/instance_name/alias Database Path: /var/lib/pki/instance_name/alias Found external module 'NSS Internal PKCS #11 Module'
This utility will return all tokens which can be detected by the Certificate System, not only tokens which are installed in the Certificate System.
13.7.1.1. Viewing tokens
To view a list of the tokens currently installed for a Certificate System instance, use the modutil utility.
Open the instance
aliasdirectory. For example:cd /var/lib/pki/instance_name/alias
Show the information about the installed PKCS #11 modules installed as well as information on the corresponding tokens using the
modutiltool.modutil -dbdir . -nocertdb -list
13.7.2. Changing a token’s password
The token, internal or external, that stores the key pairs and certificates for the subsystems is protected (encrypted) by a password. To decrypt the key pairs or to gain access to them, enter the token password. This password is set when the token is first accessed, usually during Certificate System installation.
It is good security practice to change the password that protects the server’s keys and certificates periodically. Changing the password minimizes the risk of someone finding out the password. To change a token’s password, use the certutil command-line utility.
For information about certutil, see http://www.mozilla.org/projects/security/pki/nss/tools/.
The single sign-on password cache stores token passwords in the password.conf file. This file must be manually updated every time the token password is changed. For more information on managing passwords through the password.conf file, see 9.3 Managing system passwords in the Planning, Installation and Deployment Guide (Common Criteria Edition).
