Administration Guide (Common Criteria Edition)

PDF

Red Hat Certificate System 9

Updated for Red Hat Certificate System 9.4 Common Criteria Certification

Edition 9.4-1

Red Hat

Customer Content Services

Legal Notice

February 2021

Abstract

This guide covers all aspects of installing, configuring, and managing Certificate System 9.4 in a Common Criteria environment. It also covers management tasks such as adding users; requesting, renewing, and revoking certificates; publishing CRLs; and managing smart cards. This guide is intended for Certificate System administrators.

Chapter 1. Overview of Red Hat Certificate System Subsystems

Note

This chapter is an overview of Red Hat Certificate System and the various subsystems. For details on evaluated product features, please see the NIAP Product Compliant List at https://www.niap-ccevs.org/Product/PCL.cfm.

Note

Network security services (NSS) and Federal Information Processing Standard (FIPS) hardware security modules (HSM) were the only evaluated cryptographic providers.

Every common PKI operation — issuing, renewing and revoking certificates; archiving and recovering keys; publishing CRLs and verifying certificate status — is carried out by interoperating subsystems within Red Hat Certificate System. The functions of each individual subsystem and the way that they work together to establish a robust and local PKI are described in this chapter.

1.1. Uses for Certificates

The purpose of certificates is to establish trust. Their usage varies depending on the kind of trust they are used to ensure. Some kinds of certificates are used to verify the identity of the presenter; others are used to verify that an object or item has not been tampered with.

For information on how certificates are used, the types of certificates, or how certificates establish identities and relationships, see the Certificates and Authentication section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).

1.2. A Review of Certificate System Subsystems

Red Hat Certificate System provides five different subsystems, each focusing on different aspects of a PKI deployment. These subsystems work together to create a public key infrastructure (PKI). Depending on what subsystems are installed, a PKI can function as a token management system (TMS) or a non token management system. For descriptions of the subsystems and TMS and non-TMS environments, see the A Review of Certificate System Subsystems in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).

1.3. A Look at Managing Certificates (Non-TMS)

A conventional PKI environment provides the basic framework to manage certificates stored in software databases. This is a non-TMS environment, since it does not manage certificates on smart cards. At a minimum, a non-TMS requires only a CA, but a non-TMS environment can use OCSP responders and KRA instances as well.

For information on this topic, see the following sections in Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition):

Managing Certificates
Using a Single Certificate Manager
Planning for Lost Keys: Key Archival and Recovery
Balancing Certificate Request Processing
Balancing Client OCSP Requests

1.4. A Look at the Token Management System (TMS)

Note

Features in this section on TMS are not tested in the evaluation. This section is for reference only.

Certificate System creates, manages, renews, and revokes certificates, and it also archives and recovers keys. For organizations that use smart cards, the Certificate System has a token management system — a collection of subsystems with established relationships — to generate keys and requests and receive certificates to be used for smart cards.

For information on this topic, see the following sections in Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition):

Working with Smart Cards (TMS)
Using Smart Cards

1.5. Red Hat Certificate System services

There are various different interfaces for managing certificates and subsystems, depending on the user's role: administrators, agents, auditors, and end users. For an overview of the different functions that are performed through each interface, see Red Hat Certificate System User Interfaces section in the Red Hat Certificate System 9 Planning, Installation, and Deployment Guide (Common Criteria Edition).

Part I. Red Hat Certificate System User Interfaces

Chapter 2. User Interfaces

There are different interfaces for managing certificates and subsystems, depending on the user's role: administrators, agents, auditors, and end users.

2.1. User Interfaces Overview

Administrators can use the following interfaces to securely interact with a completed Certificate System installation:

The PKI command-line interface and other command-line utilities
The PKI Console graphical interface
The Certificate System web interface.

These interfaces require configuration prior to use for secure communication with the Certificate System server over TLS. Using these clients without proper configuration is not allowed. Some of these tools use TLS client authentication. When required, their required initialization procedure includes configuring this. Which interface is used depends on the administrator's preferences and functionality available. Common actions using these interfaces are described in the remainder of the guide after this chapter.

By default, the PKI command-line interface uses the NSS database in the user's ~/.dogtag/nssdb/ directory. Section 2.5.1.1, “pki CLI Initialization” provides detailed steps for initializing the NSS database with the administrator's certificate and key. Some examples of using the PKI command-line utility are described in Section 2.5.1.2, “Using "pki" CLI”. Additional examples are shown through the rest of the guide.

Interfacing with Certificate System (as an administrator in other user roles) can be done using various command-line utilities to submit CMC requests, manage generated certificates, and so on. These are described briefly in Section 2.5, “Command Line Interfaces”, such as Section 2.5.2, “AtoB”. These utilities are utilized in later sections such as Section 5.2.2, “Creating a CSR Using PKCS10Client”.

Certificate System's PKI Console interface is a graphical interface. Section 2.3.1, “pkiconsole Initialization” describes how to initialize it. Section 2.3.2, “Using pkiconsole for CA, OCSP, KRA, and TKS Subsystems” gives an overview of using the console interface. Later sections, such as Section 3.2.2, “Managing Certificate Enrollment Profiles Using the Java-based Administration Console” go into greater detail for specific operations.

The Certificate System web interface allows administrative access through the Firefox web browser. Section 2.4.1, “Browser Initialization” describes instructions about configuring the client authentication. Other sections in Section 2.4, “Web Interface” describe using the web interface of Certificate System. More information about using the browser for specific tasks are included in the rest of the documentation, such as Section 6.2.2.2, “Searching for Certificates (Advanced)”.

Note

To terminate a PKI Console session, click the Exit button. To terminate a web browser session, close the browser. A command-line utility terminates itself as soon as it performs the action and returns to the prompt, so no action is needed on the administrator's part to terminate the session.

2.2. Client NSS Database Initialization

On Red Hat Certificate System, certain interfaces may need to access the server using TLS client certificate authentication (mutual authentication). Before performing server-side admin tasks, you need to:

Prepare an NSS database for the client. This can be a new database or an existing one.
Import the CA certificate chain and trust them.
Have a certificate and corresponding key. They can be generated in the NSS database or imported from somewhere else, such as from a PKCS #12 file.

Based on the utility, you need to initialize the NSS database accordingly. See:

Section 2.5.1.1, “pki CLI Initialization”
Section 2.3.1, “pkiconsole Initialization”
Section 2.4.1, “Browser Initialization”

2.3. Graphical Interface

pkiconsole is a graphical interface that is designed for users with the Administrator role privilege to manage the subsystem itself. This includes adding users, configuring logs, managing profiles and plug-ins, and the internal database, among many other functions. This utility communicates with the Certificate System server via TLS using client-authentication and can be used to manage the server remotely.

2.3.1. `pkiconsole` Initialization

To use the pkiconsole interface for the first time, specify a new password and use the following command:

$ pki -c password -d ~/.redhat-idm-console client-init

This command creates a new client NSS database in the ~/.redhat-idm-console/ directory.

To import the CA certificate into the PKI client NSS database, see Section 11.2, “Importing a Root Certificate”.

To request a new client certificate, see Chapter 5, Requesting, Enrolling, and Managing Certificates.

Execute the following command to extract the admin client certificate from the .p12 file:

$ openssl pkcs12 -in file -clcerts -nodes -nokeys -out file.crt

Validate and import the admin client certificate as described in Chapter 11, Managing Certificate/Key Crypto Token:

$ PKICertImport -d ~/.redhat-idm-console -n "nickname" -t ",," -a -i file.crt -u C

Important

Make sure all intermediate certificates and the root CA certificate have been imported before importing the CA admin client certificate.

To import an existing client certificate and its key into the client NSS database:

$ pki -c password -d ~/.redhat-idm-console pkcs12-import --pkcs12-file file --pkcs12-password pkcs12-password

Verify the client certificate with the following command:

$ certutil -V -u C -n "nickname" -d ~/.redhat-idm-console

2.3.2. Using `pkiconsole` for CA, OCSP, KRA, and TKS Subsystems

The Java console is used by four subsystems: the CA, OCSP, KRA, and TKS. The console is accessed using a locally-installed pkiconsole utility. It can access any subsystem because the command requires the host name, the subsystem's administrative TLS port, and the specific subsystem type.

pkiconsole https://server.example.com:admin_port/subsystem_type

If DNS is not configured, you can use an IPv4 or IPv6 address to connect to the console. For example:

https://192.0.2.1:8443/ca
https://[2001:DB8::1111]:8443/ca

This opens a console, as in Figure 2.1, “Certificate System Console”.

Figure 2.1. Certificate System Console

The Configuration tab controls all of the setup for the subsystem, as the name implies. The choices available in this tab are different depending on which subsystem type the instance is; the CA has the most options since it has additional configuration for jobs, notifications, and certificate enrollment authentication.

All subsystems have four basic options:

Users and groups
Access control lists
Log configuration
Subsystem certificates (meaning the certificates issued to the subsystem for use, for example, in the security domain or audit signing)

The Status tab shows the logs maintained by the subsystem.

2.4. Web Interface

2.4.1. Browser Initialization

This section explains browser initialization for Firefox to access PKI services.

Importing a CA Certificate

Click Menu → Preferences → Privacy & Security → View certificates.
Select the Authorities tab and click the Import button.
Select the ca.crt file and click Import.

Importing a Client Certificate

Click Options → Preferences → Privacy & Security → View certificates.
Select the Your Certificates tab.
Click on Import and select the client p12 file, such as ca_admin_cert.p12.
Enter the password for the client certificate on the prompt.
Click OK.
Verify that an entry is added under Your Certificates.

Accessing the Web Console

You can access the PKI services by opening https://host_name:port in your browser.

2.4.2. The Administrative Interfaces

The all subsystems use HTML-based administrative interface. It is accessed by entering the host name and secure port as the URL, authenticating with the administrator's certificate, and clicking the appropriate Administrators link.

Note

There is a single TLS port for all subsystems which is used for both administrator and agent services. Access to those services is restricted by certificate-based authentication.

The HTML admin interface is much more limited than the Java console; the primary administrative function is managing the subsystem users.

The TPS only allows operations to manage users for the TPS subsystem. However, the TPS admin page can also list tokens and display all activities (including normally-hidden administrative actions) performed on the TPS.

Figure 2.2. TPS Admin Page

2.4.3. Agent Interfaces

The agent services pages are where almost all of the certificate and token management tasks are performed. These services are HTML-based, and agents authenticate to the site using a special agent certificate.

Figure 2.3. Certificate Manager's Agent Services Page

The operations vary depending on the subsystem:

The Certificate Manager agent services include approving certificate requests (which issues the certificates), revoking certificates, and publishing certificates and CRLs. All certificates issued by the CA can be managed through its agent services page.
The TPS agent services, like the CA agent services, manages all of the tokens which have been formatted and have had certificates issued to them through the TPS. Tokens can be enrolled, suspended, and deleted by agents. Two other roles (operator and admin) can view tokens in web services pages, but cannot perform any actions on the tokens.
KRA agent services pages process key recovery requests, which set whether to allow a certificate to be issued reusing an existing key pair if the certificate is lost.
The OCSP agent services page allows agents to configure CAs which publish CRLs to the OCSP, to load CRLs to the OCSP manually, and to view the state of client OCSP requests.

The TKS is the only subsystem without an agent services page.

2.4.4. End User Pages

The CA and TPS both process direct user requests in some way. That means that end users have to have a way to connect with those subsystems. The CA has end-user, or end-entities, HTML services. The TPS uses the Enterprise Security Client.

The end-user services are accessed over standard HTTP using the server's host name and the standard port number; they can also be accessed over HTTPS using the server's host name and the specific end-entities TLS port.

For CAs, each type of TLS certificate is processed through a specific online submission form, called a profile. There are about two dozen certificate profiles for the CA, covering all sorts of certificates — user TLS certificates, server TLS certificates, log and file signing certificates, email certificates, and every kind of subsystem certificate. There can also be custom profiles.

Figure 2.4. Certificate Manager's End-Entities Page

End users retrieve their certificates through the CA pages when the certificates are issued. They can also download CA chains and CRLs and can revoke or renew their certificates through those pages.

2.5. Command Line Interfaces

This section discusses command-line utilities.

2.5.1. "pki" CLI

The pki command-line interface (CLI) provides access to various services on the server using the REST interface (see the REST Interface section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition)). The CLI can be invoked as follows:

$ pki [CLI options] <command> [command parameters]

Note that the CLI options must be placed before the command, and the command parameters after the command.

2.5.1.1. pki CLI Initialization

To use the command line interface for the first time, specify a new password and use the following command:

$ pki -c <password> client-init

This will create a new client NSS database in the ~/.dogtag/nssdb directory. The password must be specified in all CLI operations that uses the client NSS database. Alternatively, if the password is stored in a file, you can specify the file using the -C option. For example:

$ pki -C password_file client-init

To import the CA certificate into the client NSS database refer to Section 11.2, “Importing a Root Certificate”.

Some commands may require client certificate authentication. To import an existing client certificate and its key into the client NSS database, specify the PKCS #12 file and the password, and execute the following command:

Execute the following command to extract the admin client certificate from the .p12 file:

$ openssl pkcs12 -in file -clcerts -nodes -nokeys -out file.crt

Validate and import the admin client certificate as described in Chapter 11, Managing Certificate/Key Crypto Token:

$ PKICertImport -d ~/.dogtag/nssdb -n "nickname" -t ",," -a -i file.crt -u C

Important

Make sure all intermediate certificates and the root CA certificate have been imported before importing the CA admin client certificate.

To import an existing client certificate and its key into the client NSS database, specify the PKCS #12 file and the password, and execute the following command:

$ pki -c <password> pkcs12-import --pkcs12-file <file> --pkcs12-password <password>

Verify the client certificate with the following command:

certutil -V -u C -n "nickname" -d ~/.dogtag/nssdb

2.5.1.2. Using "pki" CLI

The command line interface supports a number of commands organized in a hierarchical structure. To list the top-level commands, execute the pki command without any additional commands or parameters:

$ pki

Some commands have subcommands. To list them, execute pki with the command name and no additional options. For example:

$ pki ca

$ pki ca-cert

To view command usage information, use the --help option:

$ pki --help

$ pki ca-cert-find --help

To view manual pages, specify the command line help command:

$ pki help

$ pki help ca-cert-find

To execute a command that does not require authentication, specify the command and its parameters (if required), for example:

$ pki ca-cert-find

To execute a command that requires client certificate authentication, specify the certificate nickname, the client NSS database password, and optionally the server URL:

$ pki -U <server URL> -n <nickname> -c <password> <command> [command parameters]

For example:

$ pki -n jsmith -c password ca-user-find ...

By default, the CLI communicates with the server at http://local_host_name:8080. To communicate with a server at a different location, specify the URL with the -U option, for example:

$ pki -U https://server.example.com:8443 -n jsmith -c password ca-user-find

2.5.2. AtoB

The AtoB utility decodes the Base64-encoded certificates to their binary equivalents. For example:

$ AtoB input.ascii output.bin

For further details, more options, and additional examples, see the AtoB(1) man page.

2.5.3. AuditVerify

The AuditVerify utility verifies integrity of the audit logs by validating the signature on log entries.

Example:

$ AuditVerify -d ~jsmith/auditVerifyDir -n Log Signing Certificate -a ~jsmith/auditVerifyDir/logListFile -P "" -v

The example verifies the audit logs using the Log Signing Certificate (-n) in the ~jsmith/auditVerifyDir NSS database (-d). The list of logs to verify (-a) are in the ~jsmith/auditVerifyDir/logListFile file, comma-separated and ordered chronologically. The prefix (-P) to prepend to the certificate and key database file names is empty. The output is verbose (-v).

For further details, more options, and additional examples, see the AuditVerify(1) man page or 14.2.2. Using Signed Audit Logs in the Red Hat Certificate System Administration Guide.

2.5.4. BtoA

The BtoA utility encodes binary data in Base64. For example:

$ BtoA input.bin output.ascii

For further details, more options, and additional examples, see the BtoA(1) man page.

2.5.5. CMCRequest

The CMCRequest utility creates a certificate issuance or revocation request. For example:

$ CMCRequest example.cfg

Note

All options to the CMCRequest utility are specified as part of the configuration filed passed to the utility. See the CMCRequest(1) man page for configuration file options and further information. Also see 4.3. Requesting and Receiving Certificates Using CMC and 6.2.1. Revoking a Certificate Using CMCRequest in Red Hat Certificate System Administration Guide.

2.5.6. CMCRevoke

Legacy. Do not use.

2.5.7. CMCSharedToken

The CMCSharedToken utility encrypts a user passphrase for shared-secred CMC requests. For example:

$ CMCSharedToken -d . -p myNSSPassword -s "shared_passphrase" -o cmcSharedTok2.b64 -n "subsystemCert cert-pki-tomcat"

The shared passphrase (-s) is encrypted and stored in the cmcSharedtok2.b64 file (-o) using the certificate named subsystemCert cert-pki-tomcat (-n) found in the NSS database in the current directory (-d). The default security token internal is used (as -h is not specified) and the token password of myNSSPassword is used for accessing the token.

For further details, more options, and additional examples, see the CMCSharedtoken(1) man page and also 8.1.3.1. Creating a Shared Secret Token in Red Hat Certificate System Administration Guide.

2.5.8. CRMFPopClient

The CRMFPopClient utility is Certificate Request Message Format (CRMF) client using NSS databases and supplying Proof of Possession.

Example:

$ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" -t false -v -o /user_or_entity_database_directory/example.csr

This example creates a new CSR with the cn=subject_name subject DN (-n), NSS database in the current directory (-d), certificate to use for transport kra.transport (-b), the AES/CBC/PKCS5Padding key wrap algorithm verbose output is specified (-v) and the resulting CSR is written to the /user_or_entity_database_directory/example.csr file (-o).

For further details, more options, and additional examples, see the output of the CRMFPopClient --help command and also 4.2.4. Creating a CSR Using CRMFPopClient in Red Hat Certificate System Administration Guide.

2.5.9. HttpClient

The HttpClient utility is an NSS-aware HTTP client for submitting CMC requests.

Example:

$ HttpClient request.cfg

Note

All parameters to the HttpClient utility are stored in the request.cfg file. For further information, see the output of the HttpClient --help command.

2.5.10. OCSPClient

An Online Certificate Status Protocol (OCSP) client for checking the certificate revocation status.

Example:

$ OCSPClient -h server.example.com -p 8080 -d /etc/pki/pki-tomcat/alias -c "caSigningCert cert-pki-ca" --serial 2

This example queries the server.example.com OCSP server (-h) on port 8080 (-p) to check whether the certificate signed by caSigningcet cert-pki-ca (-c) with serial number 2 (--serial) is valid. The NSS database in the /etc/pki/pki-tomcat/alias directory is used.

For further details, more options, and additional examples, see the output of the OCSPClient --help command.

2.5.11. PKCS10Client

The PKCS10Client utility creates a CSR in PKCS10 format for RSA and EC keys, optionally on an HSM.

Example:

$ PKCS10Client -d /etc/dirsrv/slapd-instance_name/ -p password -a rsa -l 2048 -o ~/ds.csr -n "CN=$HOSTNAME"

This example creates a new RSA (-a) key with 2048 bits (-l) in the /etc/dirsrv/slapd-instance_name/ directory (-d with database password password (-p). The output CSR is stored in the ~/ds.cfg file (-o) and the certificate DN is CN=$HOSTNAME (-n).

For further details, more options, and additional examples, see the PKCS10Client(1) man page.

2.5.12. PrettyPrintCert

The PrettyPrintCert utility displays the contents of a certificate in a human-readable format.

Example:

$ PrettyPrintCert ascii_data.cert

This command parses the output of the ascii_data.cert file and displays its contents in human readable format. The output includes information like signature algorithm, exponent, modulus, and certificate extensions.

For further details, more options, and additional examples, see the PrettyPrintCert(1) man page.

2.5.13. PrettyPrintCrl

The PrettyPrintCrl utility displays the content of a CRL file in a human readable format.

Example:

$ PrettyPrintCrl ascii_data.crl

This command parses the output of the ascii_data.crl and displays its contents in human readable format. The output includes information, such as revocation signature algorithm, the issuer of the revocation, and a list of revoked certificates and their reason.

For further details, more options, and additional examples, see the PrettyPrintCrl(1) man page.

2.5.14. TokenInfo

The TokenInfo utility lists all tokens in an NSS database.

Example:

$ TokenInfo ./nssdb/

This command lists all tokens (HSMs, soft tokens, and so on) registered in the specified database directory.

For further details, more options, and additional examples, see the output of the TokenInfo command

2.5.15. tkstool

The tkstool utility is interacting with the token Key Service (TKS) subsystem.

Example:

$ tkstool -M -n new_master -d /var/lib/pki/pki-tomcat/alias -h token_name

This command creates a new master key (-M) named new_master (-n) in the /var/lib/pki/pki-tomcat/alias NSS database on the HSM token_name

For further details, more options, and additional examples, see the output of the tkstool -H command.

Part II. Setting up Certificate Services

Note

Modification of CS.cfg, server.xml or any configuration file post-installation is expressly prohibited in a certified environment.

Chapter 3. Making Rules for Issuing Certificates (Certificate Profiles)

The Certificate System provides a customizable framework to apply policies for incoming certificate requests and to control the input request types and output certificate types; these are called certificate profiles. Certificate profiles set the required information for certificate enrollment forms in the Certificate Manager end-entities page. This chapter describes how to configure certificate profiles.

3.1. About Certificate Profiles

A certificate profile defines everything associated with issuing a particular type of certificate, including the authentication method, the authorization method, the default certificate content, constraints for the values of the content, and the contents of the input and output for the certificate profile. Enrollment and renewal requests are submitted to a certificate profile and are then subject to the defaults and constraints set in that certificate profile. These constraints are in place whether the request is submitted through the input form associated with the certificate profile or through other means. The certificate that is issued from a certificate profile request contains the content required by the defaults with the information required by the default parameters. The constraints provide rules for what content is allowed in the certificate.

For details about using and customizing certificate profiles, see Section 3.2, “Setting up Certificate Profiles”.

The Certificate System contains a set of default profiles. While the default profiles are created to satisfy most deployments, every deployment can add their own new certificate profiles or modify the existing profiles.

Authentication. In every certification profile can be specified an authentication method.
Authorization. In every certification profile can be specified an authorization method.
Profile inputs. Profile inputs are parameters and values that are submitted to the CA when a certificate is requested. Profile inputs include public keys for the certificate request and the certificate subject name requested by the end entity for the certificate.
Profile outputs. Profile outputs are parameters and values that specify the format in which to provide the certificate to the end entity. Profile outputs are CMC responses which contain a PKCS#7 certificate chain, when the request was successful.
Certificate content. Each certificate defines content information, such as the name of the entity to which it is assigned (the subject name), its signing algorithm, and its validity period. What is included in a certificate is defined in the X.509 standard. With version 3 of the X509 standard, certificates can also contain extensions. For more information about certificate extensions, see Section B.3, “Standard X.509 v3 Certificate Extension Reference”.
All of the information about a certificate profile is defined in the set entry of the profile policy in the profile's configuration file. When multiple certificates are expected to be requested at the same time, multiple set entries can be defined in the profile policy to satisfy needs of each certificate. Each policy set consists of a number of policy rules and each policy rule describes a field in the certificate content. A policy rule can include the following parts:
- Profile defaults. These are predefined parameters and allowed values for information contained within the certificate. Profile defaults include the validity period of the certificate, and what certificate extensions appear for each type of certificate issued.
- Profile constraints. Constraints set rules or policies for issuing certificates. Amongst other, profile constraints include rules to require the certificate subject name to have at least one CN component, to set the validity of a certificate to a maximum of 360 days, to define the allowed grace period for renewal, or to require that the subjectaltname extension is always set to true.

3.1.1. The Enrollment Profile

The parameters for each profile defining the inputs, outputs, and policy sets are listed in more detail in Table 11.1. Profile Configuration File Parameters in Red Hat Certificate System Planning, Installation and Deployment Guide.

A profile usually contains inputs, policy sets, and outputs, as illustrated in the caUserCert profile in Example 3.1, “Example caCMCUserCert Profile”.

Example 3.1. Example caCMCUserCert Profile

The first part of a certificate profile is the description. This shows the name, long description, whether it is enabled, and who enabled it.

desc=This certificate profile is for enrolling user certificates by using the CMC certificate request with CMC Signature authentication.
visible=true
enable=true
enableBy=admin
name=Signed CMC-Authenticated User Certificate Enrollment

Note

The missing auth.instance_id= entry in this profile means that with this profile, authentication is not needed to submit the enrollment request. However, manual approval by an authorized CA agent will be required to get an issuance.

Next, the profile lists all of the required inputs for the profile:

input.list=i1
input.i1.class_id=cmcCertReqInputImp

For the caCMCUserCert profile, this defines the certificate request type, which is CMC.

Next, the profile must define the output, meaning the format of the final certificate. The only one available is certOutputImpl, which results in CMC response to be returned to the requestor in case of success.

output.list=o1
output.o1.class_id=certOutputImpl

The last — largest — block of configuration is the policy set for the profile. Policy sets list all of the settings that are applied to the final certificate, like its validity period, its renewal settings, and the actions the certificate can be used for. The policyset.list parameter identifies the block name of the policies that apply to one certificate; the policyset.userCertSet.list lists the individual policies to apply.

For example, the sixth policy populates the Key Usage Extension automatically in the certificate, according to the configuration in the policy. It sets the defaults and requires the certificate to use those defaults by setting the constraints:

policyset.list=userCertSet
policyset.userCertSet.list=1,10,2,3,4,5,6,7,8,9
...
policyset.userCertSet.6.constraint.class_id=keyUsageExtConstraintImpl
policyset.userCertSet.6.constraint.name=Key Usage Extension Constraint
policyset.userCertSet.6.constraint.params.keyUsageCritical=true
policyset.userCertSet.6.constraint.params.keyUsageDigitalSignature=true
policyset.userCertSet.6.constraint.params.keyUsageNonRepudiation=true
policyset.userCertSet.6.constraint.params.keyUsageDataEncipherment=false
policyset.userCertSet.6.constraint.params.keyUsageKeyEncipherment=true
policyset.userCertSet.6.constraint.params.keyUsageKeyAgreement=false
policyset.userCertSet.6.constraint.params.keyUsageKeyCertSign=false
policyset.userCertSet.6.constraint.params.keyUsageCrlSign=false
policyset.userCertSet.6.constraint.params.keyUsageEncipherOnly=false
policyset.userCertSet.6.constraint.params.keyUsageDecipherOnly=false
policyset.userCertSet.6.default.class_id=keyUsageExtDefaultImpl
policyset.userCertSet.6.default.name=Key Usage Default
policyset.userCertSet.6.default.params.keyUsageCritical=true
policyset.userCertSet.6.default.params.keyUsageDigitalSignature=true
policyset.userCertSet.6.default.params.keyUsageNonRepudiation=true
policyset.userCertSet.6.default.params.keyUsageDataEncipherment=false
policyset.userCertSet.6.default.params.keyUsageKeyEncipherment=true
policyset.userCertSet.6.default.params.keyUsageKeyAgreement=false
policyset.userCertSet.6.default.params.keyUsageKeyCertSign=false
policyset.userCertSet.6.default.params.keyUsageCrlSign=false
policyset.userCertSet.6.default.params.keyUsageEncipherOnly=false
policyset.userCertSet.6.default.params.keyUsageDecipherOnly=false
...

3.1.2. Certificate Extensions: Defaults and Constraints

An extension configures additional information to include in a certificate or rules about how the certificate can be used. These extensions can either be specified in the certificate request or taken from the profile default definition and then enforced by the constraints.

A certificate extension is added or identified in a profile by adding the default which corresponds to the extension and sets default values, if the certificate extension is not set in the request. For example, the Basic Constraints Extension identifies whether a certificate is a CA signing certificate, the maximum number of subordinate CAs that can be configured under the CA, and whether the extension is critical (required):

policyset.caCertSet.5.default.name=Basic Constraints Extension Default
policyset.caCertSet.5.default.params.basicConstraintsCritical=true
policyset.caCertSet.5.default.params.basicConstraintsIsCA=true
policyset.caCertSet.5.default.params.basicConstraintsPathLen=-1

The extension can also set required values for the certificate request called constraints. If the contents of a request do not match the set constraints, then the request is rejected. The constraints generally correspond to the extension default, though not always. For example:

policyset.caCertSet.5.constraint.class_id=basicConstraintsExtConstraintImpl
policyset.caCertSet.5.constraint.name=Basic Constraint Extension Constraint
policyset.caCertSet.5.constraint.params.basicConstraintsCritical=true
policyset.caCertSet.5.constraint.params.basicConstraintsIsCA=true
policyset.caCertSet.5.constraint.params.basicConstraintsMinPathLen=-1
policyset.caCertSet.5.constraint.params.basicConstraintsMaxPathLen=-1

Note

To allow user supplied extensions to be embedded in the certificate requests and ignore the system-defined default in the profile, the profile needs to contain the User Supplied Extension Default, which is described in Section B.1.33, “User Supplied Extension Default”.

3.1.3. Inputs and Outputs

Inputs set information that must be submitted to receive a certificate. In a Common Criteria environment, set the input.i1.class_id parameter in all enabled profiles to cmcCertReqInputImpl:

input.i1.class_id=cmcCertReqInputImpl

The outputs configured in the profile define the format of the certificate that is issued. In a Common Criteria environment, set the output.o1.class_id parameter in all enabled profiles to certOutputImpl:

output.o1.class_id=CertOutputImpl

In a Common Criteria-compliant Certificate System environment, users access profiles through the /ca/ee/ca/profileSubmitUserSignedCMCFull servlet that is accessed through the end-entities interface.

3.2. Setting up Certificate Profiles

In Certificate System, you can add, delete, and modify enrollment profiles:

Using the PKI command-line interface
Using the Java-based administration console

This section provides information on each method.

3.2.1. Managing Certificate Enrollment Profiles Using the PKI Command-line Interface

This section describes how to manage certificate profiles using the pki utility. For further details, see the pki-ca-profile(1) man page.

Note

Using the raw format is recommended. For details on each attribute and field of the profile, see the section Creating and Editing Certificate Profiles Directly on the File System in Red Hat Certificate System Planning, Installation and Deployment Guide.

3.2.1.1. Enabling and Disabling a Certificate Profile

Before you can edit a certificate profile, you must disable it. After the modification is complete, you can re-enable the profile.

Note

Only CA agents can enable and disable certificate profiles.

For example, to disable the caCMCECserverCert certificate profile:

# pki -c password -n caagent ca-profile-disable caCMCECserverCert

For example, to enable the caCMCECserverCert certificate profile:

# pki -c password -n caagent ca-profile-enable caCMCECserverCert

3.2.1.2. Creating a Certificate Profile in Raw Format

To create a new profile in raw format:

# pki -c password -n caadmin ca-profile-add profile_name.cfg --raw

Note

In raw format, specify the new profile ID as follows:

profileId=profile_name

3.2.1.3. Editing a Certificate Profile in Raw Format

CA administrators can edit a certificate profile in raw format without manually downloading the configuration file.

For example, to edit the caCMCECserverCert profile:

# pki -c password -n caadmin ca-profile-edit caCMCECserverCert

This command automatically downloads the profile configuration in raw format and opens it in the VI editor. When you close the editor, the profile configuration is updated on the server.

You do not need to restart the CA after editing a profile.

Important

Before you can edit a profile, disable the profile. For details, see Section 3.2.1.1, “Enabling and Disabling a Certificate Profile”.

Example 3.2. Editing a Certificate Profile in RAW Format

For example, to edit the caCMCserverCert profile to accept multiple user-supplied extensions:

Disable the profile as a CA agent:

# pki -c password -n caagemt ca-profile-disable caCMCserverCert

Edit the profile as a CA administrator:
1. Download and open the profile in the VI editor:
```
# pki -c password -n caadmin ca-profile-edit caCMCserverCert
```
2. Update the configuration to accept the extensions. For details, see Example B.3, “Multiple User Supplied Extensions in CSR”.

Enable the profile as a CA agent:

# pki -c password -n caagent ca-profile-enable caCMCserverCert

3.2.1.4. Deleting a Certificate Profile

To delete a certificate profile:

# pki -c password -n caadmin ca-profile-del profile_name

Important

Before you can delete a profile, disable the profile. For details, see Section 3.2.1.1, “Enabling and Disabling a Certificate Profile”.

3.2.2. Managing Certificate Enrollment Profiles Using the Java-based Administration Console

3.2.2.1. Creating Certificate Profiles through the CA Console

For security reasons, the Certificate Systems enforces separation of roles whereby an existing certificate profile can only be edited by an administrator after it was allowed by an agent. To add a new certificate profile or modify an existing certificate profile, perform the following steps as the administrator:

Log in to the Certificate System CA subsystem console.
```
pkiconsole https://server.example.com:8443/ca
```
In the Configuration tab, select Certificate Manager, and then select Certificate Profiles.
The Certificate Profile Instances Management tab, which lists configured certificate profiles, opens.
To create a new certificate profile, click Add.
In the Select Certificate Profile Plugin Implementation window, select the type of certificate for which the profile is being created.
Fill in the profile information in the Certificate Profile Instance Editor.
- Certificate Profile Instance ID. This is the ID used by the system to identify the profile.
- Certificate Profile Name. This is the user-friendly name for the profile.
- Certificate Profile Description.
- End User Certificate Profile. This sets whether the request must be made through the input form for the profile. This is usually set to true. Setting this to false allows a signed request to be processed through the Certificate Manager's certificate profile framework, rather than through the input page for the certificate profile.
- Certificate Profile Authentication. This sets the authentication method. An automated authentication is set by providing the instance ID for the authentication instance. If this field is blank, the authentication method is agent-approved enrollment; the request is submitted to the request queue of the agent services interface.
  Unless it is for a TMS subsystem, administrators must select one of the following authentication plug-ins:
  - CMCAuth: Use this plug-in when a CA agent must approve and submit the enrollment request.
  - CMCUserSignedAuth: Use this plug-in to enable non-agent users to enroll own certificates.
Click OK. The plug-in editor closes, and the new profile is listed in the profiles tab.
Configure the policies, inputs, and outputs for the new profile. Select the new profile from the list, and click Edit/View.
Set up policies in the Policies tab of the Certificate Profile Rule Editor window. The Policies tab lists policies that are already set by default for the profile type.
1. To add a policy, click Add.
2. Choose the default from the Default field, choose the constraints associated with that policy in the Constraints field, and click OK.
3. Fill in the policy set ID. When issuing dual key pairs, separate policy sets define the policies associated with each certificate. Then fill in the certificate profile policy ID, a name or identifier for the certificate profile policy.
4. Configure any parameters in the Defaults and Constraints tabs.
  Defaults defines attributes that populate the certificate request, which in turn determines the content of the certificate. These can be extensions, validity periods, or other fields contained in the certificates. Constraints defines valid values for the defaults.
  See Section B.1, “Defaults Reference” and Section B.2, “Constraints Reference” for complete details for each default or constraint.
To modify an existing policy, select a policy, and click Edit. Then edit the default and constraints for that policy.
To delete a policy, select the policy, and click Delete.
Set inputs in the Inputs tab of the Certificate Profile Rule Editor window. There can be more than one input type for a profile.
Note
Unless you configure the profile for a TMS subsystem, select only cmcCertReqInput and delete other profiles by selecting them and clicking the Delete button.
1. To add an input, click Add.
2. Choose the input from the list, and click OK. See Section A.1, “Input Reference” for complete details of the default inputs.
3. The New Certificate Profile Editor window opens. Set the input ID, and click OK.
Inputs can be added and deleted. It is possible to select edit for an input, but since inputs have no parameters or other settings, there is nothing to configure.
To delete an input, select the input, and click Delete.
Set up outputs in the Outputs tab of the Certificate Profile Rule Editor window.
Outputs must be set for any certificate profile that uses an automated authentication method; no output needs to be set for any certificate profile that uses agent-approved authentication. The Certificate Output type is set by default for all profiles and is added automatically to custom profiles.
Unless you configure the profile for a TMS subsystem, select only certOutput.
Outputs can be added and deleted. It is possible to select edit for an output, but since outputs have no parameters or other settings, there is nothing to configure.
1. To add an output, click Add.
2. Choose the output from the list, and click OK.
3. Give a name or identifier for the output, and click OK.
  This output will be listed in the output tab. You can edit it to provide values to the parameters in this output.
To delete an output, select the output from list, and click Delete.

Restart the CA to apply the new profile.

systemctl restart pki-tomcatd-nuxwdog@instance_name.service

After creating the profile as an administrator, a CA agent has to approve the profile in the agent services pages to enable the profile.
1. Open the CA's services page.
```
https://server.example.com:8443/ca/services
```
2. Click the Manage Certificate Profiles link. This page lists all of the certificate profiles that have been set up by an administrator, both active and inactive.
3. Click the name of the certificate profile to approve.
4. At the bottom of the page, click the Enable button.

Note

If this profile will be used with a TPS, then the TPS must be configured to recognized the profile type. This is in 11.1.4. Managing Smart Card CA Profiles in Red Hat Certificate System's Planning, Installation, and Deployment Guide.

Authorization methods for the profiles can only be added to the profile using the command line, as described in the section Creating and Editing Certificate Profiles Directly on the File System in Red Hat Certificate System Planning, Installation and Deployment Guide.

3.2.2.2. Editing Certificate Profiles in the Console

To modify an existing certificate profile:

Log into the agent services pages and disable the profile.
Once a certificate profile is enabled by an agent, that certificate profile is marked enabled in the Certificate Profile Instance Management tab, and the certificate profile cannot be edited in any way through the console.
Log in to the Certificate System CA subsystem console.
```
pkiconsole https://server.example.com:8443/ca
```
In the Configuration tab, select Certificate Manager, and then select Certificate Profiles.
Select the certificate profile, and click Edit/View.
The Certificate Profile Rule Editor window appears. Many any changes to the defaults, constraints, inputs, or outputs.
Note
The profile instance ID cannot be modified.
If necessary, enlarge the window by pulling out one of the corners of the window.
Restart the CA to apply the changes.
In the agent services page, re-enable the profile.

Note

Delete any certificate profiles that will not be approved by an agent. Any certificate profile that appears in the Certificate Profile Instance Management tab also appears in the agent services interface. If a profile has already been enabled, it must be disabled by the agent before it can be deleted from the profile list.

3.2.3. Listing Certificate Enrollment Profiles

The following pre-defined certificate profiles are ready to use and set up in this environment when the Certificate System CA is installed. These certificate profiles have been designed for the most common types of certificates, and they provide common defaults, constraints, authentication methods, inputs, and outputs.

For a list of supported profiles, see Section 8.1.2, “CMC Authentication Plug-ins”.

To list the available profiles on the command line, use the pki utility. For example:

# pki -c password -n caadmin ca-profile-find
------------------
59 entries matched
------------------
  Profile ID: caCMCserverCert
  Name: Server Certificate Enrollment using CMC
  Description: This certificate profile is for enrolling server certificates using CMC.

  Profile ID: caCMCECserverCert
  Name: Server Certificate wth ECC keys Enrollment using CMC
  Description: This certificate profile is for enrolling server certificates with ECC keys using CMC.

  Profile ID: caCMCECsubsystemCert
  Name: Subsystem Certificate Enrollment with ECC keys using CMC
  Description: This certificate profile is for enrolling subsystem certificates with ECC keys using CMC.

  Profile ID: caCMCsubsystemCert
  Name: Subsystem Certificate Enrollment using CMC
  Description: This certificate profile is for enrolling subsystem certificates using CMC.

  ...
-----------------------------
Number of entries returned 20

For further details, see the pki-ca-profile(1) man page.

3.2.4. Displaying Details of a Certificate Enrollment Profile

For example, to display a specific certificate profile, such as caECFullCMCUserSignedCert:

$ pki -c password -n caadmin ca-profile-show caECFullCMCUserSignedCert
-----------------------------------
Profile "caECFullCMCUserSignedCert"
-----------------------------------
  Profile ID: caECFullCMCUserSignedCert
  Name: User-Signed CMC-Authenticated User Certificate Enrollment
  Description: This certificate profile is for enrolling user certificates with EC keys by using the CMC certificate request with non-agent user CMC authentication.

  Name: Certificate Request Input
  Class: cmcCertReqInputImpl

    Attribute Name: cert_request
    Attribute Description: Certificate Request
    Attribute Syntax: cert_request

  Name: Certificate Output
  Class: certOutputImpl

    Attribute Name: pretty_cert
    Attribute Description: Certificate Pretty Print
    Attribute Syntax: pretty_print

    Attribute Name: b64_cert
    Attribute Description: Certificate Base-64 Encoded
    Attribute Syntax: pretty_print

For example, to display a specific certificate profile, such as caECFullCMCUserSignedCert, in raw format:

$ pki -c password -n caadmin ca-profile-show caECFullCMCUserSignedCert --raw
#Wed Jul 25 14:41:35 PDT 2018
auth.instance_id=CMCUserSignedAuth
policyset.cmcUserCertSet.1.default.params.name=
policyset.cmcUserCertSet.4.default.class_id=authorityKeyIdentifierExtDefaultImpl
policyset.cmcUserCertSet.6.default.params.keyUsageKeyCertSign=false
policyset.cmcUserCertSet.10.default.class_id=noDefaultImpl
policyset.cmcUserCertSet.10.constraint.name=Renewal Grace Period Constraint
output.o1.class_id=certOutputImpl

...

For further details, see the pki-ca-profile(1) man page.

3.3. Defining Key Defaults in Profiles

When creating certificate profiles, the Key Default must be added before the Subject Key Identifier Default. Certificate System processes the key constraints in the Key Default before creating or applying the Subject Key Identifier Default, so if the key has not been processed yet, setting the key in the subject name fails.

For example, an object-signing profile may define both defaults:

policyset.set1.p3.constraint.class_id=noConstraintImpl
policyset.set1.p3.constraint.name=No Constraint
policyset.set1.p3.default.class_id=subjectKeyIdentifierExtDefaultImpl
policyset.set1.p3.default.name=Subject Key Identifier Default
...
policyset.set1.p11.constraint.class_id=keyConstraintImpl
policyset.set1.p11.constraint.name=Key Constraint
policyset.set1.p11.constraint.params.keyType=RSA
policyset.set1.p11.constraint.params.keyParameters=1024,2048,3072,4096
policyset.set1.p11.default.class_id=userKeyDefaultImpl
policyset.set1.p11.default.name=Key Default

In the policyset list, then, the Key Default (p11) must be listed before the Subject Key Identifier Default (p3).

policyset.set1.list=p1,p2,p11,p3,p4,p5,p6,p7,p8,p9,p10

3.4. Configuring Profiles to Enable Renewal

Renewing a certificate regenerates the certificate using the same public key as the original certificate. Renewing a certificate can be preferable to simply generating new keys and installing new certificates; for example, if a new CA signing certificate is created, all of the certificates which that CA issued and signed must be reissued. If the CA signing certificate is renewed, than all of the issued certificates are still valid. A renewed certificate is identical to the original, only with an updated validity period and expiration date.

This section discusses how to set up profiles for renewals.

3.4.1. About Renewal

A renewed certificate is identical to the original certificate, which makes renewing certificates a much simpler and cleaner option for handling the expiration of many kinds of certificates, especially CA signing certificates.

3.4.1.1. The Renewal Process

There are two methods of renewing a certificate. Regenerating the certificate takes the original key, profile, and request of the certificate and recreates a new certificate with a new validity period and expiration date using the identical key. Re-keying a certificate submits a certificate request through the original profile with the same information, so that a new key pair is generated.

A profile that allows renewal is also often accompanied by the renewGracePeriodConstraint entry. For example:

policyset.cmcUserCertSet.10.constraint.class_id=renewGracePeriodConstraintImpl
policyset.cmcUserCertSet.10.constraint.name=Renewal Grace Period Constraint
policyset.cmcUserCertSet.10.constraint.params.renewal.graceBefore=30
policyset.cmcUserCertSet.10.constraint.params.renewal.graceAfter=30
policyset.cmcUserCertSet.10.default.class_id=noDefaultImpl
policyset.cmcUserCertSet.10.default.name=No Default

3.4.1.1.1. Renewing Using the Same Key

A profile that allows the same key to be submitted for renewal has the allowSameKeyRenewal parameter set to true in the uniqueKeyConstraint entry. For example:

policyset.cmcUserCertSet.9.constraint.class_id=uniqueKeyConstraintImpl
policyset.cmcUserCertSet.9.constraint.name=Unique Key Constraint
policyset.cmcUserCertSet.9.constraint.params.allowSameKeyRenewal=true
policyset.cmcUserCertSet.9.default.class_id=noDefaultImpl
policyset.cmcUserCertSet.9.default.name=No Default

3.4.1.1.2. Renewal Using a New Key

To renew a certificate with a new key, use the same profile with a new key. Certificate System uses the subjectDN from the user signing certificate used to sign the request for the new certificate.

3.5. Setting the Signing Algorithms for Certificates

The CA's signing certificate can sign the certificates it issues with any public key algorithm supported by the CA. For example, an ECC signing certificate can sign both ECC and RSA certificate requests as long as both ECC and RSA algorithms are supported by the CA. An RSA signing certificate can can sign a PKCS #10 request with EC keys, but may not be able to sign CRMF certificate requests with EC keys if the ECC module is not available for the CA to verify the CRMF proof of possession (POP).

ECC and RSA are public key encryption and signing algorithms. Both public key algorithms support different cipher suites, algorithms used to encrypt and decrypt data. Part of the function of the CA signing certificate is to issue and sign certificates using one of its supported cipher suites.

Each profile can define which cipher suite the CA should use to sign certificates processed through that profile. If no signing algorithm is set, then the profile uses whatever the default signing algorithm is.

3.5.1. Setting the CA's Default Signing Algorithm

Open the CA console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, expand the Certificate Manager tree.
In the General Settings tab, set the algorithm to use in the Algorithm drop-down menu.

3.5.2. Setting the Signing Algorithm Default in a Profile

Each profile has a Signing Algorithm Default extension defined. The default has two settings: a default algorithm and a list of allowed algorithms, if the certificate request specifies a different algorithm. If no signing algorithms are specified, then the profile uses whatever is set as the default for the CA.

In the profile's .cfg file, the algorithm is set with two parameters:

policyset.cmcUserCertSet.8.constraint.class_id=signingAlgConstraintImpl
policyset.cmcUserCertSet.8.constraint.name=No Constraint
policyset.cmcUserCertSet.8.constraint.params.signingAlgsAllowed=SHA256withRSA,SHA512withRSA,SHA256withEC,SHA384withRSA,SHA384withEC,SHA512withEC
policyset.cmcUserCertSet.8.default.class_id=signingAlgDefaultImpl
policyset.cmcUserCertSet.8.default.name=Signing Alg
policyset.cmcUserCertSet.8.default.params.signingAlg=-

To configure the Signing Algorithm Default through the console:

Note

Before a profile can be edited, it must first be disabled by an agent.

Open the CA console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, expand the Certificate Manager tree.
Click the Certificate Profiles item.
Click the Policies tab.
Select the Signing Alg policy, and click the Edit button.
To set the default signing algorithm, set the value in the Defaults tab. If this is set to -, then the profile uses the CA's default.
To set a list of allowed signing algorithms which can be accepted in a certificate request, open the Constraints tab, and set the list of algorithms in the Value field for signingAlgsAllowed.
The possible values for the constraint are listed in Section B.2.10, “Signing Algorithm Constraint”.

3.7. Managing Subject Names and Subject Alternative Names

The subject name of a certificate is a distinguished name (DN) that contains identifying information about the entity to which the certificate is issued. This subject name can be built from standard LDAP directory components, such as common names and organizational units. These components are defined in X.500. In addition to — or even in place of — the subject name, the certificate can have a subject alternative name, which is a kind of extension set for the certificate that includes additional information that is not defined in X.500.

The naming components for both subject names and subject alternative names can be customized.

Important

If the subject name is empty, then the Subject Alternative Name extension must be present and marked critical.

3.7.1. Using the Requester CN or UID in the Subject Name

The cn or uid value from a certificate request can be used to build the subject name of the issued certificate. This section demonstrates a profile that requires the naming attribute (CN or UID) being specified in the Subject Name Constraint to be present in the certificate request. If the naming attribute is missing, the request is rejected.

There are two parts to this configuration:

The CN or UID format is set in the pattern configuration in the Subject Name Constraint.
The format of the subject DN, including the CN or UID token and the specific suffix for the certificate, is set in the Subject Name Default.

For example, to use the CN in the subject DN:

policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl
policyset.serverCertSet.1.constraint.name=Subject Name Constraint
policyset.serverCertSet.1.constraint.params.pattern=CN=[^,]+,.+
policyset.serverCertSet.1.constraint.params.accept=true
policyset.serverCertSet.1.default.class_id=subjectNameDefaultImpl
policyset.serverCertSet.1.default.name=Subject Name Default
policyset.serverCertSet.1.default.params.name=CN=$request.req_subject_name.cn$,DC=example, DC=com

In this example, if a request comes in with the CN of cn=John Smith, then the certificate will be issued with a subject DN of cn=John Smith,DC=example, DC=com. If the request comes in but it has a UID of uid=jsmith and no CN, then the request is rejected.

The same configuration is used to pull the requester UID into the subject DN:

policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl
policyset.serverCertSet.1.constraint.name=Subject Name Constraint
policyset.serverCertSet.1.constraint.params.pattern=UID=[^,]+,.+
policyset.serverCertSet.1.constraint.params.accept=true
policyset.serverCertSet.1.default.class_id=subjectNameDefaultImpl
policyset.serverCertSet.1.default.name=Subject Name Default
policyset.serverCertSet.1.default.params.name=UID=$request.req_subject_name.uid$,DC=example, DC=com

The format for the pattern parameter is covered in Section B.2.11, “Subject Name Constraint” and Section B.1.28, “Subject Name Default”.

3.7.2. Inserting LDAP Directory Attribute Values and Other Information into the Subject Alt Name

Information from an LDAP directory or that was submitted by the requester can be inserted into the subject alternative name of the certificate by using matching variables in the Subject Alt Name Extension Default configuration. This default sets the type (format) of information and then the matching pattern (variable) to use to retrieve the information. For example:

policyset.userCertSet.8.default.class_id=subjectAltNameExtDefaultImpl
policyset.userCertSet.8.default.name=Subject Alt Name Constraint
policyset.userCertSet.8.default.params.subjAltNameExtCritical=false
policyset.userCertSet.8.default.params.subjAltExtType_0=RFC822Name
policyset.userCertSet.8.default.params.subjAltExtPattern_0=$request.requestor_email$
policyset.userCertSet.8.default.params.subjAltExtGNEnable_0=true

This inserts the requester's email as the first CN component in the subject alt name. To use additional components, increment the Type_, Pattern_, and Enable_ values numerically, such as Type_1.

Configuring the subject alt name is detailed in Section B.1.24, “Subject Alternative Name Extension Default”, as well.

To insert LDAP components into the subject alt name of the certificate:

Inserting LDAP attribute values requires enabling the user directory authentication plug-in, SharedSecret.
1. Open the CA Console.
```
pkiconsole https://server.example.com:8443/ca
```
2. Select Authentication in the left navigation tree.
3. In the Authentication Instance tab, click Add, and add an instance of the SharedSecret authentication plug-in.
4. Enter the following information:
```
Authentication InstanceID=SharedToken
shrTokAttr=shrTok
ldap.ldapconn.host=server.example.com
ldap.ldapconn.port=636
ldap.ldapconn.secureConn=true
ldap.ldapauth.bindDN=cn=Directory Manager
password=password
ldap.ldapauth.authtype=BasicAuth
ldap.basedn=ou=People,dc=example,dc=org
```
5. Save the new plug-in instance.
For information on setting a CMC shared token, see Section 8.1.3.2, “Setting a CMC Shared Secret”.
The ldapStringAttributes parameter instructs the authentication plug-in to read the value of the mail attribute from the user's LDAP entry and put that value in the certificate request. When the value is in the request, the certificate profile policy can be set to insert that value for an extension value.
The format for the dnpattern parameter is covered in Section B.2.11, “Subject Name Constraint” and Section B.1.28, “Subject Name Default”.
To enable the CA to insert the LDAP attribute value in the certificate extension, edit the profile's configuration file, and insert a policy set parameter for an extension. For example, to insert the mail attribute value in the Subject Alternative Name extension in the caFullCMCSharedTokenCert profile, change the following code:
```
policyset.setID.8.default.params.subjAltExtPattern_0=$request.auth_token.mail[0]$
```
For more details about editing a profile, see Section 3.2.1.3, “Editing a Certificate Profile in Raw Format”.

Restart the CA.

systemctl restart pki-tomcatd-nuxwdog@instance_name.service

For this example, certificates submitted through the caFullCMCSharedTokenCert profile enrollment form will have the Subject Alternative Name extension added with the value of the requester's mail LDAP attribute. For example:

Identifier: Subject Alternative Name - 2.5.29.17
    Critical: no
    Value:
    RFC822Name: jsmith@example.com

There are many attributes which can be automatically inserted into certificates by being set as a token ($X$) in any of the Pattern_ parameters in the policy set. The common tokens are listed in Table 3.1, “Variables Used to Populate Certificates”, and the default profiles contain examples for how these tokens are used.

Table 3.1. Variables Used to Populate Certificates
Policy Set Token	Description
$request.auth_token.cn[0]$	The LDAP common name (`cn`) attribute of the user who requested the certificate.
$request.auth_token.mail[0]$	The value of the LDAP email (`mail`) attribute of the user who requested the certificate.
$request.auth_token.tokencertsubject$	The certificate subject name.
$request.auth_token.uid$	The LDAP user ID (`uid`) attribute of the user who requested the certificate.
$request.auth_token.userdn$	The user DN of the user who requested the certificate.
$request.auth_token.userid$	The value of the user ID attribute for the user who requested the certificate.
$request.uid$	The value of the user ID attribute for the user who requested the certificate.
$request.requestor_email$	The email address of the person who submitted the request.
$request.request_name$	The person who submitted the request.
$request.upn$	The Microsoft UPN. This has the format (UTF8String)1.3.6.1.4.1.311.20.2.3,$request.upn$.
$server.source$	Instructs the server to generate a version 4 UUID (random number) component in the subject name. This always has the format (IA5String)1.2.3.4,$server.source$.
$request.auth_token.user$	Used when the request was submitted by TPS. The TPS subsystem trusted manager who requested the certificate.
$request.subject$	Used when the request was submitted by TPS. The subject name DN of the entity to which TPS has resolved and requested for. For example, `cn=John.Smith.123456789,o=TMS Org`

3.7.3. Using the CN Attribute in the SAN Extension

Several client applications and libraries no longer support using the Common Name (CN) attribute of the Subject DN for domain name validation, which has been deprecated in RFC 2818. Instead, these applications and libraries use the dNSName Subject Alternative Name (SAN) value in the certificate request.

Certificate System copies the CN only if it matches the preferred name syntax according to RFC 1034 Section 3.5 and has more than one component. Additionally, existing SAN values are preserved. For example, the dNSName value based on the CN is appended to existing SANs.

To configure Certificate System to automatically use the CN attribute in the SAN extension, edit the certificate profile used to issue the certificates. For example:

Disable the profile:

# pki -c password -p 8080 \
     -n "PKI Administrator for example.com" ca-profile-disable profile_name

Edit the profile:

# pki -c password -p 8080 \
     -n "PKI Administrator for example.com" ca-profile-edit profile_name

Add the following configuration with a unique set number for the profile. For example:

policyset.serverCertSet.12.constraint.class_id=noConstraintImpl
policyset.serverCertSet.12.constraint.name=No Constraint
policyset.serverCertSet.12.default.class_id=commonNameToSANDefaultImpl
policyset.serverCertSet.12.default.name=Copy Common Name to Subject

The previous example uses 12 as the set number.

Append the new policy set number to the policyset.userCertSet.list parameter. For example:
```
policyset.userCertSet.list=1,10,2,3,4,5,6,7,8,9,12
```
Save the profile.

Enable the profile:

# pki -c password -p 8080 \
     -n "PKI Administrator for example.com" ca-profile-enable profile_name

Note

All default server profiles contain the commonNameToSANDefaultImpl default.

3.7.4. Accepting SAN Extensions from a CSR

In certain environments, administrators want to allow specifying Subject Alternative Name (SAN) extensions in Certificate Signing Request (CSR).

3.7.4.1. Configuring a Profile to Retrieve SANs from a CSR

To allow retrieving SANs from a CSR, use the User Extension Default. For details, see Section B.1.33, “User Supplied Extension Default”.

Note

A SAN extension can contain one or more SANs.

To accept SANs from a CSR, add the following default and constraint to a profile, such as caCMCECserverCert:

prefix.constraint.class_id=noConstraintImpl
prefix.constraint.name=No Constraint

prefix.default.class_id=userExtensionDefaultImpl
prefix.default.name=User supplied extension in CSR
prefix.default.params.userExtOID=2.5.29.17

3.7.4.2. Generating a CSR with SANs

For example, to generate a CSR with two SANs using the certutil utility:

# certutil -R -k ec -q nistp256 -d . -s "cn=Example Multiple SANs" --extSAN dns:www.example.com,dns:www.example.org -a -o /root/request.csr.p10

After generating the CSR, follow the steps described in Section 5.3.1, “The CMC Enrollment Process” to complete the CMC enrollment.

Chapter 4. Setting up Key Archival and Recovery

This chapter explains how to use the Key Recovery Authority (KRA), previously known as Data Recovery Manager (DRM), to archive private keys and to recover these archived keys to restore encrypted data.

Note

Server-side key generation is an option provided for smart card enrollments performed through the TPS subsystem. This chapter deals with archiving keys through client-side key generation, not the server-side key generation and archivals initiated through the TPS.

Note

Gemalto SafeNet LunaSA only supports PKI private key extraction in its CKE - Key Export model, and only in non-FIPS mode. The LunaSA Cloning model and the CKE model in FIPS mode do not support PKI private key extraction.

Archiving private keys offers protection for users, and for information, if that key is ever lost. Information is encrypted by the public key when it is stored. The corresponding private key must be available to decrypt the information. If the private key is lost, the data cannot be retrieved. A private key can be lost because of a hardware failure or because the key's owner forgets the password or loses the hardware token in which the key is stored. Similarly, encrypted data cannot be retrieved if the owner of the key is unavailable to supply it.

Note

In a cloned environment, it is necessary to set up key archival and recovery manually.

4.1. About Key Archival and Recovery

From the end user perspective, key archival requires only two things: a client, such as the pki utility, which can generate a key and a certificate profile which is configured to support key archival. For details about the pki utility, see the Command-Line Interface (CLI) section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).

4.1.1. Key Archival

If an end entity loses a private encryption key or is unavailable to use the private key, the key must be recovered before any data that was encrypted with the corresponding public key can be read. Recovery is possible if the private key was archived when the key was generated.

The KRA stores private encryption keys in a secure key repository in its internal database in form of key records. The Certificate Manager automatically forwards certificate requests issued by a client to the KRA, if the requests contain the key archival option. In such a case, the private key is wrapped by the KRA transport key on the client and sent as an encrypted blob to the KRA. The KRA decrypts the blob and re-encrypts the key using its storage key. The KRA then gives the encrypted blob a unique key identifier and archives it in its key repository as a key record.

The archived copy of the key remains wrapped with the KRA's storage key. It can be decrypted, or unwrapped, only by using the corresponding private key pair of the storage certificate. A combination of one or more key recovery (or KRA) agents' certificates authorizes the KRA to complete the key recovery to retrieve its private storage key and use it to decrypt/recover an archived private key. The KRA indexes stored keys by key number, owner name, and a hash of the public key, allowing for highly efficient searching.

Figure 4.1, “How the Key Archival Process Works” illustrates how the key archival process occurs when an end entity requests a certificate.

Figure 4.1. How the Key Archival Process Works

The client generates and encrypts its private key and submits the request to the CA.
After approving the certificate request and issuing the certificate, the Certificate Manager sends it to the KRA for storage, along with the public key. The Certificate Manager waits for verification from the KRA that the private key has been received and stored and that it corresponds to the public encryption key.
The KRA decrypts it with the transport private key. After confirming that the private encryption key corresponds to the public encryption key, the KRA encrypts it again with its public key pair of the storage key before storing it in its internal database.
Once the private encryption key has been successfully stored, the KRA uses the private key of its transport key pair to sign a token confirming that the key has been successfully stored; the KRA then sends the token to the Certificate Manager.
The Certificate Manager issues the certificate, which is embedded in the CMC response.

Both subsystems subject the request to configured certificate profile constraints at appropriate stages. If the request fails to meet any of the profile constraints, the subsystem rejects the request.

The KRA supports agent-initiated key recovery, when designated recovery agents use the key recovery form on the KRA agent services page to process and approve key recovery requests. With the approval of a specified number of agents, an organization can recover keys when the key's owner is unavailable or when keys have been lost.

Certificate System 9 uses an m-of-n ACL-based recovery scheme, rather than an older secret-splitting-based recovery scheme. In versions of Certificate System older than 7.1, the password for the storage token was split and protected by individual recovery agent passwords. Now, Certificate System uses its existing access control scheme to ensure recovery agents are appropriately authenticated over TLS and requires that the agent belong to a specific recovery agent group, by default the Key Recovery Authority Agents Group. The recovery request is executed only when m-of-n (a required number of) recovery agents have granted authorization to the request.

The key recovery scheme can be changed by changing the KRA configuration, as described in the Setting up Agent-Approved Key Recovery Schemes section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).

For the actual key recovery process, one of the key recovery agents informs all required recovery agents about an impending key recovery and initiates the recovery process in the KRA's agent pages. A key recovery process can either be synchronous, meaning that the initial session must remain open as approvals come in, or asynchronous, meaning that snapshots of the recovery process are stored in the internal database and updated as approvals come in.

Figure 4.2. Async and Sync Recovery, Side by Side

Important

Synchronous recovery is deprecated in Red Hat Certificate System.

For asynchronous recovery, each step is saved to the internal database. Agents can search for the key to recover and then click the Grant Recovery button to approve the recovery. Asynchronous recoveries will persist even if the KRA is restarted.

4.1.2. Key Recovery

To test whether a key can be successfully archived and recovered:

Generate a CRMF request and submit it through the CA’s enrollment portal.
For more information, see Section 5.3.2.3.1, “Example on Obtaining an Encryption-only certificate with Key Archival”.
Import the certificates into an email client capable of doing SMIME.
Confirm that the key has been archived. In the KRA's agent services page, select Show completed requests. If the key has been archived successfully, there will be information about that key. If the key is not shown, check the logs, and correct the problem. If the key has been successfully archived, close the browser window.
Verify the key. Send a signed and encrypted email. When the email is received, open it, and check the message to see if it is signed and encrypted. There should be a security icon at the top-right corner of the message window that indicates that the message is signed and encrypted.
Delete the certificate. Check the encrypted email again; the mail client should not be able to decrypt the message.
Test whether an archived key can be recovered successfully:
1. Open the KRA's agent services page, and click the Recover Keys link. Search for the key by the key owner, serial number, or public key. If the key has been archived successfully, the key information will be shown.
2. Click Recover.
3. In the form that appears, enter the base-64 encoded certificate that corresponds to the private key to recover; use the CA to get this information. If the archived key was searched for by providing the base-64 encoded certificate, then the certificate does not have to be supplied here.
4. Make sure that the Async Recovery checkbox is selected to allow the browser session to be closed while recovery is ongoing.
5. Depending on the agent scheme, a specified number of agents must authorize this key recovery. Have the agents search for the key to recover and then to approve the initiated recovery.
6. Once all the agents have authorized the recovery, the next screen requests a password to encrypt the PKCS #12 file with the certificate.
7. The next screen returns a link to download a PKCS #12 blob containing the recovered key pair. Follow the link, and save the blob to file.
  Important
  Opening the PKCS #12 file directly from the browser in the gcr-viewer utility can fail in certain situations. To work around the problem, download the file and manually open it in gcr-viewer.
Restore the key to the browser's database. Import the .p12 file into the browser and mail client.
Open the test email. The message should be shown again.

Chapter 5. Requesting, Enrolling, and Managing Certificates

Certificates are requested and used by end users. Although certificate enrollment and renewal are operations that are not limited to administrators, understanding the enrollment and renewal processes can make it easier for administrators to manage and create appropriate certificate profiles, as described in Section 3.2, “Setting up Certificate Profiles”, and to use fitting authentication methods for each certificate type.

This chapter discusses requesting, receiving, and renewing certificates for use outside Certificate System. For information on requesting and renewing Certificate System subsystem certificates, see Chapter 14, Managing Subsystem Certificates.

5.1. About Enrolling and Renewing Certificates

Enrollment is the process for requesting and receiving a certificate. The mechanics for the enrollment process are slightly different depending on the type of certificate, the method for generating its key pair, and the method for generating and approving the certificate itself. Whatever the specific method, certificate enrollment, at a high level, has the same basic steps:

A user generates a certificate request.
The certificate request is submitted to the CA.
The request is verified by authenticating the entity which requested it and by confirming that the request meets the certificate profile rules which were used to submit it.
The request is approved.
The user retrieves the new certificate.

When the certificate reaches the end of its validity period, it can be renewed.

5.2. Creating Certificate Signing Requests

As explained in the Enrolling with CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition), the CMCRequest utility accepts Certificate Signing Requests (CSR) in PKCS #10 and CRMF format.

Red Hat Certificate System supports using the following utilities to create CSRs:

certutil: Supports creating PKCS #10 requests.
PKCS10Client: Supports creating PKCS #10 requests.
CRMFPopClient: Supports creating CRMF requests.

The following sections provide some examples on how to use these utilities with the feature-rich enrollment profile framework.

5.2.1. Creating a CSR Using `certutil`

This section describes examples on how to use the certutil utility to create a CSR.

For further details about using certutil, see:

The certutil(1) man page
The output of the certutil --help command

5.2.1.1. Using `certutil` to Create a CSR with EC Keys

The following procedure demonstrates how to use the certutil utility to create an Elliptic Curve (EC) key pair and CSR:

Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
```
$ cd /user_or_entity_database_directory/
```
Create the binary CSR and store it in the /user_or_entity_database_directory/request.csr file:
```
$ certutil -d . -R -k ec -q nistp256 -s "CN=subject_name" -o /user_or_entity_database_directory/request-bin.csr
```
Enter the required NSS database password when prompted.
For further details about the parameters, see the certutil(1) man page.

Convert the created binary format CSR to PEM format:

$ BtoA /user_or_entity_database_directory/request-bin.csr /user_or_entity_database_directory/request.csr

Optionally, verify that the CSR file is correct:

$ cat /user_or_entity_database_directory/request.csr

MIICbTCCAVUCAQAwKDEQMA4GA1UEChMHRXhhbXBsZTEUMBIGA1UEAxMLZXhhbXBs
...

This is a PKCS#10 PEM certificate request.

For the next steps, see Section 5.3.1, “The CMC Enrollment Process”, but skip the step about creating the certificate request.

5.2.1.2. Using `certutil` to Create a CSR With User-defined Extensions

The following procedure demonstrates how to create a CSR with user-defined extensions using the certutil utility.

Note that the enrollment requests are constrained by the enrollment profiles defined by the CA. See Example B.3, “Multiple User Supplied Extensions in CSR”.

Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
```
$ cd /user_or_entity_database_directory/
```
Create the CSR with user-defined Key Usage extension as well as user-defined Extended Key Usage extension and store it in the /user_or_entity_database_directory/request.csr file:
```
$ certutil -d . -R -k rsa -g 1024 -s "CN=subject_name" --keyUsage keyEncipherment,dataEncipherment,critical --extKeyUsage timeStamp,msTrustListSign,critical -a -o /user_or_entity_database_directory/request.csr
```
Enter the required NSS database password when prompted.
For further details about the parameters, see the certutil(1) man page.

Optionally, verify that the CSR file is correct:

$ cat /user_or_entity_database_directory/request.csr
Certificate request generated by Netscape certutil
Phone: (not specified)

Common Name: user 4-2-1-2
Email: (not specified)
Organization: (not specified)
State: (not specified)
Country: (not specified)

This is a PKCS#10 PEM certificate request.

For the next steps, see Section 5.3.1, “The CMC Enrollment Process”, but skip the step about creating the certificate request.
Note
Remove the header information from the CSR.

5.2.2. Creating a CSR Using `PKCS10Client`

This section describes examples how to use the PKCS10Client utility to create a CSR.

For further details about using PKCS10Client, see:

The PKCS10Client(1) man page
The output of the PKCS10Client --help command

5.2.2.1. Using `PKCS10Client` to Create a CSR

The following procedure explains how to use the PKCS10Client utility to create an Elliptic Curve (EC) key pair and CSR:

Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
```
$ cd /user_or_entity_database_directory/
```
Create the CSR and store it in the /user_or_entity_database_directory/example.csr file:
```
$ PKCS10Client -d . -p NSS_password -a ec -c nistp256 -o /user_or_entity_database_directory/example.csr -n "CN=subject_name"
```
For further details about the parameters, see the PKCS10Client(1) man page.

Optionally, verify that the CSR is correct:

$ cat /user_or_entity_database_directory/example.csr
-----BEGIN CERTIFICATE REQUEST-----
MIICzzCCAbcCAQAwgYkx
...
-----END CERTIFICATE REQUEST-----

5.2.2.2. Using `PKCS10Client` to Create a CSR for SharedSecret-based CMC

The following procedure explains how to use the PKCS10Client utility to create an RSA key pair and CSR for SharedSecret-based CMC. Use it only with the CMC Shared Secret authentication method which is, by default, handled by the caFullCMCSharedTokenCert and caECFullCMCSharedTokenCert profiles.

Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
```
$ cd /user_or_entity_database_directory/
```
Create the CSR and store it in the /user_or_entity_database_directory/example.csr file:
```
$ PKCS10Client -d . -p NSS_password -o /user_or_entity_database_directory/example.csr -y true -n "CN=subject_name"
```
For further details about the parameters, see the PKCS10Client(1) man page.

Optionally, verify that the CSR is correct:

$ cat /user_or_entity_database_directory/example.csr
-----BEGIN CERTIFICATE REQUEST-----
MIICzzCCAbcCAQAwgYkx
...
-----END CERTIFICATE REQUEST-----

5.2.3. Creating a CSR Using `CRMFPopClient`

Certificate Request Message Format (CRMF) is a CSR format accepted in CMC that allows key archival information to be securely embedded in the request.

This section describes examples how to use the CRMFPopClient utility to create a CSR.

For further details about using CRMFPopClient, see the CRMFPopClient(1) man page.

5.2.3.1. Using `CRMFPopClient` to Create a CSR with Key Archival

The following procedure explains how to use the CRMFPopClient utility to create an RSA key pair and a CSR with the key archival option:

Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
```
$ cd /user_or_entity_database_directory/
```

Retrieve the KRA transport certificate:

$ pki ca-cert-find --name "DRM Transport Certificate"
    ---------------
    1 entries found
    ---------------
      Serial Number: 0x7
      Subject DN: CN=DRM Transport Certificate,O=EXAMPLE
      Status: VALID
      Type: X.509 version 3
      Key A    lgorithm: PKCS #1 RSA with 2048-bit key
      Not Valid Before: Thu Oct 22 18:26:11 CEST 2015
      Not Valid After: Wed Oct 11 18:26:11 CEST 2017
      Issued On: Thu Oct 22 18:26:11 CEST 2015
      Issued By: caadmin
    ----------------------------
    Number of entries returned 1

Export the KRA transport certificate:

$ pki ca-cert-show 0x7 --output kra.transport

Create the CSR and store it in the /user_or_entity_database_directory/example.csr file:
```
$ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" -v -o /user_or_entity_database_directory/example.csr
```
To create an Elliptic Curve (EC) key pair and CSR, pass the -a ec -t false options to the command.
For further details about the parameters, see the CRMFPopClient(1) man page.

Optionally, verify that the CSR is correct:

$ cat /user_or_entity_database_directory/example.csr
-----BEGIN CERTIFICATE REQUEST-----
MIICzzCCAbcCAQAwgYkx
...
-----END CERTIFICATE REQUEST-----

5.2.3.2. Using `CRMFPopClient` to Create a CSR for SharedSecret-based CMC

The following procedure explains how to use the CRMFPopClient utility to create an RSA key pair and CSR for SharedSecret-based CMC. Use it only with the CMC Shared Secret authentication method which is, by default, handled by the caFullCMCSharedTokenCert and caECFullCMCSharedTokenCert profiles.

Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
```
$ cd /user_or_entity_database_directory/
```

Retrieve the KRA transport certificate:

$ pki ca-cert-find --name "DRM Transport Certificate"
    ---------------
    1 entries found
    ---------------
      Serial Number: 0x7
      Subject DN: CN=DRM Transport Certificate,O=EXAMPLE
      Status: VALID
      Type: X.509 version 3
      Key A    lgorithm: PKCS #1 RSA with 2048-bit key
      Not Valid Before: Thu Oct 22 18:26:11 CEST 2015
      Not Valid After: Wed Oct 11 18:26:11 CEST 2017
      Issued On: Thu Oct 22 18:26:11 CEST 2015
      Issued By: caadmin
    ----------------------------
    Number of entries returned 1

Export the KRA transport certificate:

$ pki ca-cert-show 0x7 --output kra.transport

Create the CSR and store it in the /user_or_entity_database_directory/example.csr file:
```
$ CRMFPopClient -d . -p password -n "cn=subject_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" -y -v -o /user_or_entity_database_directory/example.csr
```
To create an EC key pair and CSR, pass the -a ec -t false options to the command.
For further details about the parameters, see the output of the CRMFPopClient --help command.

Optionally, verify that the CSR is correct:

$ cat /user_or_entity_database_directory/example.csr
-----BEGIN CERTIFICATE REQUEST-----
MIICzzCCAbcCAQAwgYkx
...
-----END CERTIFICATE REQUEST-----

5.3. Requesting and Receiving Certificates Using CMC

This section describes the procedure to enroll a certificate using Certificate Management over CMS (CMC).

For general information about configuration and the workflow of enrolling certificates using CMC, see:

The Configuration for CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
The Enrolling with CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
CMCRequest(1) man page
CMCResponse(1) man page

CMC enrollment is possible in various ways to meet the requirements for different scenarios. Section 5.3.1, “The CMC Enrollment Process” supplements the Enrolling with CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition) with more details. Additionally, the Section 5.3.2, “Practical CMC Enrollment Scenarios” section enables administrators to decide which mechanisms should be used in which scenario.

5.3.1. The CMC Enrollment Process

Use the following general procedure to request and issue a certificate using CMC:

Create a Certificate Signing Request (CSR) in one of the following formats:
- PKCS #10 format
- Certificate Request Message Format (CRMF) format:
For details about creating CSRs in these formats, see Section 5.2, “Creating Certificate Signing Requests”.
Import the admin certificate into the client NSS database. For example:
- Execute the command below to extract the admin client certificate from the .p12 file:
```
$ openssl pkcs12 -in /root/.dogtag/instance/ca_admin_cert.p12 -clcerts -nodes -nokeys -out /root/.dogtag/instance/ca_admin_cert.crt
```
- Validate and import the admin client certificate according to guidance in ⁠Chapter 11, Managing Certificate/Key Crypto Token:
```
$ PKICertImport -d . -n "CA Admin - Client Certificate" -t ",," -a -i /root/.dogtag/instance/ca_admin_cert.crt -u C
```
  Important
  Make sure all intermediate certificates and the root CA certificate have been imported before importing the CA Admin client certificate.
- Import the private keys associated with the certificates.
```
$ pki -c password pkcs12-import --pkcs12-file /root/.dogtag/instance/ca_admin_cert.p12 --pkcs12-password-file /root/.dogtag/instance/ca/pkcs12_password.conf
```

Create a configuration file for a CMC request, such as /home/user_name/cmc-request.cfg, with the following content:

# NSS database directory where CA agent certificate is stored
dbdir=/home/user_name/.dogtag/nssdb/

# NSS database password
password=password

# Token name (default is internal)
tokenname=internal

# Nickname for signing certificate
nickname=subsystem_admin

# Request format: pkcs10 or crmf
format=pkcs10

# Total number of PKCS10/CRMF requests
numRequests=1

# Path to the PKCS10/CRMF request
# The content must be in Base-64 encoded format.
# Multiple files are supported. They must be separated by space.
input=/home/user_name/file.csr

# Path for the CMC request
output=/home/user_name/cmc-request.bin

For further details, see the CMCRequest(1) man page.

Create the CMC request:
```
$ CMCRequest /home/user_name/cmc-request.cfg
```
If the command succeeds, the CMCRequest utility stored the CMC request in the file specified in the output parameter in the request configuration file.

Create a configuration file for HttpClient, such as /home/user_name/cmc-submit.cfg, which you use in a later step to submit the CMC request to the CA. Add the following content to the created file:

# PKI server host name
host=server.example.com

# PKI server port number
port=8443

# Use secure connection
secure=true

# Use client authentication
clientmode=true

# NSS database directory where the CA agent certificate is stored.
dbdir=/home/user_name/.dogtag/nssdb/

# NSS database password
password=password

# Token name (default: internal)
tokenname=internal

# Nickname of signing certificate
nickname=subsystem_admin

# Path for the CMC request
input=/home/user_name/cmc-request.bin

# Path for the CMC response
output=/home/user_name/cmc-response.bin

Important

The nickname of the certificate specified in the nickname parameter must match the one previously used for the CMC request.

Depending on what type of certificate you request, add the following parameter to the configuration file created in the previous step:
```
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=profile_name
```
For example, for a CA signing certificate:
```
servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCcaCert
```
Important
When an agent submits the CMC request in the next step, the profile specified in this parameter must use the CMCAuth authentication plug-in. Whereas in user-initiated enrollments, the profile must use the CMCUserSignedAuth plug-in. For further details, see Section 8.1.2, “CMC Authentication Plug-ins”.

Submit the CMC request to the CA:

$ HttpClient /home/user_name/cmc-submit.cfg

To convert the CMC response to a PKCS #7 certificate chain, pass the CMC response file to the -i parameter of the CMCResponse utility. For example:
```
$ CMCResponse -i /home/user_name/cmc-response.bin -o /home/user_name/cert_chain.crt
```

5.3.2. Practical CMC Enrollment Scenarios

This section describes frequent practical usage scenarios and their workflows to enable CA administrators to decide which CMC method to use in which situation.

For a general process of enrolling a certificate using CMC, see Section 5.3.1, “The CMC Enrollment Process”.

5.3.2.1. Obtaining System and Server Certificates

If a service, such as LDAP or a web server, requires a TLS server certificate, the administrator of this server creates a CSR based on the documentation of the service and sends it to the CA's agent for approval. Use the procedure described in Section 5.3.1, “The CMC Enrollment Process” for this process. Additionally, consider the following requirements:

Enrollment Profiles

The agent must either use one of the existing CMC profiles listed in Section 8.1.2, “CMC Authentication Plug-ins” or, alternatively, create a custom profile that uses the CMCAuth authentication mechanism.

CMC Signing Certificate

For system certificates, the CA agent must generate and sign the CMC request. For this, set the nickname parameter in the CMCRequest configuration file to the nickname of the CA agent.

Note

The CA agent must have access to its own private key.

HttpClient TLS Client Nickname

Use the same certificate for signing in the CMCRequest utility's configuration file as for TLS client authentication in the configuration file for HttpClient.

HttpClient servlet Parameter

The servlet in the configuration file passed to the HttpClient utility refers to the CMC servlet and the enrollment profile which handles the request.

Depending on what type of certificate you request, add one of the following entries to the configuration file created in the previous step:

For a CA signing certificate:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCcaCert

For a KRA transport certificate:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCkraTransportCert

For a OCSP signing certificate:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCocspCert

For a audit signing certificate:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCauditSigningCert

For a subsystem certificate:

For RSA certificates:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCsubsystemCert

For ECC certificates:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCsubsystemCert

For a TLS server certificate:

For RSA certificates:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCserverCert

For ECC certificates:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caCMCECCserverCert

For an admin certificate:

servlet=/ca/ee/ca/profileSubmitCMCFull?profileId=caFullCMCUserCert

Further details:

When an agent pre-signs a CSR, the Proof of Identification is considered established because the agent examines the CSR for identification. No additional CMC-specific identification proof is required.
PKCS #10 files already provide Proof of Possession information and no additional Proof of Possession (POP) is required.
In agent pre-approved requests, the PopLinkWittnessV2 feature must be disabled because the identification is checked by the agent.

5.3.2.2. Obtaining the First Signing Certificate for a User

There are two ways to approve a user's first signing certificate:

An agent signs the CMC request. See Section 5.3.2.2.1, “Signing a CMC Request with an Agent Certificate”.
Certificate enrollment is authenticated by using a Shared Secret. See Section 5.3.2.2.2, “Authenticating for Certificate Enrollment Using a Shared Secret”.

5.3.2.2.1. Signing a CMC Request with an Agent Certificate

The process for signing a CMC request with an agent certificate is the same as for system and server certificates described in Section 5.3.2.1, “Obtaining System and Server Certificates”. The only difference is that the user creates the CSR and sends it to a CA agent for approval.

5.3.2.2.2. Authenticating for Certificate Enrollment Using a Shared Secret

When a user wants to obtain the first signing certificate and the agent cannot approve the request as described in Section 5.3.2.2.1, “Signing a CMC Request with an Agent Certificate”, you can use a Shared Token. With this token, the user can obtain the first signing certificate. This certificate can then be used to sign other certificates of the user.

In this scenario, use the Shared Secret mechanism to obtain the first signing certificate of the user. Use the following information together with Section 5.3.1, “The CMC Enrollment Process”:

Create a Shared Token either as the user or CA administrator. For details, see Section 8.1.3.1, “Creating a Shared Secret Token”.
Note that:
- If the user created the token, the user must send the token to the CA administrator.
- If the CA administrator created the token, the administrator must share the password used to generate the token with the user. Use a secure way to transmit the password.
As the CA administrator, add the Shared Token to the user entry in LDAP. For details, see Section 8.1.3.2.1, “Adding a CMC Shared Secret to a User Entry for Certificate Enrollment” and the Enabling the CMC Shared Secret Feature section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
Use the following parameters in the configuration file passed to the CMCRequest utility:
- identification.enable
- witness.sharedSecret
- identityProofV2.enable
- identityProofV2.hashAlg
- identityProofV2.macAlg
- request.useSharedSecret
- request.privKeyId
If required by the CA, additionally use the following parameters in the configuration file passed to the CMCRequest utility:
- popLinkWitnessV2.enable
- popLinkWitnessV2.keyGenAlg
- popLinkWitnessV2.macAlg

5.3.2.3. Obtaining an Encryption-only Certificate for a User

This section describes the workflow for obtaining an encryption-only certificate which is signed with an existing user signing certificate:

Note

If a user owns multiple certificates for different usages, where one is signing, the user must obtain the signing certificate first. Once the user owns a signing certificate, it can be used for Proof Of Origin without requiring to set up and rely on the CMC Shared Secret mechanism.

For details about obtaining a user's first signing certificate, see Section 5.3.2.2, “Obtaining the First Signing Certificate for a User”.

As a user:

Use the cryptographic token stored in a Network Security Services (NSS) database or on a smart card that contains the user's signing certificate and keys.
Generate the CSR in PKCS #10 or the CRMF format.
Note
Use the CRMF format, if key archival is required.
Generate the CMC request.
Since this is an encryption-only certificate, the private key is not able to sign. Therefore, Proof Of Possession (POP) is not included. For this reason, the enrollment requires two steps: If the initial request is successful, results in a CMC status with the EncryptedPOP control. The user then uses the response and generates a CMC request that contains the DecryptedPOP control and submits it in the second step.
1. For the first step, in addition to the default parameters, the user must set the following parameters in the configuration file passed to the CMCRequest utility:
  - identification.enable
  - witness.sharedSecret
  - identityProofV2.enable
  - identityProofV2.hashAlg
  - identityProofV2.macAlg
  - popLinkWitnessV2.enable if required by the CA
  - popLinkWitnessV2.keyGenAlg if required by the CA
  - popLinkWitnessV2.macAlg if required by the CA
  - request.privKeyId
  For details, see the CMCRequest(1) man page.
  The response contains:
  - A CMC encrypted POP control
  - The CMCStatusInfoV2 control with the POP required error
  - The request ID
2. For the second step, in addition to the default parameters, the user must set the following parameters in the configuration file passed to the CMCRequest utility:
  - decryptedPop.enable
  - encryptedPopResponseFile
  - decryptedPopRequestFile
  - request.privKeyId
  For details, see the CMCRequest(1) man page.

5.3.2.3.1. Example on Obtaining an Encryption-only certificate with Key Archival

To perform an enrollment with key archival, generate a CMC request that contains the user's encrypted private key in the CRMF request. The following procedure assumes that the user already owns a signing certificate. The nickname of this signing certificate is set in the configuration files in the procedure.

Note

The following procedure describes the two-trip issuance used with encryption-only keys, which cannot be used for signing. If you use a key which can sign certificates, pass the -q POP_SUCCESS option instead of -q POP_NONE to the CRMFPopClient utility for a single-trip issuance.

For instructions about using CRMFPoPClient with POP_SUCCESS, see Section 5.2.3.1, “Using CRMFPopClient to Create a CSR with Key Archival” and Section 5.2.3.2, “Using CRMFPopClient to Create a CSR for SharedSecret-based CMC”.

Search for the KRA transport certificate. For example:

$ pki cert-find --name KRA_transport_certificate_subject_CN

Use the serial number of the KRA transport certificate, which you retrieved in the previous step, to store the certificate in a file. For example, to store the certificate with the 12345 serial number in the /home/user_name/kra.cert file:
```
$ pki cert-show 12345 --output /home/user_name/kra.cert
```
Use the CRMFPopClient utility to:
- Create a CSR with key archival:
  1. Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
    $ cd /home/user_name/
  2. Use the CRMFPopClient utility to create a CRMF request, where the RSA private key is wrapped by the KRA transport certificate. For example, to store the request in the /home/user_name/crmf.req file:
    $ CRMFPopClient -d . -p token_password -n subject_DN -q POP_NONE \ -b /home/user_name/kra.cert -w "AES/CBC/PKCS5Padding" \ -v -o /home/user_name/crmf.req
    Note the ID of the private key displayed by the command. The ID is required in a later step as value in the request.privKeyId parameter in the configuration file for the second trip.

Create a configuration file for the CRMRequest utility, such as /home/user_name/cmc.cfg with the following content:

#numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

#input: full path for the PKCS10 request or CRMF request,
#the content must be in Base-64 encoded format
input=/home/user_name/crmf.req

#output: full path for the CMC request in binary format
output=/home/user_name/cmc.req

#tokenname: name of token where agent signing cert can be found
#(default is internal)
tokenname=internal

#nickname: nickname for user certificate which will be used
#to sign the CMC full request.
nickname=signing_certificate

#dbdir: directory for cert8.db, key3.db and secmod.db
dbdir=/home/user_name/.dogtag/nssdb/

#password: password for cert8.db which stores the agent certificate
password=password

#format: request format, either pkcs10 or crmf
format=crmf

Create the CMC request:
```
$ CMCRequest /home/user_name/cmc.cfg
```
If the command succeeds, the CMCRequest utility stored the CMC request in the file specified in the output parameter in the request configuration file.

#host: host name for the http server
host=server.example.com

#port: port number
port=8443

#secure: true for secure connection, false for nonsecure connection
secure=true

#input: full path for the enrollment request, the content must be in
#binary format
input=/home/user_name/cmc.req

#output: full path for the response in binary format
output=/home/user_name/cmc-response_round_1.bin

#tokenname: name of token where TLS client authentication cert can be found
#(default is internal)
#This parameter will be ignored if secure=false
tokenname=internal

#dbdir: directory for cert8.db, key3.db and secmod.db
#This parameter will be ignored if secure=false
dbdir=/home/user_name/.dogtag/nssdb/

#clientmode: true for client authentication, false for no client authentication
#This parameter will be ignored if secure=false
clientmode=true

#password: password for cert8.db
#This parameter will be ignored if secure=false and clientauth=false
password=password

#nickname: nickname for client certificate
#This parameter will be ignored if clientmode=false
nickname=signing_certificate

#servlet: servlet name
servlet=/ca/ee/ca/profileSubmitUserSignedCMCFull?profileId=caFullCMCUserSignedCert

Submit the CMC request to the CA:
```
$ HttpClient /home/user_name/cmc-submit.cfg
```
If the command succeeds, the HTTPClient utility stored the CMC response in the file specified in the output parameter in the configuration file.

Verify the response by passing the response file to the CMCResponse utility. For example:

$ CMCResponse -d /home/user_name/.dogtag/nssdb/ -i /home/user_name/cmc-response_round_1.bin

If the first trip was successful, CMCResponse displays output similar to the following:

Certificates:
    Certificate:
        Data:
            Version:  v3
            Serial Number: 0x1
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=pki-tomcat,O=unknown00262DFC6A5E Security Domain
            Validity:
                Not Before: Wednesday, May 17, 2017 6:06:50 PM PDT America/Los_Angeles
                Not  After: Sunday, May 17, 2037 6:06:50 PM PDT America/Los_Angeles
            Subject: CN=CA Signing Certificate,OU=pki-tomcat,O=unknown00262DFC6A5E Security Domain
...
Number of controls is 3
Control #0: CMC encrypted POP
   OID: {1 3 6 1 5 5 7 7 9}
     encryptedPOP decoded
Control #1: CMCStatusInfoV2
   OID: {1 3 6 1 5 5 7 7 25}
   BodyList: 1
   OtherInfo type: FAIL
     failInfo=POP required
Control #2: CMC ResponseInfo
   requestID: 15

For the second trip, create a configuration file for DecryptedPOP, such as /home/user_name/cmc_DecryptedPOP.cfg, which you use in a later step. Add the following content to the created file:

#numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

#input: full path for the PKCS10 request or CRMF request,
#the content must be in Base-64 encoded format
#this field is actually unused in 2nd trip
input=/home/user_name/crmf.req

#output: full path for the CMC request in binary format
#this field is actually unused in 2nd trip
output=/home/user_name/cmc2.req

#tokenname: name of token where agent signing cert can be found
#(default is internal)
tokenname=internal

#nickname: nickname for agent certificate which will be used
#to sign the CMC full request.
nickname=signing_certificate

#dbdir: directory for cert8.db, key3.db and secmod.db
dbdir=/home/user_name/.dogtag/nssdb/

#password: password for cert8.db which stores the agent
#certificate
password=password

#format: request format, either pkcs10 or crmf
format=crmf

decryptedPop.enable=true
encryptedPopResponseFile=/home/user_name/cmc-response_round_1.bin
request.privKeyId=-25aa0a8aad395ebac7e6a19c364f0dcb5350cfef
decryptedPopRequestFile=/home/user_name/cmc.DecryptedPOP.req

Create the DecryptPOP CMC request:
```
$ CMCRequest /home/user_name/cmc.DecryptedPOP.cfg
```
If the command succeeds, the CMCRequest utility stored the CMC request in the file specified in the decryptedPopRequestFile parameter in the request configuration file.

Create a configuration file for HttpClient, such as /home/user_name/decrypted_POP_cmc-submit.cfg, which you use in a later step to submit the DecryptedPOP CMC request to the CA. Add the following content to the created file:

#host: host name for the http server
host=server.example.com

#port: port number
port=8443

#secure: true for secure connection, false for nonsecure connection
secure=true

#input: full path for the enrollment request, the content must be in binary format
input=/home/user_name/cmc.DecryptedPOP.req

#output: full path for the response in binary format
output=/home/user_name/cmc-response_round_2.bin

#tokenname: name of token where TLS client authentication cert can be found (default is internal)
#This parameter will be ignored if secure=false
tokenname=internal

#dbdir: directory for cert8.db, key3.db and secmod.db
#This parameter will be ignored if secure=false
dbdir=/home/user_name/.dogtag/nssdb/

#clientmode: true for client authentication, false for no client authentication
#This parameter will be ignored if secure=false
clientmode=true

#password: password for cert8.db
#This parameter will be ignored if secure=false and clientauth=false
password=password

#nickname: nickname for client certificate
#This parameter will be ignored if clientmode=false
nickname=singing_certificate

#servlet: servlet name
servlet=/ca/ee/ca/profileSubmitUserSignedCMCFull?profileId=caFullCMCUserCert

Submit the DecryptedPOP CMC request to the CA:
```
$ HttpClient /home/user_name/decrypted_POP_cmc-submit.cfg
```
If the command succeeds, the HTTPClient utility stored the CMC response in the file specified in the output parameter in the configuration file.

To convert the CMC response to a PKCS #7 certificate chain, pass the CMC response file to the -i parameter of the CMCResponse utility. For example:

$ CMCResponse -i /home/user_name/cmc-response_round_2.bin -o /home/user_name/certs.p7

Alternatively, to display the individual certificates in PEM format, pass the -v to the utility.

If the second trip was successful, CMCResponse displays output similar to the following:

Certificates:
    Certificate:
        Data:
            Version:  v3
            Serial Number: 0x2D
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=pki-tomcat,O=unknown00262DFC6A5E Security Domain
            Validity:
                Not Before: Thursday, June 15, 2017 3:43:45 PM PDT America/Los_Angeles
                Not  After: Tuesday, December 12, 2017 3:43:45 PM PST America/Los_Angeles
            Subject: CN=user_name,UID=example,OU=keyArchivalExample
...
Number of controls is 1
Control #0: CMCStatusInfo
   OID: {1 3 6 1 5 5 7 7 1}
   BodyList: 1
   Status: SUCCESS

5.4. Renewing Certificates

This section explains how to use the different types of certificate renewal described in Section 3.4.1, “About Renewal”. You can use the methods described in this section to renew a certificate both with and without agent approval. To renew a certificate as a user without agent approval, use profiles that require the CMCUserSignedAuth authentication plug-in, and to renew with agent approval, use profiles that require the CMCAuth authentication plug-in. For further details about these plug-ins and in which profiles they are enabled by default, see Section 8.1.2, “CMC Authentication Plug-ins”.

5.4.1. Renewal Using the Same Key

Section 5.3.1, “The CMC Enrollment Process” describes how to request and issue a certificate using CMC. When a user submits the same CMC request created during this process again with the same enrollment profile, Certificate System renews the certificate with the same key.

Note

For renewing a certificate as the user using the same key, the enrollment profile must contain the uniqueKeyConstraint entry with the params.allowSameKeyRenewal parameter set to True as described in Section 3.4.1, “About Renewal” and Section 3.4.1.1.1, “Renewing Using the Same Key”.

5.4.2. Renewal Using a New Key

To renew a certificate using a new key, follow the procedure described in Section 5.3.1, “The CMC Enrollment Process”. The process for renewal is the same as for a new enrollment. When you sign the request with the same signing certificate, the newly issued certificate contains the same subjectDN attribute as the signing certificate.

5.5. Tracing Issued Certificate to CSR, and CSR to Issued Certificate

This section details how a CA agent can trace an issued certificate to the original submitted CSR, and from a CSR to an issued certificate.

If a certificate request has been approved successfully, a CA agent can do the following to search for the request and see the CSR matching the certificate:

Access the https://host_name:port/ca/agent/ca.
Click Search for Requests
Select and fill in Request ID Range (for example 12 for Lowest Request ID and 12 for Highest Request ID.
Select Request Type and choose enrollment type.
Select Request Status and choose completed status
Make sure everything else is unselected.
Click Submit.
Click on the request number. You see the certificate in clear text at this point.
To display the CSR and certificate linking, right-click and select This Frame and View Frame Source.
- Search for inputList.inputName="Certificate Request";. The request is the inputList.inputVal below that.
- Search for outputList.outputSyntax="pretty_print";. The certificate is the outputList.outputVal below that.

To search from certificate to CSR:

Access the https://host_name:port/ca/agent/ca.
Click Find.
Click Details.
You see the certificate in clear text, along with a Request ID link. Click on the link to open the Request page.
To display the certificate and CSR linking:
- Search for inputList.inputName="Certificate Request";. The request is the inputList.inputVal below that.
- Search for outputList.outputSyntax="pretty_print";. The certificate is the outputList.outputVal below that.

Chapter 6. Revoking Certificates and Issuing CRLs

The Certificate System provides methods for revoking certificates and for producing lists of revoked certificates, called certificate revocation lists (CRLs). This chapter describes the methods for revoking a certificate, describes CMC revocation, and provides details about CRLs and setting up CRLs.

6.1. About Revoking Certificates

Certificates can be revoked by an end user (the original owner of the certificate) or by a Certificate Manager agent. An end user can revoke only certificates that contain the same subject name as the certificate presented for authentication.

When revocation requests are approved, the Certificate Manager marks the corresponding certificate records in its internal database as revoked, and, if configured to do so, removes the revoked certificates from the publishing directory. These changes are reflected in the next CRL which the CA issues.

Server and client applications that use public-key certificates as ID tokens need access to information about the validity of a certificate. Because one of the factors that determines the validity of a certificate is its revocation status, these applications need to know whether the certificate being validated has been revoked. The CA has a responsibility to do the following:

Revoke the certificate if a revocation request is received by the CA and approved.
Make the revoked certificate status available to parties or applications that need to verify its validity status.

Whenever a certificate is revoked, the Certificate Manager automatically updates the status of the certificate in its internal database, it marks the copy of the certificate in its internal database as revoked and removes the revoked certificate from the publishing directory, if the Certificate Manager is configured to remove the certificate from the database.

One of the standard methods for conveying the revocation status of certificates is by publishing a list of revoked certificates, known a certificate revocation list (CRL). A CRL is a publicly available list of certificates that have been revoked.

The Certificate Manager can be configured to generate CRLs. These CRLs can be created to conform to X.509 standards by enabling extension-specific modules in the CRL configuration. The server supports standard CRL extensions through its CRL issuing points framework; see Section 6.3.3, “Setting CRL Extensions” for more information on setting up CRL extensions for issuing points. The Certificate Manager can generate a CRL every time a certificate is revoked and at periodic intervals. If publishing is set up, the CRLs can be published to a file, an LDAP directory, or an OCSP responder.

A CRL is issued and digitally signed by the CA that issued the certificates listed in the CRL or by an entity that has been authorized by that CA to issue CRLs. The CA may use a single key pair to sign both the certificates and CRLs it issues or two separate key pairs, one for signing certificates and another one for signing CRLs.

By default, the Certificate Manager uses a single key pair for signing the certificates it issues and CRLs it generates. To create another key pair for the Certificate Manager and use it exclusively for signing CRLs, see 9.2.3.11. Setting a CA to Use a Different Certificate to Sign CRLs in Red Hat Certificate System's Planning, Installation, and Deployment Guide.

CRLs are generated when issuing points are defined and configured and when CRL generation is enabled.

When CRLs are enabled, the server collects revocation information as certificates are revoked. The server attempts to match the revoked certificate against all issuing points that are set up. A given certificate can match none of the issuing points, one of the issuing points, several of the issuing points, or all of the issuing points. When a certificate that has been revoked matches an issuing point, the server stores the information about the certificate in the cache for that issuing point.

The cache is copied to the internal directory at the intervals set for copying the cache. When the interval for creating a CRL is reached, a CRL is created from the cache. If a delta CRL has been set up for this issuing point, a delta CRL is also created at this time. The full CRL contains all revoked certificate information since the Certificate Manager began collecting this information. The delta CRL contains all revoked certificate information since the last update of the full CRL.

The full CRLs are numbered sequentially, as are delta CRLs. A full CRL and a delta CRL can have the same number; in that case, the delta CRL has the same number as the next full CRL. For example, if the full CRL is the first CRL, it is CRL 1. The delta CRL is Delta CRL 2. The data combined in CRL 1 and Delta CRL 2 is equivalent to the next full CRL, which is CRL 2.

Note

When changes are made to the extensions for an issuing point, no delta CRL is created with the next full CRL for that issuing point. A delta CRL is created with the second full CRL that is created, and then all subsequent full CRLs.

The internal database stores only the latest CRL and delta CRL. As each new CRL is created, the old one is overwritten.

When CRLs are published, each update to the CRL and delta CRL is published to the locations specified in the publishing set up. The method of publishing determines how many CRLs are stored. For file publishing, each CRL that is published to a file using the number for the CRL, so no file is overwritten. For LDAP publishing, each CRL that is published replaces the old CRL in the attribute containing the CRL in the directory entry.

By default, CRLs do not contain information about revoked expired certificates. The server can include revoked expired certificates by enabling that option for the issuing point. If expired certificates are included, information about revoked certificates is not removed from the CRL when the certificate expires. If expired certificates are not included, information about revoked certificates is removed from the CRL when the certificate expires.

6.1.1. CRL Issuing Points

Because CRLs can grow very large, there are several methods to minimize the overhead of retrieving and delivering large CRLs. One of these methods partitions the entire certificate space and associates a separate CRL with every partition. This partition is called a CRL issuing point, the location where a subset of all the revoked certificates is maintained. Partitioning can be based on whether the revoked certificate is a CA certificate, whether it was revoked for a specific reason, or whether it was issued using a specific profile. Each issuing point is identified by its name.

By default, the Certificate Manager generates and publishes a single CRL, the master CRL. An issuing point can generate CRLs for all certificates, for only CA signing certificates, or for all certificates including expired certificates.

Once the issuing points have been defined, they can be included in certificates so that an application that needs to check the revocation status of a certificate can access the CRL issuing points specified in the certificate instead of the master or main CRL. Since the CRL maintained at the issuing point is smaller than the master CRL, checking the revocation status is much faster.

CRL distribution points can be associated with certificates by setting the CRLDistributionPoint extension.

6.1.2. Delta CRLs

Delta CRLs can be issued for any defined issuing point. A delta CRL contains information about any certificates revoked since the last update to the full CRL. Delta CRLs for an issuing point are created by enabling the DeltaCRLIndicator extension.

6.1.3. Publishing CRLs

The Certificate Manager can publish the CRL to a file, an LDAP-compliant directory, or to an OCSP responder. Where and how frequently CRLs are published are configured in the Certificate Manager, as described in Chapter 7, Publishing Certificates and CRLs.

Because CRLs can be very large, publishing CRLs can take a very long time, and it is possible for the process to be interrupted. Special publishers can be configured to publish CRLs to a file over HTTP1.1, and, if the process is interrupted, the CA subsystem's web server can resume publishing at the point it was interrupted, instead of having to begin again. This is described in Section 7.7, “Setting up Resumable CRL Downloads”.

6.2. Revoking Certificates

6.2.1. Performing a CMC Revocation

Similar to Certificate Management over CMS (CMC) enrollment, CMC revocation enables users to set up a revocation client, and sign the revocation request with either an agent certificate or a user certificate with a matching subjectDN attribute. Then the user can send the signed request to the Certificate Manager.

Alternatively, CMC revocation can also be authenticated using the Shared Secret Token mechanism. For details, see Section 8.1.3, “CMC SharedSecret Authentication”.

Regardless of whether a user or agent signs the request or if a Shared Secret Token is used, the Certificate Manager automatically revokes the certificate when it receives a valid revocation request.

Certificate System provides the following utilities for CMC revocation requests:

CMCRequest. For details, see Section 6.2.1.1, “Revoking a Certificate Using CMCRequest”.
CMCRevoke. For details, see Section 6.2.1.2, “Revoking a Certificate Using CMCRevoke”.

Important

Red Hat recommends using the CMCRequest utility to generate CMC revocation requests, because it provides more options than CMCRevoke.

6.2.1.1. Revoking a Certificate Using `CMCRequest`

To revoke a certificate using CMCRequest:

Create a configuration file for the CMC revocation request, such as /home/user_name/cmc-request.cfg, with the following content:

#numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

#output: full path for the CMC request in binary format
output=/home/user_name/cmc.revoke.userSigned.req

#tokenname: name of token where user signing cert can be found
#(default is internal)
tokenname=internal

#nickname: nickname for user signing certificate which will be used
#to sign the CMC full request.
nickname=signer_user_certificate

#dbdir: directory for cert8.db, key3.db and secmod.db
dbdir=/home/user_name/.dogtag/nssdb/

#password: password for cert8.db which stores the user signing
#certificate and keys
password=myPass

#format: request format, either pkcs10 or crmf.
format=pkcs10

## revocation parameters
revRequest.enable=true
revRequest.serial=45
revRequest.reason=unspecified
revRequest.comment=user test revocation
revRequest.issuer=issuer
revRequest.sharedSecret=shared_secret

Create the CMC request:
```
# CMCRequest /home/user_name/cmc-request.cfg
```
If the command succeeds, the CMCRequest utility stores the CMC request in the file specified in the output parameter in the request configuration file.

Create a configuration file, such as /home/user_name/cmc-submit.cfg, which you use in a later step to submit the CMC revocation request to the CA. Add the following content to the created file:

#host: host name for the http server
host=>server.example.com

#port: port number
port=8443

#secure: true for secure connection, false for nonsecure connection
secure=true

#input: full path for the enrollment request, the content must be
#in binary format
input=/home/user_name/cmc.revoke.userSigned.req

#output: full path for the response in binary format
output=/home/user_name/cmc.revoke.userSigned.resp

#tokenname: name of token where TLS client authentication certificate
#can be found (default is internal)
#This parameter will be ignored if secure=false
tokenname=internal

#dbdir: directory for cert8.db, key3.db and secmod.db
#This parameter will be ignored if secure=false
dbdir=/home/user_name/.dogtag/nssdb/

#clientmode: true for client authentication, false for no client
#authentication. This parameter will be ignored if secure=false
clientmode=true

#password: password for cert8.db
#This parameter will be ignored if secure=false and clientauth=false
password=password

#nickname: nickname for client certificate
#This parameter will be ignored if clientmode=false
nickname=signer_user_certificate

Important

If the CMC revocation request is signed, set the secure and clientmode parameters to true and, additionally, fill the nickname parameter.

Depending on who signed the request, the servlet parameter in the configuration file for HttpClient must be set accordingly:
- If an agent signed the request, set:
```
servlet=/ca/ee/ca/profileSubmitCMCFull
```
- If a user signed the request, set:
```
servlet=/ca/ee/ca/profileSubmitUserSignedCMCFull
```

Submit the CMC request:

# HttpClient /home/user_name/cmc-submit.cfg

For further details about revoking a certificate using CMCRequest, see the CMCRequest(1) man page.

6.2.1.2. Revoking a Certificate Using `CMCRevoke`

The CMC revocation utility, CMCRevoke, is used to sign a revocation request with an agent's certificate. This utility simply passes the required information — certificate serial number, issuer name, and revocation reason — to identify the certificate to revoke, and then the require information to identify the CA agent performing the revocation (certificate nickname and the database with the certificate).

Important

Using CMCRevoke requires that the CA administrator followed the instructions specified in the Enabling CMCRevoke for the Web User Interface section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition) during the installation.

The reason the certificate is being revoked can be any of the following (with the number being the value passed to the CMCRevoke utility):

0 — unspecified
1 — the key was compromised
2 — the CA key was compromised
3 — the employee's affiliation changed
4 — the certificate has been superseded
5 — cessation of operation
6 — the certificate is on hold

The available tool arguments are described in detail in the Command-Line Tools Guide.

6.2.1.2.1. Testing CMCRevoke

Create a CMC revocation request for an existing certificate.
```
CMCRevoke -d/path/to/agent-cert-db -nnickname -iissuerName -sserialName -mreason -ccomment
```
For example, if the directory containing the agent certificate is ~jsmith/.mozilla/firefox/, the nickname of the certificate is AgentCert, and the serial number of the certificate is 22, the command is as shown:
```
CMCRevoke -d"~jsmith/.mozilla/firefox/" -n"ManagerAgentCert" -i"cn=agentAuthMgr" -s22 -m0 -c"test comment"
```
Note
Surround values that include spaces in quotation marks.
Important
Do not have a space between the argument and its value. For example, giving a serial number of 26 is -s26, not -s 26.

Open the end-entities page.

https://server.example.com:8443/ca/ee/ca

Select the Revocation tab.
Select the CMC Revoke link on the menu.
Paste the output from the CMCRevoke into the text area.
Remove -----BEGIN NEW CERTIFICATE REQUEST----- and ----END NEW CERTIFICATE REQUEST----- from the pasted content.
Click Submit.
The returned page should confirm that correct certificate has been revoked.

6.2.2. Performing Revocation as an Agent from the Web UI

A Certificate Manager agent can use the agent services page to find a specific certificate issued by the Certificate System or to retrieve a list of certificates that match specified criteria. The certificates which are retrieved can be examined or revoked by the agent. The Certificate Manager agent can also manage the certificate revocation list (CRL).

6.2.2.1. Listing Certificates

It is possible to list certificates within a range of serial numbers. All certificates within the range may be displayed or, if the agent selects, only those that are currently valid.

To find a specific certificate or to list certificates by serial number:

Open the Certificate Manager agent services page.
Click List Certificates.

Figure 6.1. List Certificates
- To find a certificate with a specific serial number, enter the serial number in both the upper limit and lower limit fields of the List Certificates form, in either decimal or hexadecimal form. Use 0x to indicate the beginning of a hexadecimal number; for example, 0x00000006. Serial numbers are displayed in hexadecimal form in the Search Results and Details pages.
- To find all certificates within a range of serial numbers, enter the upper and lower limits of the serial number range in decimal or hexadecimal form.
Leaving either the lower limit or upper limit field blank displays the certificate with the specified number, plus all certificates before or after it in sequence.
To limit the returned list to valid certificates, select the check boxes labeled with filtering methods. It is possible to include revoked certificates, to include expired certificates or certificates that are not yet valid, or to display only valid certificates.
Enter the maximum number of certificates matching the criteria that should be returned in the results page.
When any number is entered, the first certificates up to that number matching the criteria are displayed.
Click Find.
The Certificate System displays a list of the certificates that match the search criteria. Select a certificate in the list to examine it in more detail or perform various operations on it. For more information, refer to Section 6.2.2.3, “Examining Certificate Details”.

6.2.2.2. Searching for Certificates (Advanced)

Search for certificates by more complex criteria than serial number using the advanced search form. To perform an advanced search for certificates:

Open the Certificate Manager agent services page. The agent must submit the proper client certificate to access this page.
Click Search for Certificates to display the Search for Certificates form to specify search criteria.
To search by particular criteria, use one or more of the sections of the Search for Certificates form. To use a section, select the check box, then fill in any necessary information.
- Serial Number Range. Finds a certificate with a specific serial number or lists all certificates within a range of serial numbers.
  - To find a certificate with a specific serial number, enter the serial number in both the upper limit and lower limit fields in either decimal or hexadecimal. Use 0x to indicate the beginning of a hexadecimal number, such as 0x2A. Serial numbers are displayed in hexadecimal form in the Search Results and Details pages.
  - To find all certificates within a range of serial numbers, enter the upper and lower limits of the serial number range in decimal or hexadecimal. Leaving either the lower limit or upper limit field blank returns all certificates before or after the number specified.
- Status. Selects certificates by their status. A certificate has one of the following status codes:
  - Valid. A valid certificate has been issued, its validity period has begun but not ended, and it has not been revoked.
  - Invalid. An invalid certificate has been issued, but its validity period has not yet begun.
  - Revoked. The certificate has been revoked.
  - Expired. An expired certificate has passed the end of its validity period.
  - Revoked and Expired. The certificate has passed its validity period and been revoked.
- Subject Name. Lists certificates belonging to a particular owner; it is possible to use wildcards in this field.
  Note
  Certificate System certificate request forms support all UTF-8 characters for the common name, organizational unit, and requester name fields. The common name and organization unit fields are included in the subject name of the certificate. This means that the searches for subject names support UTF-8 characters.
  This support does not include supporting internationalized domain names.
- Revocation Information. Lists certificates that have been revoked during a particular period, by a particular agent, or for a particular reason. For example, an agent can list all certificates revoked between July 2005 and April 2006 or all certificates revoked by the agent with the username admin.
  - To list certificates revoked within a time period, select the day, month, and year from the drop-down lists to identify the beginning and end of the period.
  - To list certificates revoked by a particular agent, enter the name of the agent; it is possible to use wildcards in this field.
  - To list certificates revoked for a specific reason, select the revocation reasons from the list.
- Issuing Information. Lists certificates that have been issued during a particular period or by a particular agent. For example, an agent can list all certificates issued between July 2005 and April 2006 or all certificates issued by the agent with the username jsmith.
  - To list certificates issued within a time period, select the day, month, and year from the drop-down lists to identify the beginning and end of the period.
  - To list certificates issued by a particular agent, enter the name of the agent; it is possible to use wildcards in this field.
  - To list certificates enrolled through a specific profile, enter the name of the profile.
- Dates of Validity. List certificates that become effective or expire during a particular period. For example, an agent can list all certificates that became valid on June 1, 2003, or that expired between January 1, 2006, and June 1, 2006.
  It is also possible to list certificates that have a validity period of a certain length of time, such as all certificates that are valid for less than one month.
  - To list certificates that become effective or expire within a time period, select the day, month, and year from the drop-down lists to identify the beginning and end of the period.
  - To list certificates that have a validity period of a certain length in time, select Not greater than or Not less than from the drop-down list, enter a number, and select a time unit from the drop-down list: days, weeks, months, or years.
- Basic Constraints. Shows CA certificates that are based on the Basic Constraints extension.
- Type. Lists certain types of certificates, such as all certificates for subordinate CAs. This search works only for certificates containing the Netscape Certificate Type extension, which stores type information. For each type, choose from the drop-down list to find certificates where that type is On, Off, or Do Not Care.
To find a certificate with a specific subject name, use the Subject Name section. Select the check box, then enter the subject name criteria. Enter values for the included search criteria and leave the others blank.
The standard tags or components are as follows:
- Email address. Narrows the search by email address.
- Common name. Finds certificates associated with a specific person or server.
- UserID. Searches certificates by the user ID for the person to whom the certificate belongs.
- Organization unit. Narrows the search to a specific division, department, or unit within an organization.
- Organization. Narrows the search by organization.
- Locality. Narrows the search by locality, such as the city.
- State. Narrows the search by state or province.
- Country. Narrows the search by country; use the two-letter country code, such as US.
Note
Certificate System certificate request forms support all UTF-8 characters for the common name and organizational unit fields. The common name and organization unit fields are included in the subject name of the certificate. This means that the searches for subject names or those elements in the subject name support UTF-8 characters.
This support does not include supporting internationalized domain names, such as in email addresses.
After entering the field values for the server to match, specify the type of search to perform:
- Exact searches for certificate subject names match the exact components specified and contain none of the components left blank. Wildcards cannot be used in this type of search.
- Partial searches for certificate subject names match the specified components, but the returned certificates may also contain values in components that were left blank. Wildcard patterns can be used in this type of search by using a question mark (?) to match an arbitrary single character and an asterisk (*) to match an arbitrary string of characters.
  Note
  Placing a single asterisk in a search field means that the component must be in the certificate's subject name but may have any value. Leave the field blank if it does not matter if the field is present.
After entering the search criteria, scroll to the bottom of the form, and enter the number of certificates matching the specified criteria that should be returned.
Setting the number of certificates to be returned returns the first certificates found that match the search criteria up to that number. It is also possible to put a time limit on the search in seconds.
Click Find.
The Search Results form appears, showing a list of the certificates that match the search criteria. Select a certificate in the list to examine it in more detail. For more information, refer to Section 6.2.2.3, “Examining Certificate Details”.

6.2.2.3. Examining Certificate Details

On the agent services page, click List Certificates or Search for Certificates, specify search criteria, and click Find to display a list of certificates.
On the Search Results form, select a certificate to examine.
If the desired certificate is not shown, scroll to the bottom of the list, specify an additional number of certificates to be returned, and click Find. The system displays the next certificates up to that number that match the original search criteria.
After selecting a certificate, click the Details button at the left side of its entry.
The Certificate page shows the detailed contents of the selected certificate and instructions for installing the certificate in a server or in a web browser.

Figure 6.2. Certificate Details
The certificate is shown in base-64 encoded form at the bottom of the Certificate page, under the heading Installing this certificate in a server.

6.2.2.4. Revoking Certificates

Only Certificate Manager agents can revoke certificates other than their own. A certificate must be revoked if one of the following situations occurs:

The owner of the certificate has changed status and no longer has the right to use the certificate.
The private key of a certificate owner has been compromised.

These two reasons are not the only ones why a certificate would need revoked; there are six reasons available for revoking a certificate.

To revoke one or more certificates, search for the certificates to revoke using the Revoke Certificates button. While the search is similar to the one through the Search for Certificates form, the Search Results form returned by this search offers the option of revoking one or all of the returned certificates.

6.2.2.4.1. Revoking Certificates

Open the Certificate Manager agent services page.
Click Revoke Certificates.
Note
The search form that appears has the same search criteria sections as the Search for Certificates form.
Specify the search criteria by selecting the check boxes for the sections and filling in the required information.
Scroll to the bottom of the form, and set the number of matching certificates to display.
Click Find.
The search returns a list of matching certificates. It is possible to revoke one or all certificates in the list.
Note
If the search criteria are very specific and all of the certificates returned are to be revoked, then click the Revoke ALL # Certificates button at the bottom of the page. The number shown on the button is the total number of certificates returned by the search. This is usually a larger number than the number of certificates displayed on the current page.
Verify that all of the certificates returned by the search should be revoked, not only those displayed on the current page.
Click the Revoke button next to the certificate to be revoked.
Warning
Whether revoking a single certificate or a list of certificates, be extremely careful that the correct certificate has been selected or that the list contains only certificates which should be revoked. Once a revocation operation has been confirmed, there is no way to undo it.
Select an invalidity date. The invalidity date is the date which it is known or suspected that the user's private key was compromised or that the certificate became invalid. A set of drop down lists allows the agent to select the correct invalidity date.
Select a reason for the revocation.
- Key compromised
- CA key compromised
- Affiliation changed
- Certificate superseded
- Cessation of operation
- Certificate is on hold
Enter any additional comment. The comment is included in the revocation request.

When the revocation request is submitted, it is automatically approved, and the certificate is revoked. Revocation requests are viewed by listing requests with a status of Completed.

6.2.2.4.2. Taking Ceritificates Off Hold

There can be instances when a certificate is inaccessible, and therefore should be treated as revoked, but that certificate can be recovered. For example, a user may have a personal email certificate stored on a flash drive which he accidentally leaves at home. The certificate is not compromised, but it should be temporarily suspended.

That certificate can be temporarily revoked by putting it on hold (one of the options given when revoking a certificate, as in Section 6.2.2.4.1, “Revoking Certificates”). At a later time — such as when the forgotten flash drive is picked up — that certificate can be taken off hold and is again active.

Search for the on hold certificate, as in Section 6.2.2.2, “Searching for Certificates (Advanced)”. Scroll to the Revocation Information section, and set the Certificate is on hold revocation reason as the search criterion.
In the results list, click the Off Hold button by the certificate to take off hold.

6.2.2.5. Managing the Certificate Revocation List

Revoking a certificate notifies other users that the certificate is no longer valid. This notification is done by publishing a list of the revoked certificates, called the certificate revocation list (CRL), to an LDAP directory or to a flat file. This list is publicly available and ensures that revoked certificates are not misused.

6.2.2.5.1. Viewing or Examining CRLs

It may be necessary to view or examine a CRL, such as before manually updating a directory with the latest CRL. To view or display the CRL:

Go to the Certificate Manager agent services page.
Click Display Certificate Revocation List to display the form for viewing the CRL.
Select the CRL to view. If the administrator has created multiple issuing points, these are listed in the Issuing point drop-down list. Otherwise, only the master CRL is shown.
Choose how to display the CRL by selecting one of the options from the Display Type menu. The choices on this menu are as follows:
- Cached CRL. Views the CRL from the cache rather than from the CRL itself. This option displays results faster than viewing the entire CRL.
- Entire CRL. Retrieves and displays the entire CRL.
- CRL header. Retrieves and displays the CRL header only.
- Base 64 Encoded. Retrieves and displays the CRL in base-64 encoded format.
- Delta CRL. Retrieves and displays a delta CRL, which is a subset of the CRL showing only new revocations since the last CRL was published. This option is available only if delta CRL generation is enabled.
To examine the selected CRL, click Display.
The CRL appears in the browser window. This allows the agent to check whether a particular certificate (by its serial number) appears in the list and to note recent changes such as the total number of certificates revoked since the last update, the total number of certificates taken off hold since the last update, and the total number of certificates that expired since the last update.

6.2.2.5.2. Updating the CRL

CRLs can be automatically updated if a schedule for automatic CRL generation is enabled, and the schedule can set the CRL to be generated at set time schedules or whenever there are certificate revocations.

Likewise, CRLs can be also automatically published if CRL publishing is enabled.

In some cases, the CRL may need to be updated manually, such as updating the list after the system has been down or removing expired certificates to reduce the file size. (Expired certificates do not need to be included in the CRL because they are already invalid because of the expiration date.) Only a Certificate Manager agent can manually update the CRL.

To update the CRL manually:

Open the Certificate Manager agent services page.
Click Update Revocation List to display the form for updating the CRL.

Figure 6.3. Update Certificate Revocation List
Select the CRL issuing point which will update the CRL. There can be multiple issuing points configured for a single CA.
Select the algorithm to use to sign the new CRL. Before choosing an algorithm, make sure that any system or network applications that need to read or view this CRL support the algorithm.
- SHA-256 with RSA.
- SHA-384 with RSA.
- SHA-512 with RSA.
Before selecting an algorithm, make sure that the Certificate System has that algorithm enabled. The Certificate System administrator will have that information.
Click Update to update the CRL with the latest certificate revocation information.

6.2.3. Performing Revocation on Own Certificate as a User Using the Web UI

Revoking a certificate invalidates it before its expiration date. This can be necessary if a certificate is lost, compromised, or no longer needed.

6.2.3.1. Revoking Your User Certificate

Click the Revocation tab.
Click the User Certificate link.
Select the reason why the certificate is being revoked, and click Submit.
Select the certificates to revoke from the list.

6.2.3.2. Checking Whether a Certificate Is Revoked

Click the Retrieval tab.
Click the Import Certificate Revocation List link.
Select the radio button by Check whether the following certificate is included in CRL cache or Check whether the following certificate is listed by CRL, and enter the serial number of the certificate.
Click the Submit button.
A message is returned either saying that the certificate is not listed in any CRL or giving the information for the CRL which contains the certificate.

6.2.3.3. Downloading and Importing CRLs

Certificate revocation lists (CRLs) can be downloaded and installed in a web client, application, or machine. They can also be viewed to see what certificates have been revoked.

Click the Retrieval tab.
Click the Import Certificate Revocation List link.
Select the radio button to view, download, or import the CRL.
- To import the CRL into the browser or download and save it, select the appropriate radio button. There are two options: to download/import the full CRL or the delta CRL. The delta CRL only imports/downloads the list of certificates which have been revoked since the last time the CRL was generated.
- To view the CRL, select Display the CRL information and select which CRL subset (called an issuing point) to view. This shows the CRL information, including the number of certificates included in it.
Click the Submit button.
Save the file or approve the import operation.

6.3. Issuing CRLs

The Certificate Manager uses its OCSP signing key to sign CRLs. To use a separate signing key pair for CRLs, set up a CRL signing key and change the Certificate Manager configuration to use this key to sign CRLs. See 9.2.3.11. Setting a CA to Use a Different Certificate to Sign CRLs in Red Hat Certificate System's Planning, Installation, and Deployment Guide for more information.
Set up CRL issuing points. An issuing point is already set up and enabled for a master CRL.
Figure 6.4. Default CRL Issuing Point
Additional issuing points for the CRLs can be created. See Section 6.3.1, “Configuring Issuing Points” for details.
There are five types of CRLs the issuing points can create, depending on the options set when configuring the issuing point to define what the CRL will list:
- Master CRL contains the list of revoked certificates from the entire CA.
- ARL is an Authority Revocation List containing only revoked CA certificates.
- CRL with expired certificates includes revoked certificates that have expired in the CRL.
- CRL from certificate profiles determines the revoked certificates to include based on the profiles used to create the certificates originally.
- CRLs by reason code determines the revoked certificates to include based on the revocation reason code.
Configure the CRLs for each issuing point. See Section 6.3.2, “Configuring CRLs for Each Issuing Point” for details.
Set up the CRL extensions which are configured for the issuing point. See Section 6.3.3, “Setting CRL Extensions” for details.
Set up the delta CRL for an issuing point by enabling extensions for that issuing point, DeltaCRLIndicator or CRLNumber.
Set up the CRLDistributionPoint extension to include information about the issuing point.
Set up publishing CRLs to files, an LDAP directory, or an OCSP responder. See Chapter 7, Publishing Certificates and CRLs for details about setting up publishing.

6.3.1. Configuring Issuing Points

Issuing points define which certificates are included in a new CRL. A master CRL issuing point is created by default for a master CRL containing a list of all revoked certificates for the Certificate Manager.

To create a new issuing point, do the following:

Open the Certificate System Console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, expand Certificate Manager from the left navigation menu. Then select CRL Issuing Points.
To edit an issuing point, select the issuing point, and click Edit. The only parameters which can be edited are the name of the issuing point and whether the issuing point is enabled or disabled.
To add an issuing point, click Add. The CRL Issuing Point Editor window opens.
Figure 6.5. CRL Issuing Point Editor
Note
If some fields do not appear large enough to read the content, expand the window by dragging one of the corners.
Fill in the following fields:
- Enable. Enables the issuing point if selected; deselect to disable.
- CRL Issuing Point name. Gives the name for the issuing point; spaces are not allowed.
- Description. Describes the issuing point.
Click OK.

To view and configure a new issuing point, close the CA Console, then open the Console again. The new issuing point is listed below the CRL Issuing Points entry in the navigation tree.

Configure CRLs for the new issuing point, and set up any CRL extensions that will be used with the CRL. See Section 6.3.2, “Configuring CRLs for Each Issuing Point” for details on configuring an issuing point. See Section 6.3.3, “Setting CRL Extensions” for details on setting up the CRL extensions. All the CRLs created appear on the Update Revocation List page of the agent services pages.

6.3.2. Configuring CRLs for Each Issuing Point

Information, such as the generation interval, the CRL version, CRL extensions, and the signing algorithm, can all be configured for the CRLs for the issuing point. The CRLs must be configured for each issuing point.

Open the CA console.

pkiconsole https://server.example.com:8443/ca

In the navigation tree, select Certificate Manager, and then select CRL Issuing Points.
Select the issuing point name below the Issuing Points entry.
Configure how and how often the CRLs are updated by supplying information in the Update tab for the issuing point. This tab has two sections, Update Schema and Update Frequency.
- The Update Schema section has the following options:
  - Enable CRL generation. This checkbox sets whether CRLs are generated for that issuing point.
  - Generate full CRL every # delta(s). This field sets how frequently CRLs are created in relation to the number of changes.
  - Extend next update time in full CRLs. This provides an option to set the nextUpdate field in the generated CRLs. The nextUpdate parameter shows the date when the next CRL is issued, regardless of whether it is a full or delta CRL. When using a combination of full and delta CRLs, enabling Extend next update time in full CRLs will make the nextUpdate parameter in a full CRL show when the next full CRL will be issued. Otherwise, the nextUpdate parameter in the full CRL will show when the next delta CRL will be issued, since the delta will be the next CRL to be issued.
- The Update Frequency section sets the different intervals when the CRLs are generated and issued to the directory.
  - Every time a certificate is revoked or released from hold. This sets the Certificate Manager to generate the CRL every time it revokes a certificate. The Certificate Manager attempts to issue the CRL to the configured directory whenever it is generated. Generating a CRL can be time consuming if the CRL is large. Configuring the Certificate Manager to generate CRLs every time a certificate is revoked may engage the server for a considerable amount of time; during this time, the server will not be able to update the directory with any changes it receives.
    This setting is not recommended for a standard installation. This option should be selected to test revocation immediately, such as testing whether the server issues the CRL to a flat file.
  - Update the CRL at. This field sets a daily time when the CRL should be updated. To specify multiple times, enter a comma-separate list of times, such as 01:50,04:55,06:55. To enter a schedule for multiple days, enter a comma-separated list to set the times within the same day, and then a semicolon separated list to identify times for different days. For example, this sets revocation on Day 1 of the cycle at 1:50am, 4:55am, and 6:55am and then Day 2 at 2am, 5am, and 5pm:
    01:50,04:55,06:55;02:00,05:00,17:00
  - Update the CRL every. This checkbox enables generating CRLs at the interval set in the field. For example, to issue CRLs every day, select the checkbox, and enter 1440 in this field.
  - Next update grace period. If the Certificate Manager updates the CRL at a specific frequency, the server can be configured to have a grace period to the next update time to allow time to create the CRL and issue it. For example, if the server is configured to update the CRL every 20 minutes with a grace period of 2 minutes, and if the CRL is updated at 16:00, the CRL is updated again at 16:18.
Important
Due to a known issue, when currently setting full and delta Certificate Revocation List schedules, the Update CRL every time a certificate is revoked or released from hold option also requires you to fill out the two grace period settings. Thus, in order to select this option you need to first select the Update CRL every option and enter a number for the Next update grace period # minutes box.
The Cache tab sets whether caching is enabled and the cache frequency.
Figure 6.6. CRL Cache Tab
- Enable CRL cache. This checkbox enables the cache, which is used to create delta CRLs. If the cache is disabled, delta CRLs will not be created. For more information about the cache, see Section 6.1, “About Revoking Certificates”.
- Update cache every. This field sets how frequently the cache is written to the internal database. Set to 0 to have the cache written to the database every time a certificate is revoked.
- Enable cache recovery. This checkbox allows the cache to be restored.
- Enable CRL cache testing. This checkbox enables CRL performance testing for specific CRL issuing points. CRLs generated with this option should not be used in deployed CAs, as CRLs issued for testing purposed contain data generated solely for the purpose of performance testing.
The Format tab sets the formatting and contents of the CRLs that are created. There are two sections, CRL Format and CRL Contents.
Figure 6.7. CRL Format Tab
- The CRL Format section has two options:
  Revocation list signing algorithm is a drop down list of allowed ciphers to encrypt the CRL.
  Allow extensions for CRL v2 is a checkbox which enabled CRL v2 extensions for the issuing point. If this is enabled, set the required CRL extensions described in Section 6.3.3, “Setting CRL Extensions”.
  Note
  Extensions must be turned on to create delta CRLs.
- The CRL Contents section has three checkboxes which set what types of certificates to include in the CRL:
  Include expired certificates. This includes revoked certificates that have expired. If this is enabled, information about revoked certificates remains in the CRL after the certificate expires. If this is not enabled, information about revoked certificates is removed when the certificate expires.
  CA certificates only. This includes only CA certificates in the CRL. Selecting this option creates an Authority Revocation List (ARL), which lists only revoked CA certificates.
  Certificates issued according to profiles. This only includes certificates that were issued according to the listed profiles; to specify multiple profiles, enter a comma-separated list.
Click Save.
Extensions are allowed for this issuing point and can be configured. See Section 6.3.3, “Setting CRL Extensions” for details.

6.3.3. Setting CRL Extensions

Note

Extensions only need configured for an issuing point if the Allow extensions for CRLs v2 checkbox is selected for that issuing point.

When the issuing point is created, three extensions are automatically enabled: CRLReason, InvalidityDate, and CRLNumber. Other extensions are available but are disabled by default. These can be enabled and modified. For more information about the available CRL extensions, see Section B.4.2, “Standard X.509 v3 CRL Extensions Reference”.

To configure CRL extensions, do the following:

Open the CA console.

pkiconsole https://server.example.com:8443/ca

In the navigation tree, select Certificate Manager, and then select CRL Issuing Points.
Select the issuing point name below the Issuing Points entry, and select the CRL Extension entry below the issuing point.
The right pane shows the CRL Extensions Management tab, which lists configured extensions.
Figure 6.8. CRL Extensions
To modify a rule, select it, and click Edit/View.
Most extensions have two options, enabling them and setting whether they are critical. Some require more information. Supply all required values. See Section B.4.2, “Standard X.509 v3 CRL Extensions Reference” for complete information about each extension and the parameters for those extensions.
Click OK.
Click Refresh to see the updated status of all the rules.

6.3.4. Generating CRLs from Cache

By default, CRLs are generated from the CA's internal database. However, revocation information can be collected as the certificates are revoked and kept in memory. This revocation information can then be used to update CRLs from memory. Bypassing the database searches that are required to generate the CRL from the internal database significantly improves performance.

Note

Because of the performance enhancement from generating CRLs from cache, enable the enableCRLCache parameter in most environments. However, the Enable CRL cache testing parameter should not be enabled in a production environment.

6.3.4.1. Configuring CRL Generation from Cache in the Console

Open the console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, expand the Certificate Manager folder and the CRL Issuing Points subfolder.
Select the MasterCRL node.
Select Enable CRL cache.
Save the changes.

6.4. Setting Full and Delta CRL Schedules

CRLs are generated periodically. Setting that period is touched on in the configuration in Section 6.3.2, “Configuring CRLs for Each Issuing Point”.

CRLs are issued according to a time-based schedule. CRLs can be issued every single time a certificate is revoked, at a specific time of day, or once every so-many minutes.

Time-based CRL generation schedules apply to every CRL that is generated. There are two kinds of CRLs, full CRLs and delta CRLs. A full CRL has a record of every single revoked certificate, whereas delta CRLs contain only the certificates that have been revoked since the last CRL (delta or full) was generated.

By default, full CRLs are generated at every specified interval in the schedule. It is possible space out the time between generating full CRLs by generating interim delta CRLs. The generation interval is configured in the CRL schema, which sets the scheme for generating delta and full CRLs.

If the interval is set to 3, for example, then the first CRL generated will be both a full and delta CRL, then the next two generation updates are delta CRLs only, and then the fourth interval is both a full and delta CRL again. In other words, every third generation interval has both a full CRL and a delta CRL.

Interval   1, 2, 3, 4, 5, 6, 7 ...
Full CRL   1        4        7 ...
Delta CRL  1, 2, 3, 4, 5, 6, 7 ...

Note

For delta CRLs to be generated in addition to full CRLs, the CRL cache must be enabled.

6.4.1. Configuring CRL Update Intervals in the Console

Open the console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, expand the Certificate Manager folder and the CRL Issuing Points subfolder.
Select the MasterCRL node.
Enter the required interval in the Generate full CRL every # delta(s) field.
Set the update frequency, either by specifying the occasion of a certificate revocation, a cyclical interval or set times for the updates to occur:
- Select the Update CRL every time a certificate is revoked or released from hold checkbox. The Update CRL every time a certificate is revoked or released from hold option also requires you to fill out the two Grace period settings. This is a known issue, and the bug is being tracked in Red Hat Bugzilla.
- Select the Update CRL every time a certificate is revoked or released from hold checkbox.
- Select the Update CRL at checkbox and enter specific times separated by commas, such as 01:50,04:55,06:55.
- Select Update CRL every checkbox and enter the required interval, such as 240.
Save the changes.

Important

The Update CRL every time a certificate is revoked or released from hold option also requires you to fill out the two grace period settings. This is a known issue, and the bug is being tracked in Red Hat Bugzilla.

Note

Schedule drift can occur when updating CRLs by interval. Typically, drift occurs as a result of manual updates and CA restarts.

To prevent schedule drift, select the Update CRL at checkbox and enter a value. The interval updates will resynchronize with the Update CRL at value every 24 hours.

Only one Update CRL at value will be accepted when updating CRLs by interval.

6.4.2. Configuring CRL Generation Schedules over Multiple Days

By default, CRL generaton schedules cover 24 hours. Also, by default, when full and delta CRLs are enabled full CRLs occur at specific intervals in place of one or all delta CRLs, i.e., every third update.

To set CRL generation schedules across multiple days, the list of times uses commas to separate times within the same day and a semicolon to delimit days:

ca.crl.MasterCRL.dailyUpdates=01:00,03:00,18:00;02:00,05:00,17:00

This example updates CRLs on day one of the schedule at 01:00, 03:00, and 18:00, and on day two of the schedule at 02:00, 05:00, and 17:00. On day three the cycle starts again.

Note

The semicolon indicates a new day. Starting the list with a semicolon results in an initial day where no CRLs are generated. Likewise, ending the list with a semicolon adds a final day to the schedule where no CRLs are generated. Two semicolons together result in a day with no CRL generation.

To set full CRL updates independent of delta updates, the list of times accepts time values prepended with an asterisk to indicate when full CRL updates should occur:

ca.crl.MasterCRL.dailyUpdates=01:00,03:00,18:00,*23:00;02:00,05:00,21:00,*23:30

This example generates delta CRL updates on day one at 01:00, 03:00, and 18:00, with a full and delta CRL update at 23:00. On day two, delta CRLs are updated at 02:00, 05:00, and 21:00, with a full and delta CRL update at 23:30. On day three, the cycle starts again.

Note

Both the semicolon and asterisk syntax works in the console.

6.5. Using the Online Certificate Status Protocol (OCSP) Responder

6.5.1. Setting up the OCSP Responder

If a CA within the security domain is selected when the Online Certificate Status Manager is configured, there is no extra step required to configure the OCSP service. The CA's CRL publishing is set up automatically, and its signing certificate is automatically added and trusted in the Online Certificate Status Manager's certificate database. However, if a non-security domain CA is selected, then the OCSP service must be manually configured after the Online Certificate Status Manager is configured.

Note

Not every CA within the security domain to which the OCSP Manager belongs 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 trusted automatically by the OCSP Manager. Other CAs within the security domain but not in the certificate chain must be trusted manually.

To set up the Online Certificate Status Manager for a Certificate Manager outside the security domain:

Configure the CRLs for every CA that will publish to an OCSP responder.
Enable publishing, set up a publisher, and set publishing rules in every CA that the OCSP service will handle (Chapter 7, Publishing Certificates and CRLs). This is not necessary if the Certificate Managers publish to an LDAP directory and the Online Certificated Status Manager is set up to read from that directory.
The certificate profiles must be configured to include the Authority Information Access extension, pointing to the location at which the Certificate Manager listens for OCSP service requests (Section 6.5.4, “Enabling the Certificate Manager's Internal OCSP Service”).
Configure the OCSP Responder.
- Configure the Revocation Info store (Section 6.5.2.2, “Configure the Revocation Info Stores: Internal Database” and Section 6.5.2.3, “Configure the Revocation Info Stores: LDAP Directory”).
- Identify every publishing Certificate Manager to the OCSP responder (Section 6.5.2, “Identifying the CA to the OCSP Responder”).
- If necessary, configure the trust settings for the CA which signed the OCSP signing certificate (Section 14.5, “Changing the Trust Settings of a CA Certificate”).
Restart both subsystems after configuring them.
Verify that the CA is properly connected to the OCSP responder (Section 6.5.2.1, “Verify Certificate Manager and Online Certificate Status Manager Connection”).

6.5.2. Identifying the CA to the OCSP Responder

Before a CA is configured to publish CRLs to the Online Certificate Status Manager, the CA must be identified to the Online Certificate Status Manager by storing the CA signing certificate in the internal database of the Online Certificate Status Manager. The Certificate Manager signs CRLs with the key pair associated with this certificate; the Online Certificate Status Manager verifies the signature against the stored certificate.

Note

If a CA within the security domain is selected when the Online Certificate Status Manager is configured, there is no extra step required to configure the Online Certificate Status Manager to recognize the CA; the CA signing certificate is automatically added and trusted in the Online Certificate Status Manager's certificate database. However, if a non-security domain CA is selected, then the CA signing certificate must be manually added to the certificate database after the Online Certificate Status Manager is configured.

It is not necessary to import the certificate chain for a CA which will publish its CRL to the Online Certificate Status Manager. The only time a certificate chain is needed for the OCSP service is if the CA connects to the Online Certificate Status Manager through TLS authentication when it publishes its CRL. Otherwise, the Online Certificate Status Manager does not need to have the complete certificate chain.

However, the Online Certificate Status Manager must have the certificate which signed the CRL, either a CA signing certificate or a separate CRL signing certificate, in its certificate database. The OCSP service verifies the CRL by comparing the certificate which signed the CRL against the certificates in its database, not against a certificate chain. If both a root CA and one of its subordinate CAs publish CRLs to the Online Certificate Status Manager, the Online Certificate Status Manager needs the CA signing certificate of both CAs.

To import the CA or CRL signing certificate which is used to sign the certificates the CA is publishing to the Online Certificate Status Manager, do the following:

Get the Certificate Manager's base-64 CA signing certificate from the end-entities page of the CA.
Open the Online Certificate Status Manager agent page. The URL has the format https://hostname:SSLport/ocsp/agent/ocsp.
In the left frame, click Add Certificate Authority.
In the form, paste the encoded CA signing certificate inside the text area labeled Base 64 encoded certificate (including the header and footer).
To verify that the certificate is added successfully, in the left frame, click List Certificate Authorities.

The resulting form should show information about the new CA. The This Update, Next Update, and Requests Served Since Startup fields should show a value of zero (0).

6.5.2.1. Verify Certificate Manager and Online Certificate Status Manager Connection

When the Certificate Manager is restarted, it tries to connect to the Online Certificate Status Manager's TLS port. To verify that the Certificate Manager did indeed communicate with the Online Certificate Status Manager, check the This Update and Next Update fields, which should be updated with the appropriate timestamps of the CA's last communication with the Online Certificate Status Manager. The Requests Served Since Startup field should still show a value of zero (0) since no client has tried to query the OCSP service for certificate revocation status.

6.5.2.2. Configure the Revocation Info Stores: Internal Database

The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses it as the CRL store for verifying the revocation status of certificates. To change the configuration that the Online Certificate Status Manager uses for storing the CRLs in its internal database:

Open the Online Certificate Status Manager Console.
```
pkiconsole https://server.example.com:8443/ocsp
```
In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.
The right pane shows the two repositories the Online Certificate Status Manager can use; by default, it uses the CRL in its internal database.
Select the defStore, and click Edit/View.
Edit the defStore values.
- notFoundAsGood. Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is UNKNOWN, which, when encountered by a client, results in an error message.
- byName. The OCSP Responder only supports the basic response type, which includes the ID of the OCSP Responder making the response. The ResponderID field within the basic response type is determined by the value of the ocsp.store.defStore.byName parameter. If byName parameter is true or is missing, the OCSP authority signing certificate subject name is used as the ResponderID field of the OCSP response. If byName parameter is false, the OCSP authority signing certificate key hash will be the ResponderID field of the OCSP response.
- includeNextUpdate. Includes the timestamp of the next CRL update time.

6.5.2.3. Configure the Revocation Info Stores: LDAP Directory

Although the OCSP Manager stores the CA CRLs in its internal database by default, it can be configured to use a CRL published to an LDAP directory instead.

Important

If the ldapStore method is enabled, the OCSP user interface does not check the certificate status.

To configure the Online Certificate Status Manager to use an LDAP directory:

Open the Online Certificate Status Manager Console.
```
pkiconsole https://server.example.com:8443/ocsp
```
In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.
The right pane shows the two repositories the Online Certificate Status Manager can use; by default, it uses the CRL in its internal database.
To use the CRLs in LDAP directories, click Set Default to enable the ldapStore option.
Select ldapStore, and click Edit/View.
Set the ldapStore parameters.
- numConns. The total number of LDAP directories the OCSP service should check. By default, this is set to 0. Setting this value shows the corresponding number of host, port, baseDN, and refreshInSec fields.
- host. The fully-qualified DNS hostname of the LDAP directory.
- port. The non-TLS port of the LDAP directory.
- baseDN. The DN to start searching for the CRL. For example, O=example.com.
- refreshInSec. How often the connection is refreshed. The default is 86400 seconds (daily).
- caCertAttr. Leave the default value, cACertificate;binary, as it is. It is the attribute to which the Certificate Manager publishes its CA signing certificate.
- crlAttr. Leave the default value, certificateRevocationList;binary, as it is. It is the attribute to which the Certificate Manager publishes CRLs.
- notFoundAsGood. Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is UNKNOWN, which, when encountered by a client, results in an error message.
- byName. The OCSP Responder only supports the basic response type, which includes the ID of the OCSP Responder making the response. The ResponderID field within the basic response type is determined by the value of the ocsp.store.defStore.byName parameter. If byName parameter is true or is missing, the OCSP authority signing certificate subject name is used as the ResponderID field of the OCSP response. If byName parameter is false, the OCSP authority signing certificate key hash will be the ResponderID field of the OCSP response.
- includeNextUpdate. The Online Certificate Status Manager can include the timestamp of the next CRL update time.

6.5.2.4. Testing the OCSP Service Setup

Test whether the Certificate Manager can service OCSP requests properly by doing the following:

Turn on revocation checking in the browser or client.
Request a certificate from the CA that has been enabled for OCSP services.
Approve the request.
Download the certificate to the browser or client.
Make sure the CA is trusted by the browser or client.
Check the status of Certificate Manager's internal OCSP service.
Open the CA agent services page, and select the OCSP Services link.
Test the independent Online Certificate Status Manager subsystem.
Open the Online Certificate Status Manager agent services page, and click the List Certificate Authorities link.
The page should show information about the Certificate Manager configured to publish CRLs to the Online Certificate Status Manager. The page also summarizes the Online Certificate Status Manager's activity since it was last started.
Revoke the certificate.
Verify the certificate in the browser or client. The server should return that the certificate has been revoked.
Check the Certificate Manager's OCSP-service status again to verify that these things happened:
- The browser sent an OCSP query to the Certificate Manager.
- The Certificate Manager sent an OCSP response to the browser.
- The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.
Check the independent OCSP service subsystem again to verify that these things happened:
- The Certificate Manager published the CRL to the Online Certificate Status Manager.
- The browser sent an OCSP response to the Online Certificate Status Manager.
- The Online Certificate Status Manager sent an OCSP response to the browser.
- The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.

6.5.3. Setting the Response for Bad Serial Numbers

OCSP responders check the revocation status and expiration date of a certificate before determining whether the certificate is valid; by default, the OCSP does not validate other information on the certificate.

The notFoundAsGood parameter sets how the OCSP handles a certificate with an invalid serial number. This parameter is enabled by default, which means that if a certificate is present with a bad serial number but the certificate is otherwise valid, the OCSP returns a status of GOOD for the certificate.

To have the OCSP check and reject certificates based on bad serial numbers as well as revocation status, change the notFoundAsGood setting. In that case, the OCSP returns a status of UNKNOWN with a certificate with a bad serial number. The client interprets that as an error and can respond accordingly.

Open the Online Certificate Status Manager Console.
```
pkiconsole https://server.example.com:8443/ocsp
```
In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.
Select the defStore, and click Edit/View.
Edit the notFoundAsGood value. Selecting the checkbox means that the OCSP returns a value of GOOD even if the serial number on the certificate is bad. Unselecting the checkbox means that the OCSP sends a value of UNKNOWN, which the client can intrepret as an error.

Restart the OCSP Manager.

systemctl restart pki-tomcatd-nuxwdog@instance_name.service

6.5.4. Enabling the Certificate Manager's Internal OCSP Service

The Certificate Manager has a built-in OCSP service, which can be used by OCSP-compliant clients to query the Certificate Manager directly about the revocation status of the certificate. When the Certificate Manager is installed, an OCSP signing certificate is issued and the OCSP service is turned on by default. This OCSP signing certificate is used to sign all responses to OCSP service requests. Since the internal OCSP service checks the status of certificates stored in the Certificate Manager's internal database, publishing does not have to be configured to use this service.

Clients can query the OCSP service through the non-TLS end-entity port of the Certificate Manager. When queried for the revocation status of a certificate, the Certificate Manager searches its internal database for the certificate, checks its status, and responds to the client. Since the Certificate Manager has real-time status of all certificates it has issued, this method of revocation checking is the most accurate.

Every CA's built-in OCSP service is turned on at installation. However, to use this service, the CA needs to issue certificates with the Authority Information Access extension.

Go to the CA's end-entities page. For example:
```
https://server.example.com:8443/ca/ee/ca
```
Find the CA signing certificate.
Look for the Authority Info Access extension in the certificate, and note the Location URIName value, such as https://server.example.com:8443/ca/ocsp.
Update the enrollment profiles to enable the Authority Information Access extension, and set the Location parameter to the Certificate Manager's URI. For information on editing the certificate profiles, see Section 3.2, “Setting up Certificate Profiles”.

Restart the CA instance.

systemctl restart pki-tomcatd-nuxwdog@instance_name.service

6.5.5. Submitting OCSP Requests Using the OCSPClient program

The OCSPClient program can be used for performing OCSP requests. For example:

]# OCSPClient -h server.example.com -p 8080 -d /etc/pki/pki-tomcat/alias -c "caSigningCert cert-pki-ca" --serial 2
CertID.serialNumber=2
CertStatus=Good

The OCSPClient command can be used with the following command-line options:

Table 6.1. Available OCSPClient Options
Option	Description
-d database	Security database location (default: current directory)
-h hostname	OCSP server hostname (default: example.com)
-p port	OCSP server port number (default: 8080)
-t path	OCSP service path (default: /ocsp/ee/ocsp)
-c nickname	CA certificate nickname (defaut: CA Signing Certificate)
-n times	Number of submissions (default: 1)
--serial serial_number	Serial number of certificate to be checked
--input input_file	Input file containing DER-encoded OCSP request
--output output_file	Output file to store DER-encoded OCSP response
-v, --verbose	Run in verbose mode
--help	Show help message

6.5.6. Submitting OCSP Requests Using the GET Method

OCSP requests which are smaller than 255 bytes can be submitted to the Online Certificate Status Manager using a GET method, as described in RFC 6960. To submit OCSP requests over GET:

Generate an OCSP request for the certificate the status of which is being queried. For example:

]# openssl ocsp -CAfile ca.pem -issuer issuer.pem -serial serial_number -reqout - | base64 

MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=

Paste the URL in the address bar of a web browser to return the status information. The browser must be able to handle OCSP requests.

https://server.example.com:8443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=

The OCSP Manager responds with the certificate status which the browser can interpret. The possible statuses are GOOD, REVOKED, and UNKNOWN.

Alternatively, run the OCSP from the command line by using a tool such as curl to send the request and openssl to parse the response. For example:

Generate an OCSP request for the certificate the status of which is being queried. For example:

]# openssl ocsp -CAfile ca.pem -issuer issuer.pem -serial serial_number -reqout - | base64 

MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=

Connect to the OCSP Manager using curl to send the OCSP request.

curl https://server.example.com:8443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE= > ocspresp.der

Parse the response using openssl:

openssl ocsp -respin ocspresp.der -resp_text

Part III. Additional Configuration to Manage CA Services

Chapter 7. Publishing Certificates and CRLs

Note

Features in this section on TMS are not tested in the evaluation. This section is for reference only.

Red Hat Certificate System includes a customizable publishing framework for the Certificate Manager, enabling certificate authorities to publish certificates, certificate revocation lists (CRLs), and other certificate-related objects to any of the supported repositories: an LDAP-compliant directory, a flat file, and an online validation authority. This chapter explains how to configure a Certificate Manager to publish certificates and CRLs to a file, to a directory, and to the Online Certificate Status Manager.

The general process to configure publishing is as follows:

Configure publishing to a file, LDAP directory, or OCSP responder.
There can be a single publisher or multiple publishers, depending on how many locations will be used. The locations can be split by certificates and CRLs or narrower definitions, such as certificate type. Rules determine which type to publish and to what location by being associated with the publisher.
Set rules to determine what certificates are published to the locations. Any rule which a certificate or CRL matches is activated, so the same certificate can be published to a file and to an LDAP directory by matching a file-based rule and matching a directory-based rule.
Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. Disable all rules that will not be used.
Configure CRLs. CRLs must be configured before they can be published. See Chapter 6, Revoking Certificates and Issuing CRLs.
Enable publishing after setting up publishers, mappers, and rules. Once publishing is enabled, the server starts publishing immediately. If the publishers, mappers, and rules are not completely configured, publishing may not work correctly or at all.

7.1. About Publishing

The Certificate System is capable of publishing certificates to a file or an LDAP directory and of publishing CRLs to a file, an LDAP directory, or to an OCSP responder.

For additional flexibility, specific types of certificates or CRLs can be published to a single format or all three. For example, CA certificates can be published only to a directory and not to a file, and user certificates can be published to both a file and a directory.

Note

An OCSP responder only provides information about CRLs; certificates are not published to an OCSP responder.

Different publishing locations can be set for certificates files and CRL files, as well as different publishing locations for different types of certificates files or different types of CRL files.

Similarly, different types of certificates and different types of CRLs can be published to different places in a directory. For example, certificates for users from the West Coast division of a company can be published in one branch of the directory, while certificates for users in the East Coast division can be published to another branch in the directory.

When publishing is enabled, every time a certificate or a CRL is issued, updated, or revoked, the publishing system is invoked. The certificate or CRL is evaluated by the rules to see if it matches the type and predicate set in the rule. The type specifies if the object is a CRL, CA certificate, or any other certificate. The predicate sets more criteria for the type of object being evaluated. For example, it can specify user certificates, or it can specify West Coast user certificates. To use predicates, a value needs to be entered in the predicate field of the publishing rule, and a corresponding value (although formatted somewhat differently) needs to be contained in the certificate or certificate request to match. The value in the certificate or certificate request may be derived from information in the certificate, such as the type of certificate, or may be derived from a hidden value that is placed in the request form. If no predicate is set, all certificates of that type are considered to match. For example, all CRLs match the rule if CRL is set as the type.

Every rule that is matched publishes the certificate or CRL according to the method and location specified in that rule. A given certificate or CRL can match no rules, one rule, more than one rule, or all rules. The publishing system attempts to match every certificate and CRL issued against all rules.

When a rule is matched, the certificate or CRL is published according to the method and location specified in the publisher associated with that rule. For example, if a rule matches all certificates issued to users, and the rule has a publisher that publishes to a file in the location /etc/CS/certificates, the certificate is published as a file to that location. If another rule matches all certificates issued to users, and the rule has a publisher that publishes to the LDAP attribute userCertificate;binary attribute, the certificate is published to the directory specified when LDAP publishing was enabled in this attribute in the user's entry.

For rules that specify to publish to a file, a new file is created when either a certificate or a CRL is issued in the stipulated directory.

For rules that specify to publish to an LDAP directory, the certificate or CRL is published to the entry specified in the directory, in the attribute specified. The CA overwrites the values for any published certificate or CRL attribute with any subsequent certificate or CRL. Simply put, any existing certificate or CRL that is already published is replaced by the next certificate or CRL.

For rules that specify to publish to an Online Certificate Status Manager, a CRL is published to this manager. Certificates are not published to an Online Certificate Status Manager.

For LDAP publishing, the location of the user's entry needs to be determined. Mappers are used to determine the entry to which to publish. The mappers can contain an exact DN for the entry, some variable that associates information that can be gotten from the certificate to create the DN, or enough information to search the directory for a unique attribute or set of attributes in the entry to ascertain the correct DN for the entry.

When a certificate is revoked, the server uses the publishing rules to locate and delete the corresponding certificate from the LDAP directory or from the filesystem.

When a certificate expires, the server can remove that certificate from the configured directory. The server does not do this automatically; the server must be configured to run the appropriate job.

Setting up publishing involves configuring publishers, mappers, and rules.

7.1.1. Publishers

Publishers specify the location to which certificates and CRLs are published. When publishing to a file, publishers specify the filesystem publishing directory. When publishing to an LDAP directory, publishers specify the attribute in the directory that stores the certificate or CRL; a mapper is used to determine the DN of the entry. For every DN, a different formula is set for deriving that DN. The location of the LDAP directory is specified when LDAP publishing is enabled. When publishing a CRL to an OCSP responder, publishers specify the hostname and URI of the Online Certificate Status Manager.

7.1.2. Mappers

Mappers are only used in LDAP publishing. Mappers construct the DN for an entry based on information from the certificate or the certificate request. The server has information from the subject name of the certificate and the certificate request and needs to know how to use this information to create a DN for that entry. The mapper provides a formula for converting the information available either to a DN or to some unique information that can be searched in the directory to obtain a DN for the entry.

7.1.3. Rules

Rules for file, LDAP, and OCSP publishing tell the server whether and how a certificate or CRL is to be published. A rule first defines what is to be published, a certificate or CRL matching certain characteristics, by setting a type and predicate for the rule. A rule then specifies the publishing method and location by being associated with a publisher and, for LDAP publishing, with a mapper.

Rules can be as simple or complex as necessary for the PKI deployment and are flexible enough to accommodate different scenarios.

7.1.4. Publishing to Files

The server can publish certificates and CRLs to flat files, which can then be imported into any repository, such as a relational database. When the server is configured to publish certificates and CRLs to file, the published files are DER-encoded binary blobs, base-64 encoded text blobs, or both.

For each certificate the server issues, it creates a file that contains the certificate in either DER-encoded or base-64 encoded format. Each file is named either cert-serial_number.der or cert-serial_number.b64. The serial_number is the serial number of the certificate contained in the file. For example, the filename for a DER-encoded certificate with the serial number 1234 is cert-1234.der.
Every time the server generates a CRL, it creates a file that contains the new CRL in either DER-encoded or base-64 encoded format. Each file is named either issuing_point_name-this_update.der or issuing_point_name-this_update.b64, depending on the format. The issuing_point_name identifies the CRL issuing point which published the CRL, and this_update specifies the value derived from the time-dependent update value for the CRL contained in the file. For example, the filename for a DER-encoded CRL with the value This Update: Friday January 28 15:36:00 PST 2021, is MasterCRL-20210128-153600.der.

7.1.5. OCSP Publishing

There are two forms of Certificate System OCSP services, an internal service for the Certificate Manager and the Online Certificate Status Manager. The internal service checks the internal database of the Certificate Manager to report on the status of a certificate. The internal service is not set for publishing; it uses the certificates stored in its internal database to determine the status of a certificate. The Online Certificate Status Manager checks CRLs sent to it by Certificate Manager. A publisher is set for each location a CRL is sent and one rule for each type of CRL sent.

For detailed information on both OCSP services, see Section 6.5, “Using the Online Certificate Status Protocol (OCSP) Responder”.

7.1.6. LDAP Publishing

In LDAP publishing, the server publishes the certificates, CRLs, and other certificate-related objects to a directory using LDAP or LDAPS. The branch of the directory to which it publishes is called the publishing directory.

For each certificate the server issues, it creates a blob that contains the certificate in its DER-encoded format in the specified attribute of the user's entry. The certificate is published as a DER encoded binary blob.
Every time the server generates a CRL, it creates a blob that contains the new CRL in its DER-encoded format in the specified attribute of the entry for the CA.

The server can publish certificates and CRLs to an LDAP-compliant directory using the LDAP protocol or LDAP over TLS (LDAPS) protocol, and applications can retrieve the certificates and CRLs over HTTP. Support for retrieving certificates and CRLs over HTTP enables some browsers to import the latest CRL automatically from the directory that receives regular updates from the server. The browser can then use the CRL to check all certificates automatically to ensure that they have not been revoked.

For LDAP publishing to work, the user entry must be present in the LDAP directory.

If the server and publishing directory become out of sync for some reason, privileged users (administrators and agents) can also manually initiate the publishing process. For instructions, see Section 7.11.2, “Manually Updating the CRL in the Directory”.

7.2. Configuring Publishing to a File

The general process to configure publishing involves setting up a publisher to publish the certificates or CRLs to the specific location. There can be a single publisher or multiple publishers, depending on how many locations will be used. The locations can be split by certificates and CRLs or finer definitions, such as certificate type. Rules determine which type to publish and to what location by being associated with the publisher.

Publishing to file simply publishes the CRLs or certificates to text files on a given host.

Publishers must be created and configured for each publishing location; publishers are not automatically created for publishing to a file. To publish all files to a single location, create one publisher. To publish to different locations, create a publisher for each location. A location can either contain an object type, like user certificates, or a subset of an object type, like West Coast user certificates.

To create publishers for publishing to files:

Log into the Certificate Manager Console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Publishers.
The Publishers Management tab, which lists configured publisher instances, opens on the right.
Click Add to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
Select the FileBasedPublisher module, then open the editor window.
This is the module that enables the Certificate Manager to publish certificates and CRLs to files.
Configure the information for publishing the certificate:
- The publisher ID, an alphanumeric string with no spaces like PublishCertsToFile
- The path to the directory in which the Certificate Manager should publish the files. The path can be an absolute path or can be relative to the Certificate System instance directory. For example, /export/CS/certificates.
- The file type to publish, by selecting the checkboxes for DER-encoded files, base-64 encoded files, or both.
- For CRLs, the format of the timestamp. Published certificates include serial numbers in their file names, while CRLs use timestamps.
- For CRLs, whether to generate a link in the file to go to the latest CRL. If enabled, the link assumes that the name of the CRL issuing point to use with the extension will be supplied in the crlLinkExt field.
- For CRLs, whether to compress (zip) CRLs and the compression level to use.

After configuring the publisher, configure the rules for the published certificates and CRLs, as described in Section 7.5, “Creating Rules”.

7.3. Configuring Publishing to an OCSP

Publishing to an OCSP Manager is a way to publish CRLs to a specific location for client verification.

A publisher must be created and configured for each publishing location; publishers are not automatically created for publishing to the OCSP responder. Create a single publisher to publish everything to s single location, or create a publisher for every location to which CRLs will be published. Each location can contain a different kind of CRL.

7.3.1. Enabling Publishing to an OCSP with Client Authentication

Log into the Certificate Manager Console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Publishers.
Click Add to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
Select the OCSPPublisher module, then open the editor window. This is the publisher module that enables the Certificate Manager to publish CRLs to the Online Certificate Status Manager.
- The publisher ID must be an alphanumeric string with no spaces, like PublishCertsToOCSP.
- The host can be the fully-qualified domain name, such as ocspResponder.example.com, or an IPv4 or IPv6 address.
- The default path is the directory to send the CRL to, like /ocsp/agent/ocsp/addCRL.
- If client authentication is used (enableClientAuth is checked), then the nickname field gives the nickname of the certificate to use for authentication. This certificate must already exist in the OCSP security database; this will usually be the CA subsystem certificate.
Create a user entry for the CA on the OCSP Manager. The user is used to authenticate to the OCSP when sending a new CRL. There are two things required:
- Name the OCSP user entry after the CA server, like CA-hostname-EEport.
- Use whatever certificate was specified in the publisher configuration as the user certificate in the OCSP user account. This is usually the CA's subsystem certificate.
Setting up subsystem users is covered in Section 12.3.2.1, “Creating Users”.

After configuring the publisher, configure the rules for the published certificates and CRLs, as described in Section 7.5, “Creating Rules”.

7.4. Configuring Publishing to an LDAP Directory

Configuring LDAP publishing is similar to other publishing procedures, with additional steps to configure the directory:

Configure the Directory Server to which certificates will be published. Certain attributes have to be added to entries and bind identities and authentication methods have to be configured.
Configure a publisher for each type of object published: CA certificates, cross-pair certificates, CRLs, and user certificates. The publisher declares in which attribute to store the object. The attributes set by default are the X.500 standard attributes for storing each object type. This attribute can be changed in the publisher, but generally, it is not necessary to change the LDAP publishers.
Set up mappers to enable an entry's DN to be derived from the certificate's subject name. This generally does not need set for CA certificates, CRLs, and user certificates. There can be more than one mapper set for a type of certificate. This can be useful, for example, to publish certificates for two sets of users from different divisions of a company who are located in different parts of the directory tree. A mapper is created for each of the groups to specify a different branch of the tree.
For details about setting up mappers, see Section 7.4.3, “Creating Mappers”.
Create rules to connect publishers to mappers, as described in Section 7.5, “Creating Rules”.
Enable publishing, as described in Section 7.6, “Enabling Publishing”.

7.4.1. Configuring the LDAP Directory

Before certificates and CRLs can be published, the Directory Server must be configured to work with the publishing system. This means that user entries must have attributes that allow them to receive certificate information, and entries must be created to represent the CRLs.

Set up the entry for the CA. For the Certificate Manager to publish its CA certificate and CRL, the directory must include an entry for the CA.
Note
When LDAP publishing is configured, the Certificate Manager automatically creates or converts an entry for the CA in the directory. This option is set in both the CA and CRL mapper instances and enabled by default. If the directory restricts the Certificate Manager from creating entries in the directory, turn off this option in those mapper instances, and add an entry for the CA manually in the directory.
When adding the CA's entry to the directory, select the entry type based on the DN of the CA:
- If the CA's DN begins with the cn component, create a new person entry for the CA. Selecting a different type of entry may not allow the cn component to be specified.
- If the CA's DN begins with the ou component, create a new organizationalunit entry for the CA.
The entry does not have to be in the pkiCA or certificationAuthority object class. The Certificate Manager will convert this entry to the pkiCA or certificationAuthority object class automatically by publishing its CA's signing certificate.
Note
The pkiCA object class is defined in RFC 4523, while the certificationAuthority object class is defined in the (obsolete) RFC 2256. Either object class is acceptable, depending on the schema definitions used by the Directory Server. In some situations, both object classes can be used for the same CA entry.
For more information on creating directory entries, see the Red Hat Directory Server documentation.

Add the correct schema elements to the CA and user directory entries.

For a Certificate Manager to publish certificates and CRLs to a directory, it must be configured with specific attributes and object classes.

Object Type	Schema	Reason
End-entity certificate	userCertificate;binary (attribute)	This is the attribute to which the Certificate Manager publishes the certificate. This is a multi-valued attribute, and each value is a DER-encoded binary X.509 certificate. The LDAP object class named `inetOrgPerson` allows this attribute. The `strongAuthenticationUser` object class allows this attribute and can be combined with any other object class to allow certificates to be published to directory entries with other object classes. The Certificate Manager does not automatically add this object class to the schema table of the corresponding Directory Server. If the directory object that it finds does not allow the `userCertificate;binary` attribute, adding or removing the certificate fails.
CA certificate	caCertificate;binary (attribute)	This is the attribute to which the Certificate Manager publishes the certificate. The Certificate Manager publishes its own CA certificate to its own LDAP directory entry when the server starts. The entry corresponds to the Certificate Manager's issuer name. This is a required attribute of the `pkiCA` or `certificationAuthority` object class. The Certificate Manager adds this object class to the directory entry for the CA if it can find the CA's directory entry.
CRL	certificateRevocationList;binary (attribute)	This is the attribute to which the Certificate Manager publishes the CRL. The Certificate Manager publishes the CRL to its own LDAP directory entry. The entry corresponds to the Certificate Manager's issuer name. This is an attribute of the `pkiCA` or `certificationAuthority` object class. The value of the attribute is the DER-encoded binary X.509 CRL. The CA's entry must already contain the `pkiCA` or `certificationAuthority` object class for the CRL to be published to the entry.
Delta CRL	deltaRevocationList;binary (attribute)	This is the attribute to which the Certificate Manager publishes the delta CRL. The Certificate Manager publishes the delta CRL to its own LDAP directory entry, separate from the full CRL. The delta CRL entry corresponds to the Certificate Manager's issuer name. This attribute belongs to the `deltaCRL` or `certificationAuthority-V2` object class. The value of the attribute is the DER-encoded binary X.509 delta CRL.

Set up a bind DN for the Certificate Manager to use to access the Directory Server.
The Certificate Manager user must have read-write permissions to the directory to publish certificates and CRLs to the directory so that the Certificate Manager can modify the user entries with certificate-related information and the CA entry with CA's certificate and CRL related information.
The bind DN entry can be either of the following:
- An existing DN that has write access, such as the Directory Manager.
- A new user which is granted write access. The entry can be identified by the Certificate Manager's DN, such as cn=testCA, ou=Research Dept, o=Example Corporation, st=California, c=US.
  Note
  Carefully consider what privileges are given to this user. This user can be restricted in what it can write to the directory by creating ACLs for the account. For instructions on giving write access to the Certificate Manager's entry, see the Directory Server documentation.
Set the directory authentication method for how the Certificate Manager authenticates to Directory Server. There are three options: basic authentication (simple username and password); TLS without client authentication (simple username and password); and TLS with client authentication (certificate-based).
See the Red Hat Directory Server documentation for instructions on setting up these methods of communication with the server.

7.4.2. Configuring LDAP Publishers

The Certificate Manager creates, configures, and enables a set of publishers that are associated with LDAP publishing. The default publishers (for CA certificates, user certificates, CRLs, and cross-pair certificates) already conform to the X.500 standard attributes for storing certificates and CRLs and do not need to be changed.

Table 7.1. LDAP Publishers
Publisher	Description
LdapCaCertPublisher	Publishes CA certificates to the LDAP directory.
LdapCrlPublisher	Publishes CRLs to the LDAP directory.
LdapDeltaCrlPublisher	Publishes delta CRLs to the LDAP directory.
LdapUserCertPublisher	Publishes all types of end-entity certificates to the LDAP directory.
LdapCrossCertPairPublisher	Publishes cross-signed certificates to the LDAP directory.

7.4.3. Creating Mappers

Mappers are only used with LDAP publishing. Mappers define a relationship between a certificate's subject name and the DN of the directory entry to which the certificate is published. The Certificate Manager needs to derive the DN of the entry from the certificate or the certificate request so it can determine which entry to use. The mapper defines the relationship between the DN for the user entry and the subject name of the certificate or other input information so that the exact DN of the entry can be determined and found in the directory.

When it is configured, the Certificate Manager automatically creates a set of mappers defining the most common relationships. The default mappers are listed in Table 7.2, “Default Mappers”.

Table 7.2. Default Mappers
Mapper	Description
LdapUserCertMap	Locates the correct attribute of user entries in the directory in order to publish user certificates.
LdapCrlMap	Locates the correct attribute of the CA's entry in the directory in order to publish the CRL.
LdapCaCertMap	Locates the correct attribute of the CA's entry in the directory in order to publish the CA certificate.

To use the default mappers, configure each of the macros by specifying the DN pattern and whether to create the CA entry in the directory. To use other mappers, create and configure an instance of the mapper. For more information, see Section C.2, “Mapper Plug-in Modules ”.

Log into the Certificate Manager Console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Mappers.
The Mappers Management tab, which lists configured mappers, opens on the right.
To create a new mapper instance, click Add. The Select Mapper Plugin Implementation window opens, which lists registered mapper modules. Select a module, and edit it. For complete information about these modules, see Section C.2, “Mapper Plug-in Modules ”.
Edit the mapper instance, and click OK.
See Section C.2, “Mapper Plug-in Modules ” for detailed information about each mapper.

7.4.4. Completing Configuration: Rules and Enabling

After configuring the mappers for LDAP publishing, configure the rules for the published certificates and CRLs, as described in Section 7.5, “Creating Rules”.

Once the configuration is complete, enable publishing, as described in Section 7.6, “Enabling Publishing”.

7.5. Creating Rules

Rules determine what certificate object is published in what location. Rules work independently, not in tandem. A certificate or CRL that is being published is matched against every rule. Any rule which it matches is activated. In this way, the same certificate or CRL can be published to a file, to an Online Certificate Status Manager, and to an LDAP directory by matching a file-based rule, an OCSP rule, and matching a directory-based rule.

Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. The rules can be more detailed for different kinds of certificates or different kinds of CRLs.

The rule first determines if the object matches by matching the type and predicate set up in the rule with the object. Where matching objects are published is determined by the publisher and mapper associated with the rule.

Rules are created for each type of certificate the Certificate Manager issues.

Modify publishing rules by doing the following:

Log into the Certificate Manager Console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Rules.
The Rules Management tab, which lists configured rules, opens on the right.
To edit an existing rule, select that rule from the list, and click Edit. This opens the Rule Editor window.
To create a rule, click Add. This opens the Select Rule Plug-in Implementation window.
Select the Rule module. This is the only default module. If any custom modules have been been registered, they are also available.
Edit the rule.
- type. This is the type of certificate for which the rule applies. For a CA signing certificate, the value is cacert. For a cross-signed certificate, the value is xcert. For all other types of certificates, the value is certs. For CRLs, specify crl.
- predicate. This sets the predicate value for the type of certificate or CRL issuing point to which this rule applies. The predicate values for CRL issuing points, delta CRLs, and certificates are listed in Table 7.3, “Predicate Expressions”.
- enable.
- mapper. Mappers are not necessary when publishing to a file; they are only needed for LDAP publishing. If this rule is associated with a publisher that publishes to an LDAP directory, select an appropriate mapper here. Leave blank for all other forms of publishing.
- publisher. Sets the publisher to associate with the rule.

Table 7.3, “Predicate Expressions” lists the predicates that can be used to identify CRL issuing points and delta CRLs and certificate profiles.

Table 7.3. Predicate Expressions
Predicate Type	Predicate
CRL Issuing Point	`issuingPointId==`Issuing_Point_Instance_ID `&& isDeltaCRl==[true\|false]` To publish only the master CRL, set `isDeltaCRl==false`. To publish only the delta CRL, set `isDeltaCRl==true`. To publish both, set a rule for the master CRL and another rule for the delta CRL.
Certificate Profile	`profileId==`profile_name To publish certificates based on the profile used to issue them, set `profileId==` to a profile name, such as `caServerCert`.

7.6. Enabling Publishing

Publishing can be enabled for only files, only LDAP, or both. Publishing should be enabled after setting up publishers, rules, and mappers. Once enabled, the server attempts to begin publishing. If publishing was not configured correctly before being enabled, publishing may exhibit undesirable behavior or may fail.

Note

Configure CRLs. CRLs must be configured before they can be published. See Chapter 6, Revoking Certificates and Issuing CRLs.

Log into the Certificate Manager Console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing.
The right pane shows the details for publishing to an LDAP-compliant directory.
To enable publishing to a file only, select Enable Publishing.
To enable LDAP publishing, select both Enable Publishing and Enable Default LDAP Connection.
In the Destination section, set the information for the Directory Server instance.
- Host name. If the Directory Server is configured for TLS client authenticated communication, the name must match the cn component in the subject DN of the Directory Server's TLS server certificate.
  The hostname can be the fully-qualified domain name or an IPv4 or IPv6 address.
- Port number.
- Directory Manager DN. This is the distinguished name (DN) of the directory entry that has Directory Manager privileges. The Certificate Manager uses this DN to access the directory tree and to publish to the directory. The access control set up for this DN determines whether the Certificate Manager can perform publishing. It is possible to create another DN that has limited read-write permissions for only those attributes that the publishing system actually needs to write.
- Password. This is the password which the CA uses to bind to the LDAP directory to which the certificate or CRL is published. The Certificate Manager saves this password in its password.conf file. For example:
```
CA LDAP Publishing:password
```
- Client certificate. This sets the certificate the Certificate Manager uses for TLS client authentication to the publishing directory. By default, the Certificate Manager uses its TLS server certificate.
- LDAP version. Select LDAP version 3.
- Authentication. The way the Certificate Manager authenticates to the Directory Server. The choices are Basic authentication and TLS client authentication.
  If the Directory Server is configured for basic authentication or for TLS communication without client authentication, select Basic authentication and specify values for the Directory manager DN and password.
  If the Directory Server is configured for TLS communication with client authentication, select TLS client authentication and the Use TLS communication option, and identify the certificate that the Certificate Manager must use for TLS client authentication to the directory.

The server attempts to connect to the Directory Server. If the information is incorrect, the server displays an error message.

7.7. Setting up Resumable CRL Downloads

Certificate System provides option for interrupted CRL downloads to be resumed smoothly. This is done by publishing the CRLs as a plain file over HTTP. This method of downloading CRLs gives flexibility in retrieving CRLs and lowers overall network congestion.

7.7.1. Retrieving CRLs Using wget

Because CRLs can be published as a text file over HTTP, they can be manually retrieved from the CA using a tool such as wget. The wget command can be used to retrieve any published CRL. For example, to retrieve a full CRL which is newer than the previous full CRL:

[root@server ~]# wget --no-check-certificate -d https://server.example.com:8443/ca/ee/ca/crl/MasterCRL.bin

The relevant parameters for wget are summarized in Table 7.4, “wget Options to Use for Retrieving CRLs”.

Table 7.4. wget Options to Use for Retrieving CRLs
Argument	Description
no argument	Retrieves the full CRL.
-N	Retrieves the CRL that is newer than the local copy (delta CRL).
-c	Retrieves a partially-downloaded file.
--no-check-certificate	Skips TLS for the connection, so it is not necessary to configure TLS between the host and client.
-d	Prints debug information.

7.8. Publishing Cross-Pair Certificates

The cross-pair certificates can be published as a crossCertificatePair entry to an LDAP directory or to a file; this is enabled by default. If this has been disabled, it can be re-enabled through the Certificate Manager Console by doing the following:

Open the CA console.

pkiconsole https://server.example.com:8443/ca

In the Configuration tab, select the Certificate Manager link in the left pane, then the Publishing link.
Click the Rules link under Publishing. This opens the Rules Management pane on the right.
If the rule exists and has been disabled, select the enable checkbox. If the rule has been deleted, then click Add and create a new rule.
1. Select xcerts from the type drop-down menu.
2. Make sure the enable checkbox is selected.
3. Select LdapCaCertMap from the mapper drop-down menu.
4. Select LdapCrossCertPairPublisher from the publisher drop-down menu.

The mapper and publisher specified in the publishing rule are both listed under Mapper and Publisher under the Publishing link in the left navigation window of the CA Console. The mapper, LdapCaCertMap, by default designates that the crossCertificatePair be stored to the LdapCaSimpleMap LDAP entry. The publisher, LDAPCrossPairPublisher, by default sets the attribute to store the cross-pair certificate in the CA entry to crossCertificatePair;binary.

7.9. Testing Publishing to Files

To verify that the Certificate Manager is publishing certificates and CRLs correctly to file:

Open the CA's end-entities page, and request a certificate.
Approve the request through the agent services page, if required.
Retrieve the certificate from the end-entities page, and download the certificate into the browser.
Check whether the server generated the DER-encoded file containing the certificate.
Open the directory to which the binary blob of the certificate is supposed to be published. The certificate file should be named cert-serial_number.der.
Convert the DER-encoded certificate to its base 64-encoded format using the Binary to ASCII tool. For more information on this tool, refer to the BtoA(1) man page.
```
BtoA input_file output_file
```
input_file sets the path to the file that contains the DER-encoded certificate, and output_file sets the path to the file to write the base-64 encoded certificate.

Open the ASCII file; the base-64 encoded certificate is similar to the one shown:

Convert the base 64-encoded certificate to a readable form using the Pretty Print Certificate tool. For more information on this tool, refer to the PrettyPrintCert(1) man page.
```
PrettyPrintCert input_file [output_file]
```
input_file sets the path to the ASCII file that contains the base-64 encoded certificate, and output_file, optionally, sets the path to the file to write the certificate. If an output file is not set, the certificate information is written to the standard output.
Compare the output with the certificate issued; check the serial number in the certificate with the one used in the filename.
If everything matches, the Certificate Manager is configured correctly to publish certificates to file.
Revoke the certificate.
Check whether the server generated the DER-encoded file containing the CRL.
Open the directory to which the server is to publish the CRL as a binary blob. The CRL file should have a name in the form crl-this_update.der. this_update specifies the value derived from the time-dependent This Update variable of the CRL.
Convert the DER-encoded CRL to its base 64-encoded format using the Binary to ASCII tool.
```
BtoA input_file output_file
```
Convert the base 64-encoded CRL to readable form using the Pretty Print CRL tool.
```
PrettyPrintCrl input_file [output_file]
```
Compare the output.

7.10. Viewing Certificates and CRLs Published to File

Certificates and CRLs can be published to two types of files: base-64 encoded or DER-encoded. The content of these files can be viewed by converting the files to pretty-print format using the dumpasn1 tool or the PrettyPrintCert or PrettyPrintCrl tool.

To view the content in a base-64 encoded file:

Convert the base-64 file to binary. For example:
```
AtoB /tmp/example.b64 /tmp/example.bin
```
Use the PrettyPrintCert or PrettyPrintCrl tool to convert the binary file to pretty-print format. For example:
```
PrettyPrintCert example.bin example.cert
```

To view the content of a DER-encoded file, simply run the dumpasn1, PrettyPrintCert, or PrettyPrintCrl tool with the DER-encoded file. For example:

PrettyPrintCrl example.der example.crl

7.11. Updating Certificates and CRLs in a Directory

The Certificate Manager and the publishing directory can become out of sync if certificates are issued or revoked while the Directory Server is down. Certificates that were issued or revoked need to be published or unpublished manually when the Directory Server comes back up.

To find certificates that are out of sync with the directory ‐ valid certificates that are not in the directory and revoked or expired certificates that are still in the directory ‐ the Certificate Manager keeps a record of whether a certificate in its internal database has been published to the directory. If the Certificate Manager and the publishing directory become out of sync, use the Update Directory option in the Certificate Manager agent services page to synchronize the publishing directory with the internal database.

The following choices are available for synchronizing the directory with the internal database:

Search the internal database for certificates that are out of sync and publish or unpublish.
Publish certificates that were issued while the Directory Server was down. Similarly, unpublish certificates that were revoked or that expired while Directory Server was down.
Publish or unpublish a range of certificates based on serial numbers, from serial number xx to serial number yy.

A Certificate Manager's publishing directory can be manually updated by a Certificate Manager agent only.

7.11.1. Manually Updating Certificates in the Directory

The Update Directory Server form in the Certificate Manager agent services page can be used to update the directory manually with certificate-related information. This form initiates a combination of the following operations:

Update the directory with certificates.
Remove expired certificates from the directory.
Removing expired certificates from the publishing directory can be automated by scheduling an automated job.
Remove revoked certificates from the directory.

Manually update the directory with changes by doing the following:

Open the Certificate Manager agent services page.
Select the Update Directory Server link.
Select the appropriate options, and click Update Directory.
The Certificate Manager starts updating the directory with the certificate information in its internal database. If the changes are substantial, updating the directory can take considerable time. During this period, any changes made through the Certificate Manager, including any certificates issued or any certificates revoked, may not be included in the update. If any certificates are issued or revoked while the directory is updated, update the directory again to reflect those changes.

When the directory update is complete, the Certificate Manager displays a status report. If the process is interrupted, the server logs an error message.

If the Certificate Manager is installed as a root CA, the CA signing certificate may get published using the publishing rule set up for user certificates when using the agent interface to update the directory with valid certificates. This may return an object class violation error or other errors in the mapper. Selecting the appropriate serial number range to exclude the CA signing certificate can avoid this problem. The CA signing certificate is the first certificate a root CA issues.

Modify the default publishing rule for user certificates by changing the value of the predicate parameter to profileId!=caCACert.
Use the LdapCaCertPublisher publisher plug-in module to add another rule, with the predicate parameter set to profileId=caCACert, for publishing subordinate CA certificates.

7.11.2. Manually Updating the CRL in the Directory

The Certificate Revocation List form in the Certificate Manager agent services page manually updates the directory with CRL-related information.

Manually update the CRL information by doing the following:

Open the Certificate Manager agent services page.
Select Update Revocation List.
Click Update.

The Certificate Manager starts updating the directory with the CRL in its internal database. If the CRL is large, updating the directory takes considerable time. During this period, any changes made to the CRL may not be included in the update.

When the directory is updated, the Certificate Manager displays a status report. If the process is interrupted, the server logs an error message.

Chapter 8. Authentication for Enrolling Certificates

8.1. Automatic Approval by an Authentication Plug-in

The auth.instance_id parameter in a profile specifies the authentication mechanism. A certificate request can either be automatically approved through an authentication plug-in, or be manually approved by a CA agent.

Note

For instructions on how to edit certificate enrollment profiles, see Section 3.2, “Setting up Certificate Profiles”.

8.1.1. Setting up Auto-approval of Enrollment Requests

Configuring that enrollment requests are automatically approved depends on the type of requests:

For agent-pre-approved CMC requests, set in the CA profile:
```
auth.instance_id=CMCAuth
authz.acl=group="Certificate Manager Agents"
```
The authz.acl parameter defines the group that is allowed to approve requests.

For user-initiated requests:

When using CMC Shared Token, set in the CA profile:

auth.instance_id=CMCUserSignedAuth

Required default and constraint:

policyset.cmcUserCertSet.1.constraint.class_id=cmcSharedTokenSubjectNameConstraintImpl
policyset.cmcUserCertSet.1.constraint.name=CMC Shared Token Subject Name Constraint
policyset.cmcUserCertSet.1.default.class_id=authTokenSubjectNameDefaultImpl
policyset.cmcUserCertSet.1.default.name=Subject Name Default

When using User-signed requests, set in the CA profile:

auth.instance_id=CMCUserSignedAuth

Required default and constraint:

policyset.cmcUserCertSet.1.default.params.name=
policyset.cmcUserCertSet.9.constraint.class_id=uniqueKeyConstraintImpl
policyset.cmcUserCertSet.9.constraint.name=Unique Key Constraint
policyset.cmcUserCertSet.9.constraint.params.allowSameKeyRenewal=true
policyset.cmcUserCertSet.9.default.class_id=noDefaultImpl
policyset.cmcUserCertSet.9.default.name=No Default

For details about editing a profile, see Section 3.2, “Setting up Certificate Profiles”.

8.1.2. CMC Authentication Plug-ins

Certificate System provides the following authentication plug-ins:

CMCAuth

Use this plug-in when a CA agent signs CMC requests.

To use the CMCAuth plug-in, set the following in the enrollment profile:

auth.instance_id=CMCAuth

By default, the following enrollment profiles use the CMCAuth plug-in:

For system certificates:
- caCMCauditSigningCert
- caCMCcaCert
- caCMCECserverCert
- caCMCECsubsystemCert
- caCMCECUserCert
- caCMCkraStorageCert
- caCMCkraTransportCert
- caCMCocspCert
- caCMCserverCert
- caCMCsubsystemCert
For user certificates:
- caCMCUserCert
- caECFullCMCUserCert
- caFullCMCUserCert

CMCUserSignedAuth

Use this plug-in when users submit signed or SharedSecret-based CMC requests.

To use the CMCUserSignedAuth plug-in, set the following in the enrollment profile:

auth.instance_id=CMCUserSignedAuth

A user-signed CMC request must be signed by the user's certificate which contains the same subjectDN attribute as the requested certificate. You can only use a user-signed CMC request if the user already obtained a signing certificate which can be used to prove the user's identity for other certificates.

A SharedSecret-based CMC request means that the request was signed by the private key of the request itself. In this case, the CMC request must use the Shared Secret mechanism for authentication. A SharedSecret-based CMC request is typically used to obtain the user's first signing certificate, which is later used to obtain other certificates. For further details, see Section 8.1.3, “CMC SharedSecret Authentication”.

By default, the following enrollment profiles use the CMCUserSignedAuth plug-in:

caFullCMCUserSignedCert
caECFullCMCUserSignedCert
caFullCMCSharedTokenCert
caECFullCMCSharedTokenCert

8.1.3. CMC SharedSecret Authentication

Use the Shared Secret feature to enable users to send unsigned CMC requests to the server. For example, this is necessary if a user wants to obtain the first signing certificate. This signing certificate can later be used to sign other certificates of this user.

8.1.3.1. Creating a Shared Secret Token

The The Shared Secret Workflow section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition) describes the workflow when using a Shared Secret Token. Depending on the situation, either an end entity user or an administrator creates the Shared Secret Token.

Note

To use the shared secret token, Certificate System must use an RSA issuance protection certificate. For details, see Enabling the CMC Shared Secret Feature section located in RHCS Planning, Installation, and Deployment Guide.

To create a Shared Secret Token, enter:

# CMCSharedToken -d /home/user_name/.dogtag/ -p NSS_password \
     -s "CMC_enrollment_password" -o /home/user_name/CMC_shared_token.b64 \
     -n "issuance_protection_certificate_nickname"

If you use an HSM, additionally pass the -h token_name option to the command to set the HSM security token name.

For further details about the CMCSharedToken utility, see the CMCSharedToken(8) man page.

Note

The generated token is encrypted and only the user who generated knows the password. If a CA administrator generates the token for a user, the administrator must provide the password to the user using a secure way.

After creating the Shared Token, an administrator must add the token to a user or certificate record. For details, see Section 8.1.3.2, “Setting a CMC Shared Secret”.

8.1.3.2. Setting a CMC Shared Secret

Depending on the planned action, an administrator must store a Shared Secret Token after generating it in the LDAP entry of the user or certificate.

For details about the workflow and when to use a Shared Secret, see the The Shared Secret Workflow section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).

8.1.3.2.1. Adding a CMC Shared Secret to a User Entry for Certificate Enrollment

To use the Shared Secret Token for certificate enrollment, store it as an administrator in the LDAP entry of the user:

# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user_name,ou=People,dc=example,dc=com
changetype: modify
replace: shrTok
shrTok: base64-encoded_token

8.1.3.2.2. Adding a CMC Shared Secret to a Certificate for Certificate Revocations

To use the Shared Secret Token for certificate revocations, store it as an administrator in the LDAP entry of the certificate to be revoked:

 # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=certificate_id,ou=certificateRepository,ou=ca,o=pki-tomcat-CA
changetype: modify
replace: shrTok
shrTok: base64-encoded_token

8.2. Manual Approval by a CA Agent

If manual approval is configured in a CA profile, users can create CMC requests, but requests must be manually approved by a CA agent.

To configure manual agent approval in a CA profile:

Set the auth.instance_id to an empty value:
```
auth.instance_id=
```
Do not set the authz.acl parameter.

For details about editing a profile, see Section 3.2, “Setting up Certificate Profiles”.

8.3. Manually Reviewing the Certificate Status Using the Command Line

To review certificate requests, ensure that you are authenticated as an agent with proper permissions to approve certificate requests. For details about configuring the pki command-line interface, see Section 2.5.1.1, “pki CLI Initialization”.

To review the requests:

Display the list of pending certificate requests:
```
$ pki agent_authentication_parameters ca-cert-request-find --status pending
```
This command lists all pending certificate requests.

Download a particular certificate request:

$ pki agent_authentication_parameters ca-cert-request-review id --file request.xml

Open the request.xml file in an editor or a separate terminal, and review the contents of the request to ensure it is legitimate. Then answer the prompt: if the request is valid, answer "approve and press Enter. If the request is invalid, answer reject and press Enter. Organizations can subscribe semantic differences to reject and cancel; both result in no certificate being issued.

8.4. Manually Reviewing the Certificate Status Using the Web Interface

Open the following URL in a web browser:

https://server_host_name:8443/ca/agent/ca

Authenticate as an agent. For information about authenticating as a user and configuring your browser, see Section 2.4.1, “Browser Initialization”.
On the sidebar on the left, click the List requests link.
Filter the requests be selecting Show all requests for Request type and Show pending requests for Request status.
Click Find in the lower right corner.
The results page lists all pending requests waiting for review. Click on the request number to review a request.
Review the request information and ensure that it is a legitimate request. If necessary, modify the policy information to correct any mistakes or make any desired changes to the certificate, such as changing the not valid after field. Optionally, leave an additional note.
The drop down menu includes several review status updates. Select Approve request to approve the request or Reject request to deny it, and click Submit. Organizations can subscribe semantic differences to Reject request and Cancel Request; both result in no certificate being issued.

Chapter 9. Authorization for Enrolling Certificates (Access Evaluators)

This chapter describes the authorization mechanism using access evaluators.

Note

For instructions on how to edit certificate enrollment profiles, see Section 3.2, “Setting up Certificate Profiles”.

9.1. Authorization Mechanism

In addition to the authentication mechanism, each enrollment profile can be configured to have its own authorization mechanism. The authorization mechanism is executed only after a successful authentication.

The authorization mechanism is provided by the Access Evaluator plug-in framework. Access evaluators are pluggable classes that are used for evaluating access control instructions (ACI) entries. The mechanism provides an evaluate method that takes a predefined list of arguments (that is, type, op, value), evaluates an expression such as group='Certificate Manager Agents' and returns a boolean depending on the result of evaluation.

9.2. Default Evaluators

Red Hat Certificate System provides four default evaluators.

accessEvaluator.impl.group.class=com.netscape.cms.evaluators.GroupAccessEvaluator
accessEvaluator.impl.ipaddress.class=com.netscape.cms.evaluators.IPAddressAccessEvaluator
accessEvaluator.impl.user.class=com.netscape.cms.evaluators.UserAccessEvaluator
accessEvaluator.impl.user_origreq.class=com.netscape.cms.evaluators.UserOrigReqAccessEvaluator

The group access evaluator evaluates the group membership properties of a user. For example, in the following enrollment profile entry, only the CA agents are allowed to go through enrollment with that profile:

authz.acl=group="Certificate Manager Agents"

The ipaddress access evaluator evaluates the IP address of the requesting subject. For example, in the following enrollment profile entry, only the host bearing the specified IP address can go through enrollment with that profile:

authz.acl=ipaddress="a.b.c.d.e.f"

The user access evaluator evaluates the user ID for exact match. For example, in the following enrollment profile entry, only the user matching the listed user is allowed to go through enrollment with that profile:

authz.acl=user="bob"

The user_origreq access evaluator evaluates the authenticated user against a previous matching request for equality. This special evaluator is designed specifically for renewal purpose to make sure the user requesting the renewal is the same user that owns the original request. For example, in the following renewal enrollment profile entry, the UID of the authenticated user must match the UID of the user requesting the renewal:

authz.acl=user_origreq="auth_token.uid"

New evaluators can be written in the current framework and can be registered through the CS console. The default evaluators can be used as templates to expand and customize into more targeted plug-ins.

Part IV. Managing the Subsystem Instances

Chapter 10. Self Tests

10.1. Running Self-Tests

The Certificate System has the added functionality to allow self-tests of the server. The self-tests are run at start up and can also be run on demand. The startup self-tests run when the server starts and keep the server from starting if a critical self-test fails. The on-demand self-tests are run by clicking the self-tests button in the subsystem console.

10.1.1. Running Self-Tests

The on-demand self-test for the CA, OCSP, KRA, or TKS subsystems are run from the console. The on-demand self-tests for the TPS system are run from the web services page.

10.1.1.1. Running Self-Tests from the Console

Log into the Console.

pkiconsole https://server.example.com:admin_port/subsystem_type

Select the subsystem name at the top of the left pane.
Select the Self Tests tab.
Click Run.
The self-tests that are configured for the subsystem will run. If any critical self-tests fail, the server will stop.
The On-Demand Self Tests Results window appears, showing the logged events for this run of the self-tests.

10.1.1.2. Running TPS Self-Tests

To run TPS self-tests from the command-line interface (CLI):

pki tps-selftest-find
pki tps-selftest-run
pki tps-selftest-show

10.2. Debugging Self-Tests Failures

In the event of self-test failure, the Certificate System instance will stop completely and will not respond to any HTTP or HTTPS requests.

To diagnose a manually run self-test failure, refer to the various logs described in Section 10.2.1, “Self-Test Logging”. Often other logs are useful as well, including debug logs. For more information on subsystem logs, refer to Chapter 13, Configuring Subsystem Logs. For more information on debug logs, refer to the Logs section under the Certificate System Architecture Overview in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).

Common causes of self-test failures are services (such as LDAP) are down or unreachable, certificates are expired, or the system configuration is wrong. A precise cause of self-test failure is given in the logs.

After the cause of the self-test failure is identified and fixed, please restart the Certificate System server to resume normal operations:

# systemctl restart pki-tomcatd-nuxwdog@instance_name.service

10.2.1. Self-Test Logging

A separate log, selftests.log, is added to the log directory that contains reports for both the start up self-tests and the on-demand self-tests.

Chapter 11. 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 2.3.8.1. NSS Soft Token (internal token) in Red Hat Certificate System's Planning, Installation, and Deployment Guide.

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

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

11.1.2. PKICertImport Basic Usage

PKICertImport [options]

Each PKICertImport invocation accepts 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 11.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.

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

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

11.2. Importing a Root Certificate

First, change directories into the NSS DB:

cd /path/to/nssdb

Ensure that your web service is taken offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the NSS DB by other processes (such as a browser). Doing so may corrupt the NSS DB or result in improper usage of these certificates.

When needing to import a new root certificate, ensure you acquire this certificate in a secure manner as it will be able to sign a number of certificates. We assume you already have it in a file named ca_root.crt. Please substitute the correct name and path to this file as appropriate for your scenario.

For more information about the certutil and PKICertImport options used below, see Section 11.1, “About certutil and PKICertImport”.

To import the root certificate:

Execute PKICertImport -d . -n "CA Root" -t "CT,C,C" -a -i ca_root.crt -u L command.
This command validates and imports the root certificate into your NSS DB. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. The certificate usually fails to validate because it is expired or because it is not a CA certificate. Therefore, make sure your certificate file is correct and up-to-date. Contact the issuer and ensure that all intermediate and root certificates are present on your system.

11.3. Importing an Intermediate Certificate Chain

Before beginning, please change directories into the NSS DB:

cd /path/to/nssdb

Ensure that your web service is offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the NSS DB by other processes (such as a browser). Doing so may corrupt the NSS DB or result in improper usage of these certificates.

If you have not imported and trusted the root certificate, see Section 11.2, “Importing a Root Certificate”.

When given a series of intermediate certificates between your root and end server or client certificates, we need to import and validate the signed certificate chain in order from closest to furthest from the root CA certificate. We assume the Intermediate CAs are in files named ca_sub_<num>.crt (for example ca_sub_1.crt, ca_sub_2.crt, and so on). Substitute names and paths for your certificates as appropriate to your deployment.

Note

In the unlikely scenario that you are instead given a single file named fullchain.crt, fullchain.pem, or similar and it contains multiple certificates, split it into the above format by copying each block (between and including the ----BEGIN CERTIFICATE----- and an -----END CERTIFICATE----- markers) to its own file. The first ones should be named ca_sub_<num>.crt and the last will be your server cert named service.crt. Server certificates are discussed in later sections.

First, we will import and validate any intermediate CAs in order of closest to furthest from the root CA certificate. If you don't have any, you can skip to the next section.

For more information about the certutil and PKICertImport options used below, see Section 11.1, “About certutil and PKICertImport”.

For every intermediate certificate in the chain:

Execute PKICertImport -d . -n "CA Sub $num" -t "CT,C,C" -a -i ca_sub_$num.crt -u L
This command validates and imports the Intermediate CA certificate into your NSS DB. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

11.4. Importing a certificate into an NSS Database

Ensure that your web service is taken offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the NSS database by other processes (such as a browser). Doing so may corrupt the NSS database or result in improper usage of these certificates.

Note that which set of instructions you follow will depend on the usage for the certificate in question.

For any subsystem's auditSigningCert, please follow the steps below for validating an object Signing certificate.
For the CA subsystem's caSigningCert, please follow the steps above for importing and validating an intermediate certificate chain, but do so only with the caSigningCert.
For the CA subsystem's ocspSigningCert, please follow the steps below for validating an OCSP certificate.
For user's client or S/MIME certificate, follow the Client Certificate steps.

For more information about the certutil and PKICertImport options used below, see Section 11.1, “About certutil and PKICertImport”.

Importing a Client Certificate Into the NSS Database

To import a client certificate into the NSS database:

Change into the NSS database directory. For example:
```
# cd /path/to/nssdb/
```
Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 11.2, “Importing a Root Certificate”.
Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 11.3, “Importing an Intermediate Certificate Chain”.
Validate and import the client certificate:
```
# PKICertImport -d . -n "client name" -t ",," -a -i client.crt -u C
```
The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

Importing an Object Signing Certificate

To import an object signing certificate:

Change into the NSS database directory. For example:
```
# cd /path/to/nssdb/
```
Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 11.2, “Importing a Root Certificate”.
Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 11.3, “Importing an Intermediate Certificate Chain”.
Validate and import the object signing certificate:
```
# PKICertImport -d . -n "certificate name" -t ",,P" -a -i objectsigning.crt -u J
```
The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

Importing an OCSP Responder

To import an OCSP responder:

Change into the NSS database directory. For example:
```
# cd /path/to/nssdb/
```
Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 11.2, “Importing a Root Certificate”.
Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 11.3, “Importing an Intermediate Certificate Chain”.
Validate and import the OCSP responder certificate:
```
# PKICertImport -d . -n "certificate name" -t ",," -a -i ocsp.crt -u O
```
The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute echo $? immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.

Chapter 12. Managing Certificate System Users and Groups

This chapter explains how to set up authorization for access to the administrative, agent services, and end-entities pages.

12.1. About Authorization

Note

The ACLs associated with each group discussed in this section must not be modified.

Authorization is the process of allowing access to certain tasks associated with the Certificate System. Access can be limited to allow certain tasks to certain areas of the subsystem for certain users or groups and different tasks to different users and groups.

Users are specific to the subsystem in which they are created. Each subsystem has its own set of users independent of any other subsystem installed. The users are placed in groups, which can be predefined or user-created. Privileges are assigned to a group through access control lists (ACLs). There are ACLs associated with areas in the administrative console, agent services interface, and end-entities page that perform an authorization check before allowing an operation to proceed. Access control instructions (ACIs) in each of the ACLs are created that specifically allow or deny possible operations for that ACL to specified users, groups, or IP addresses.

The ACLs contain a default set of ACIs for the default groups that are created.

Authorization goes through the following process:

The users authenticate to the interface using a certificate.
The server authenticates the user by checking the certificate against one stored in the database. The server also checks that the certificate is valid and finds the group membership of the user by associating the DN of the certificate with a user and checking the user entry.
When the user tries to perform an operation, the authorization mechanism compares the user ID of the user, the group in which the user belongs, or the IP address of the user to the ACLs set for that user, group, or IP address. If an ACL exists that allows that operation, then the operation proceeds.

12.2. Default Groups

A user's privileges are determined by the group (role) membership of the user. There are three groups (roles) that a user can be assigned to:

Administrators. This group is given full access to all of the tasks available in the administrative interface.
Agents. This group is given full access to all of the tasks available in the agent services interface.
Auditors. This group is given access to view the signed audit logs. This group does not have any other privileges.

There is a fourth role that is exclusively created for communication between subsystems. Administrators should never assign a real user to such a role:

Enterprise administrators. Each subsystem instance is automatically assigned a subsystem-specific role as an enterprise administrator when it is joined to a security domain during configuration. These roles automatically provide trusted relationships among subsystems in the security domain, so that each subsystem can efficiently carry out interactions with other subsystems.

12.2.1. Administrators

Administrators have permissions to perform all administrative tasks. A user is designated or identified as being an administrator by being added to the Administrators group for the group. Every member of that group has administrative privileges for that instance of Certificate System.

At least one administrator must be defined for each Certificate System instance, but there is no limit to the number of administrators an instance can have. The first administrator entry is created when the instance is configured.

Administrators are authenticated with a simple bind using their Certificate System user ID and password.

Table 12.1. Security Domain User Roles
Role	Description
Security Domain Administrators	Add and modify users in the security domain's user and group database. Manage the shared trust policies. Manage the access controls on the domain services. By default, the CA administrator of the CA hosting the domain is assigned as the security domain administrator.
Enterprise CA Administrators	Automatically approve any sub-CA, server, and subsystem certificate from any CA in the domain. Register and unregister CA subsystem information in the security domain.
Enterprise KRA Administrators	Automatically approve any transport, storage, server, and subsystem certificate from any CA in the domain. Register and unregister KRA subsystem information in the security domain. Push KRA connector information to any CA.
Enterprise OCSP Administrators	Automatically approve any OCSP, server, and subsystem certificate from any CA in the domain. Register and unregister OCSP subsystem information in the security domain. Push CRL publishing information to any CA.
Enterprise TKS Administrators	Automatically approve any server and subsystem certificate from any CA in the domain. Register and unregister TKS subsystem information in the security domain.
Enterprise TPS Administrators	Automatically approve any server and subsystem certificate from any CA in the domain. Register and unregister TPS subsystem information in the security domain.

As necessary, the security domain administrator can manage access controls on the security domain and on the individual subsystems. For example, the security domain administrator can restrict access so that only finance department KRA administrators can set up finance department KRAs.

Enterprise subsystem administrators are given enough privileges to perform operations on the subsystems in the domain. For example, an enterprise CA administrator has the privileges to have sub-CA certificates approved automatically during configuration. Alternatively, a security domain administrator can restrict this right if necessary.

12.2.2. Auditors

An auditor can view the signed audit logs and is created to audit the operation of the system. The auditor cannot administer the server in any way.

An auditor is created by adding a user to the Auditors group and storing the auditor's certificate in the user entry. The auditor's certificate is used to encrypt the private key of the key pair used to sign the audit log.

The Auditors group is set when the subsystem is configured. No auditors are assigned to this group during configuration.

12.2.3. Agents

Agents are users who have been assigned end-entity certificate and key-management privileges. Agents can access the agent services interface.

Agents are created by assigning a user to the appropriate subsystem agent group and identifying certificates that the agents must use for TLS client authentication to the subsystem for it to service requests from the agents. Each subsystem has its own agent group:

The Certificate Manager Agents group.
The Key Recovery Authority Agents group.
The Online Certificate Status Manager Agents group.
The Token Key Service Agents group.
The Token Processing System Agents group.

Each Certificate System subsystem has its own agents with roles defined by the subsystem. Each subsystem must have at least one agent, but there is no limit to the number of agents a subsystem can have.

Certificate System identifies and authenticates a user with agent privileges by checking the user's TLS client certificate in its internal database.

12.2.4. Enterprise Groups

Note

No real user should ever be asigned to this group.

During subsystem configuration, every subsystem instance is joined to a security domain. Each subsystem instance is automatically assigned a subsystem-specific role as an enterprise administrator. These roles automatically provide trusted relationships among subsystems in the security domain, so that each subsystem can efficiently carry out interactions with other subsystems. For example, this allows OCSPs to push CRL publishing publishing information to all CAs in the domain, KRAs to push KRA connector information, and CAs to approve certificates generated within the CA automatically.

Enterprise subsystem administrators are given enough privileges to perform operations on the subsystems in the domain. Each subsystem has its own security domain role:

Enterprise CA Administrators
Enterprise KRA Administrators
Enterprise OCSP Administrators
Enterprise TKS Administrators
Enterprise TPS Administrators

Additionally, there is a Security Domain Administrators group for the CA instance which manages the security domain, access control, users, and trust relationships within the domain.

Each subsystem administrator authenticates to the other subsystems using TLS client authentication with the subsystem certificate issued during configuration by the security domain CA.

12.3. Managing Users and Groups for a CA, OCSP, KRA, or TKS

Many of the operations that users can perform are dictated by the groups that they belong to; for instance, agents for the CA manage certificates and profiles, while administrators manage CA server configuration.

Four subsystems — the CA, OCSP, KRA, and TKS — use the Java administrative console to manage groups and users. The TPS has web-based admin services, and users and groups are configured through its web service page.

12.3.1. Managing Groups

12.3.1.1. Creating a New Group

Log into the administrative console.

pkiconsole https://server.example.com:8443/subsystem_type

Select Users and Groups from the navigation menu on the left.
Select the Groups tab.
Click Edit, and fill in the group information.
It is only possible to add users who already exist in the internal database.
Edit the ACLs to grant the group privileges. See Section 12.4.3, “Editing ACLs” for more information. If no ACIs are added to the ACLs for the group, the group will have no access permissions to any part of Certificate System.

12.3.1.2. Changing Members in a Group

Members can be added or deleted from all groups. The group for administrators must have at least one user entry.

Log into the administrative console.
Select Users and Groups from the navigation tree on the left.
Click the Groups tab.
Select the group from the list of names, and click Edit.
Make the appropriate changes.
- To change the group description, type a new description in the Group description field.
- To remove a user from the group, select the user, and click Delete.
- To add users, click Add User. Select the users to add from the dialog box, and click OK.

12.3.2. Managing Users (Administrators, Agents, and Auditors)

The users for each subsystem are maintained separately. Just because a person is an administrator in one subsystem does not mean that person has any rights (or even a user entry) for another subsystem. Users can be configured and, with their user certificates, trusted as agents, administrators, or auditors for a subsystem.

12.3.2.1. Creating Users

After you installed Certificate System, only the user created during the setup exists. This section describes how to create additional users.

Note

For security reasons and audit trails, create individual accounts for Certificate System users and administrators.

12.3.2.1.1. Creating Users Using the Command Line

To create a user using the command line:

Add a user account. For example, to add the example user to the CA:

# pki -c password -n caadmin \
     ca-user-add example --fullName "Example User"
---------------------
Added user "example"
---------------------
  User ID: example
  Full name: Example User

This command uses the caadmin user to add a new account.

Optionally, add a user to a group. For example, to add the example user to the Certificate Manager Agents group:
```
# pki -p password -n "caadmin" \
     user-add-membership example Certificate Manager Agents
```
Create a certificate request:
- If a Key Recovery Authority (KRA) exists in your Certificate System environment:
```
# CRMFPopClient -d ~/.dogtag/pki-instance_name/ -p password \
     -n "user_name" -q POP_SUCCESS -b kra.transport -w "AES/CBC/PKCS5Padding" \
     -v -o ~/user_name.req
```
  This command stores the Certificate Signing Request (CSR) in the CRMF format in the ~/user_name.req file.
- If no Key Recovery Authority (KRA) exists in your Certificate System environment:
```
# PKCS10Client -d ~/.dogtag/pki-instance_name/ -p password \
     -n "user_name" -o ~/user_name.req
```
  This command stores the CSR in pkcs10 format in the ~/user_name.req file.

Create an enrollment request:

Create the ~/cmc.role_crmf.cfg file with the following content:

#numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

#input: full path for the PKCS10 request or CRMF request,
#the content must be in Base-64 encoded format
#Multiple files are supported. They must be separated by space.
input=~/user_name.req

#output: full path for the CMC request in binary format
output=~/cmc.role_crmf.req

#tokenname: name of token where agent signing cert can be found (default is internal)
tokenname=internal

#nickname: nickname for agent certificate which will be used
#to sign the CMC full request.
nickname=PKI Administrator for Example.com

#dbdir: directory for cert8.db, key3.db and secmod.db
dbdir=~/.dogtag/pki-instance_name/

#password: password for cert8.db which stores the agent
#certificate
password=password

#format: request format, either pkcs10 or crmf
format=crmf

Set the parameters based on your environment and the CSR format used in the previous step.

Pass the previously created configuration file to the CMCRequest utility to create the CMC request:
```
# CMCRequest ~/cmc.role_crmf.cfg
```

Submit a Certificate Management over CMS (CMC) request:

Create the ~/HttpClient_role_crmf.cfg file with the following content:

# #host: host name for the http server
host=server.example.com

#port: port number
port=8443

#secure: true for secure connection, false for nonsecure connection
secure=true

#input: full path for the enrollment request, the content must be in binary format
input=~/cmc.role_crmf.req

#output: full path for the response in binary format
output=~/cmc.role_crmf.resp

#tokenname: name of token where TLS client authentication cert can be found (default is internal)
#This parameter will be ignored if secure=false
tokenname=internal

#dbdir: directory for cert8.db, key3.db and secmod.db
#This parameter will be ignored if secure=false
dbdir=~/.dogtag/pki-instance_name/

#clientmode: true for client authentication, false for no client authentication
#This parameter will be ignored if secure=false
clientmode=true

#password: password for cert8.db
#This parameter will be ignored if secure=false and clientauth=false
password=password

#nickname: nickname for client certificate
#This parameter will be ignored if clientmode=false
nickname=PKI Administrator for Example.com

#servlet: servlet name
servlet=/ca/ee/ca/profileSubmitCMCFull

Set the parameters based on your environment.

Submit the request to the CA:

# HttpClient ~/HttpClient_role_crmf.cfg
Total number of bytes read = 3776
after SSLSocket created, thread token is Internal Key Storage Token
client cert is not null
handshake happened
writing to socket
Total number of bytes read = 2523
MIIJ1wYJKoZIhvcNAQcCoIIJyDCCCcQCAQMxDzANBglghkgBZQMEAgEFADAxBggr
...
The response in data format is stored in ~/cmc.role_crmf.resp

Verify the result:

# CMCResponse ~/cmc.role_crmf.resp
Certificates:
    Certificate:
        Data:
            Version:  v3
            Serial Number: 0xE
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=pki-instance_name Security Domain
            Validity:
                Not Before: Friday, July 21, 2017 12:06:50 PM PDT America/Los_Angeles
                Not  After: Wednesday, January 17, 2018 12:06:50 PM PST America/Los_Angeles
            Subject: CN=user_name
...
Number of controls is 1
Control #0: CMCStatusInfoV2
   OID: {1 3 6 1 5 5 7 7 25}
   BodyList: 1
   Status: SUCCESS

Optionally, to import the certificate as the user to its own ~/.dogtag/pki-instance_name/ database:

# certutil -d ~/.dogtag/pki-instance_name/ -A -t "u,u,u" -n "user_name certificate" -i ~/cmc.role_crmf.resp

Add the certificate to the user record:

List certificates issued for the user to discover the certificate's serial number. For example, to list certificates that contain the example user name in the certificate's subject:

pki -c password -n caadmin ca-user-cert-find example
-----------------
1 entries matched
-----------------
  Cert ID: 2;6;CN=CA Signing Certificate,O=EXAMPLE;CN=PKI Administrator,E=example@example.com,O=EXAMPLE
  Version: 2
  Serial Number: 0x6
  Issuer: CN=CA Signing Certificate,O=EXAMPLE
  Subject: CN=PKI Administrator,E=example@example.com,O=EXAMPLE
----------------------------
Number of entries returned 1

The serial number of the certificate is required in the next step.

Add the certificate using its serial number from the certificate repository to the user account in the Certificate System database. For example, for a CA user:
```
pki -c password -n caadmin ca-user-cert-add example --serial 0x6
```

12.3.2.1.2. Creating Users Using the Console

To create a user using the PKI Console:

Log into the administrative console.

pkiconsole https://server.example.com:8443/subsystem_type

In the Configuration tab, select Users and Groups. Click Add.
Fill in the information in the Edit User Information dialog.
Most of the information is standard user information, such as the user's name, email address, and password. This window also contains a field called User State, which can contain any string, which is used to add additional information about the user; most basically, this field can show whether this is an active user.
Select the group to which the user will belong. The user's group membership determines what privileges the user has. Assign agents, administrators, and auditors to the appropriate subsystem group.
Store the user's certificate.
1. Request a user certificate through the CA end-entities service page.
2. If auto-enrollment is not configured for the user profile, then approve the certificate request.
3. Retrieve the certificate using the URL provided in the notification email, and copy the base-64 encoded certificate to a local file or to the clipboard.
4. Select the new user entry, and click Certificates.
5. Click Import, and paste in the base-64 encoded certificate.

12.3.2.2. Changing a Certificate System User's Certificate

Log into the administrative console.
Select Users and Groups.
Select the user to edit from the list of user IDs, and click Certificates.
Click Import to add the new certificate.
In the Import Certificate window, paste the new certificate in the text area. Include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- marker lines.

12.3.2.3. Renewing Administrator, Agent, and Auditor User Certificates

There are two methods of renewing a certificate. Regenerating the certificate takes its original key and its original profile and request, and recreates an identical key with a new validity period and expiration date. Re-keying a certificate resubmits the initial certificate request to the original profile, but generates a new key pair. Administrator certificates can be renewed by being re-keyed.

Each subsystem has a bootstrap administrator user that was created at the time the subsystem was created. A new certificate can be requested for this user before their original one expires, using one of the default renewal profiles.

Certificates for administrative users can be renewed directly in the end user enrollment forms, using the serial number of the original certificate.

Renew the admin user certificate. For details, seeSection 5.4, “Renewing Certificates”.
Add the renewed user certificate to the user entry in the internal LDAP database.
1. Open the console for the subsystem.
```
pkiconsole https://server.example.com:admin_port/subsystem_type
```
2. Configuration | Users and Groups | Users | admin | Certificates | Import
3. In the Configuration tab, select Users and Groups.
4. In the Users tab, double-click the user entry with the renewed certificate, and click Certificates.
5. Click Import, and paste in the base-64 encoded certificate.
This can also be done by using ldapmodify to add the renewed certification directly to the user entry in the internal LDAP database, by replacing the userCertificate attribute in the user entry, such as uid=admin,ou=people,dc=subsystem-base-DN.

12.3.2.4. Deleting a Certificate System User

Users can be deleted from the internal database. Deleting a user from the internal database deletes that user from all groups to which the user belongs. To remove the user from specific groups, modify the group membership.

Delete a privileged user from the internal database by doing the following:

Log into the administrative console.
Select Users and Groups from the navigation menu on the left.
Select the user from the list of user IDs, and click Delete.
Confirm the delete when prompted.

12.4. Configuring Access Control for Users

Authorization is the mechanism that checks whether a user is allowed to perform an operation. Authorization points are defined in certain groups of operations that require an authorization check.

12.4.1. About Access Control

Access control lists (ACLs) are the mechanisms that specify the authorization to server operations. An ACL exists for each set of operations where an authorization check occurs. Additional operations can be added to a ACL.

The ACL contains access control instructions (ACIs) which specifically allow or deny operations, such as read or modify. The ACI also contains an evaluator expression. The default implementation of ACLs specifies only users, groups, and IP addresses as possible evaluator types. Each ACI in an ACL specifies whether access is allowed or denied, what the specific operator is being allowed or denied, and which users, groups, or IP addresses are being allowed or denied to perform the operation.

The privileges of Certificate System users are changed by changing the access control lists (ACL) that are associated with the group in which the user is a member, for the users themselves, or for the IP address of the user. New groups are assigned access control by adding that group to the access control lists. For example, a new group for administrators who are only authorized to view logs, LogAdmins, can be added to the ACLs relevant to logs to allow read or modify access to this group. If this group is not added to any other ACLs, members of this group only have access to the logs.

The access for a user, group, or IP address is changed by editing the ACI entries in the ACLs. In the ACL interface, each ACI is shown on a line of its own. In this interface window, the ACI has the following syntax:

allow|deny (operation) user|group|IP="name"

Note

The IP address can be an IPv4 or IPv6 address. An IPv4 address must be in the format n.n.n.n or n.n.n.n,m.m.m.m. For example, 128.21.39.40 or 128.21.39.40,255.255.255.00. An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example, 0:0:0:0:0:0:13.1.68.3, FF01::43, 0:0:0:0:0:0:13.1.68.3,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:255.255.255.0, and FF01::43,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00:0000.

For example, the following is an ACI that allows administrators to perform read operations:

allow (read) group="Administrators"

An ACI can have more than one operation or action configured. The operations are separated with a comma with no space on either side. For example:

allow (read,modify) group="Administrators"

An ACI can have more than one group, user, or IP address by separating them with two pipe symbols (||) with a space on either side. For example:

allow (read) group="Administrators" || group="Auditors"

The administrative console can create or modify ACIs. The interface sets whether to allow or deny the operation in the Allow and Deny field, sets which operations are possible in the Operations field, and then lists the groups, users, or IP addresses being granted or denied access in the Syntax field.

An ACI can either allow or deny an operation for the specified group, user ID, or IP address. Generally, ACIs do not need to be created to deny access. If there are no allow ACIs that include a user ID, group, or IP address, then the group, user ID, or IP address is denied access.

Note

If a user is not explicitly allowed access to any of the operations for a resource, then this user is considered denied; he does not specifically need to be denied access.

For example, user JohnB is a member of the Administrators group. If an ACL has only the following ACL, JohnB is denied any access since he does not match any of the allow ACIs:

Allow (read,modify) group="Auditors" || user="BrianC"

There usually is no need to include a deny statement. Some situations can arise, however, when it is useful to specify one. For example, JohnB, a member of the Administrators group, has just been fired. It may be necessary to deny access specifically to JohnB if the user cannot be deleted immediately. Another situation is that a user, BrianC, is an administrator, but he should not have the ability to change some resource. Since the Administrators group must access this resource, BrianC can be specifically denied access by creating an ACI that denies this user access.

The allowed rights are the operations which the ACI controls, either by allowing or denying permission to perform the operation. The actions that can be set for an ACL vary depending on the ACL and subsystem. Two common operations that can be defined are read and modify.

The syntax field of the ACI editor sets the evaluator for the expression. The evaluator can specify group, name, and IP address (both IPv4 and IPv6 addresses). These are specified along with the name of the entity set as equals (=) or does not equal (!=).

The syntax to include a group in the ACL is group="groupname". The syntax to exclude a group is group!="groupname", which allows any group except for the group named. For example:

group="Administrators" || group!="Auditors"

It is also possible to use regular expressions to specify the group, such as using wildcard characters like an asterisk (*). For example:

group="* Managers"

For more information on supported regular expression patterns, see https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.

The syntax to include a user in the ACL is user="userID". The syntax to exclude the user is user!="userID", which allows any user ID except for the user ID named. For example:

user="BobC" || user!="JaneK"

To specify all users, provide the value anybody. For example:

user="anybody"

It is also possible to use regular expressions to specify the user names, such as using wildcard characters like an asterisk (*). For example:

user="*johnson"

For more information on supported regular expression patterns, see https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.

The syntax to include an IP address in the ACL is ipaddress="ipaddress". The syntax to exclude an ID address from the ACL is ipaddress!="ipaddress". An IP address is specified using its numeric value; DNS values are not permitted. For example:

ipaddress="12.33.45.99"
ipaddress!="23.99.09.88"

The IP address can be an IPv4 address, as shown above, or IPv6 address. An IPv4 address has the format n.n.n.n or n.n.n.n,m.m.m.m with the netmask. An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example:

ipaddress="0:0:0:0:0:0:13.1.68.3"

It is also possible to use regular expressions to specify the IP address, such as using wildcard characters like an asterisk (*). For example:

ipaddress="12.33.45.*"

For more information on supported regular expression patterns, see https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.

It is possible to create a string with more than one value by separating each value with two pipe characters (||) with a space on either side. For example:

user="BobC" || group="Auditors" || group="Administrators"

12.4.2. Adding ACLs

ACLs are stored in the internal database and can only be modified in the administrative console.

To add a new ACL:

Log into the administrative console.
Select Access Control List.
Click Add to open the Access Control Editor.
Fill the Resource name and Available rights fields.
To add an access control instruction (ACI), click Add, and supply the ACI information.
1. Select the allow or deny radio button from the Access field to allow or deny the operation to the groups, users, or IP addresses specified. For more information about allowing or denying access, see Section 12.4.1, “About Access Control”.
2. Set the rights. The available options are read and modify. To select both, hold the Ctrl or Shift button while selecting the entries.
3. Specify the user, group, or IP address that will be granted or denied access in the Syntax field. See Section 12.4.1, “About Access Control” for details on syntax.
Click OK to return to the Access Control Editor window.
Click OK to store the ACI.

12.4.3. Editing ACLs

ACLs are stored in the internal database and can only be modified in the administrative console.

To edit the existing ACLs:

Log into the administrative console.
Select Access Control List in the left navigation menu.
Select the ACL to edit from the list, and click Edit.
The ACL opens in the Access Control Editor window.
To add an ACI, click Add, and supply the ACI information.
To edit an ACI, select the ACI from the list in the ACI entries text area of the ACL Editor window. Click Edit.
1. Select the allow or deny radio button from the Access field to allow or deny the operation to the groups, users, or IP addresses specified. For more information about allowing or denying access, see Section 12.4.1, “About Access Control”.
2. Set the rights for the access control. The options are read and modify. To set both, use the Ctrl or Shift buttons.
3. Specify the user, group, or IP address that will be granted or denied access in the Syntax field. See Section 12.4.1, “About Access Control” for details on syntax.

Chapter 13. Configuring Subsystem Logs

For an overview on logs, see the Logs section under the Certificate System Architecture Overview section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition).

For log configuration during the installation and additional information, see the Configuring Logs section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition).

13.1. Managing Logs

The Certificate System subsystem log files record events related to operations within that specific subsystem instance. For each subsystem, different logs are kept for issues such as installation, access, and web servers.

All subsystems have similar log configuration, options, and administrative paths.

13.1.1. Configuring Logs in the Console

Logs can be configured through the subsystem Console. Specialized logs, such as signed audit logs and custom logs, can also be created through the Console or configuration file.

In the navigation tree of the Configuration tab, select Log.
The Log Event Listener Management tab lists the currently configured listeners.
To create a new log instance, click Add, and select a module plug-in from the list in the Select Log Event Listener Plug-in Implementation window.
Set or modify the fields in the Log Event Listener Editor window. The different parameters are listed in Table 13.1, “Log Event Listener Fields”.

Table 13.1. Log Event Listener Fields
Field	Description
Log Event Listener ID	Gives the unique name that identifies the listener. The names can have any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-), but it cannot contain other characters or spaces.
type	Gives the type of log file. system creates error and system logs; transaction records audit logs.
enabled	Sets whether the log is active. Only enabled logs actually record events. The value is either `true` or `false`.
level	Sets the log level in the text field. The level must be manually entered in the field; there is no selection menu. The choices are Debug, Information, Warning, Failure, Misconfiguration, Catastrophe, and Security.
fileName	Gives the full path, including the file name, to the log file. The subsystem user should have read/write permission to the file.
bufferSize	Sets the buffer size in kilobytes (KB) for the log. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file. The default size is 512 KB.
flushInterval	Sets the amount of time before the contents of the buffer are flushed out and added to the log file. The default interval is 5 seconds.
maxFileSize	Sets the size, in kilobytes (KB), a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started new. The default size is 2000 KB.
rolloverInterval	Sets the frequency for the server to rotate the active log file. The available options are hourly, daily, weekly, monthly, and yearly. The default is monthly.

13.1.2. Managing Audit Logs

The audit log contains audit records for events that have been set up as recordable events. If you enabled the audit log signing option as described in the Enabling and Configuring Signed Audit Logs section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition), the audit log is signed with a log signing certificate belonging to the server. This certificate can be used by auditors to verify that the log has not been tampered with.

Note

Signed audit logs are optional. To enable them, please refer to Section 13.1.2.1, “Configuring a Signed Audit Log in the Console”.

By default, regular audit logs are located in the /var/log/pki/instance_name/subsystem_name/ directory with other types of logs, while signed audit logs are written to /var/log/pki/instance_name/subsystem_name/signedAudit/. The default location for logs can be changed by modifying the configuration.

The signed audit log creates a log recording system events, and the events are selected from a list of potential events. When enabled, signed audit logs record a verbose set of messages about the selected event activity.

It is also possible to edit the configuration or change the signing certificates after configuration, as covered in Section 13.1.2.1, “Configuring a Signed Audit Log in the Console”.

13.1.2.1. Configuring a Signed Audit Log in the Console

Signed audit logs are configured by default when the instance is first created, but it is possible to edit the configuration or change the signing certificates after the installation.

Note

Provide enough space in the file system for the signed audit logs, since they can be large.

A log is set to a signed audit log by setting the logSigning parameter to enable and providing the nickname of the certificate used to sign the log. A special log signing certificate is created when the subsystems are first configured.

Only a user with auditor privileges can access and view a signed audit log. Auditors can use the AuditVerify tool to verify that signed audit logs have not been tampered with.

The signed audit log is created and enabled when the subsystem is configured, but it needs additional configuration to begin creating and signing audit logs.

Open the Console.
In the navigation tree of the Configuration tab, select Log.
In the Log Event Listener Management tab, select the SignedAudit entry.
Click Edit/View.
There are two fields which must be reset in the Log Event Listener Editor window.
- Set the logSigning field to true to enable signed logging.
  Note
  For more fine-grained audit event select, set audit event filters during the installation configuration. For details, see the Filtering Audit Events section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
- Set any events which are logged to the audit log. Appendix E, Audit Events lists the loggable events. Log events are separated by commas with no spaces.
Save the log configuration.

After enabling signed audit logging, assign auditor users by creating the user and assigning that entry to the auditor group. Members of the auditor group are the only users who can view and verify the signed audit log. See Section 12.3.2.1, “Creating Users” for details about setting up auditors.

Auditors can verify logs by using the AuditVerify tool. See the AuditVerify(1) man page for details about using this tool. For further details, see Section 13.2.2, “Using Signed Audit Logs”.

13.1.2.2. Handling Audit Logging Failures

There are events that could cause the audit logging function to fail, so events cannot be written to the log. For example, audit logging can fail when the file system containing the audit log file is full or when the file permissions for the log file are accidentally changed.

If log signing is enabled and audit logging fails, the Certificate System instance shuts down in the following manner.

Servlets are disabled and will not process new requests.
All pending and new requests are killed.
The subsystem is shut down.

When this happens, administrators and auditors should work together with the operating system administrator to resolve the disk space or file permission issues. When the IT problem is resolved, the auditor should make sure that the last audit log entries are signed. When this is completed, the administrators can restart the Certificate System.

13.2. Using Logs

13.2.1. Viewing Logs in the Console

To troubleshoot the subsystem, check the error or informational messages that the server has logged. Examining the log files can also monitor many aspects of the server's operation. Some log files can be viewed through the Console. However, the audit log is only accessible by users with the Auditor role, using a method detailed in Section 13.2.2, “Using Signed Audit Logs”.

To view the contents of an active or rotated system log file:

Log into the Console.
Select the Status tab.
Under Logs, select the log to view.
Set the viewing preferences in the Display Options section.
- Entries — The maximum number of entries to be displayed. When this limit is reached, the Certificate System returns any entries that match the search request. Zero (0) means no messages are returned. If the field is blank, the server returns every matching entry, regardless of the number found.
- Source — Select the Certificate System component or service for which log messages are to be displayed. Choosing All means messages logged by all components that log to this file are displayed.
- Level — Select a message category that represents the log level for filtering messages.
- Filename — Select the log file to view. Choose Current to view the currently active system log file.
Click Refresh.
The table displays the system log entries. The entries are in reverse chronological order, with the most current entry placed at the top. Use the scroll arrows on the right edge of the panel to scroll through the log entries.
Each entry has the following information shown:
- Source — The component or resource that logged the message.
- Level — The severity of the corresponding entry.
- Date — The date on which the entry was logged.
- Time — The time at which the entry was logged.
- Details — A brief description of the log.
To view a full entry, double-click it, or select the entry, and click View.

13.2.2. Using Signed Audit Logs

This section explains how a user in the Auditor group displays and verifies signed audit logs.

13.2.2.1. Listing Audit Logs

As a user with auditor privileges, use the the pki subsystem-audit-file-find command to list existing audit log files on the server.

For example, to list the audit log files on the CA hosted on server.example.com:

# pki -h server.example.com -p 8443 -n auditor ca-audit-file-find
-----------------
3 entries matched
-----------------
  File name: ca_audit.20170331225716
  Size: 2883

  File name: ca_audit.20170401001030
  Size: 189

  File name: ca_audit
  Size: 6705
----------------------------
Number of entries returned 3
----------------------------

The command uses the client certificate with the auditor nickname stored in the ~/.dogtag/nssdb/ directory for authenticating to the CA. For further details about the parameters used in the command and alternative authentication methods, see the pki(1) man page.

13.2.2.2. Downloading Audit Logs

As a user with auditor privileges, use the pki subsystem-audit-file-retrieve command to download a specific audit log from the server.

For example, to download an audit log file from the CA hosted on server.example.com:

Optionally, list the available log files on the CA. See Section 13.2.2.1, “Listing Audit Logs”.
Download the log file. For example, to download the ca_audit file:
```
# pki -U https://server.example.com:8443 -n auditor ca-audit-file-retrieve ca_audit
```
The command uses the client certificate with the auditor nickname stored in the ~/.dogtag/nssdb/ directory for authenticating to the CA. For further details about the parameters used in the command and alternative authentication methods, see the pki(1) man page.

After downloading a log file, you can search for specific log entries, for example, using the grep utility:

# grep "\[AuditEvent=ACCESS_SESSION_ESTABLISH\]" log_file

13.2.2.3. Verifying Signed Audit Logs

If audit log signing is enabled, users with auditor privileges can verify the logs:

Initialize the NSS database and import the CA certificate. For details, see the Command-line Initialization section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition).

If the audit signing certificate does not exist in the PKI client database, import it:

Search the audit signing certificate for the subsystem logs you want to verify. For example:

# pki ca-cert-find --name "CA Audit Signing Certificate"
---------------
1 entries found
---------------
  Serial Number: 0x5
  Subject DN: CN=CA Audit Signing Certificate,O=EXAMPLE
  Status: VALID
  Type: X.509 version 3
  Key Algorithm: PKCS #1 RSA with 2048-bit key
  Not Valid Before: Fri Jul 08 03:56:08 CEST 2016
  Not Valid After: Thu Jun 28 03:56:08 CEST 2018
  Issued On: Fri Jul 08 03:56:08 CEST 2016
  Issued By: system
----------------------------
Number of entries returned 1
----------------------------

Import the audit signing certificate into the PKI client:

# pki client-cert-import "CA Audit Signing Certificate" --serial 0x5 --trust ",,P"
---------------------------------------------------
Imported certificate "CA Audit Signing Certificate"
---------------------------------------------------

Download the audit logs. See Section 13.2.2.2, “Downloading Audit Logs”.
Verify the audit logs.
1. Create a text file that contains a list of the audit log files you want to verify in chronological order. For example:
```
# cat > ~/audit.txt << EOF
ca_audit.20170331225716
ca_audit.20170401001030
ca_audit
EOF
```
2. Use the AuditVerify utility to verify the signatures. For example:
```
# AuditVerify -d ~/.dogtag/nssdb/ -n "CA Audit Signing Certificate" \
     -a ~/audit.txt
Verification process complete.
Valid signatures: 10
Invalid signatures: 0
```
  For further details about using AuditVerify, see the AuditVerify(1) man page.

13.2.3. Displaying Operating System-level Audit Logs

Note

To see Operating System-level audit logs using the instructions below, the auditd logging framework must be configured per the Enabling OS-level Audit Logs section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition).

To display operating system-level access logs, use the ausearch utility as root or as a privileged user with the sudo utility.

13.2.3.1. Displaying Audit Log Deletion Events

Since these events are keyed (with rhcs_audit_deletion), use the -k parameter to find events matching that key:

# ausearch -k rhcs_audit_deletion

13.2.3.2. Displaying Access to the NSS Database for Secret and Private Keys

Since these events are keyed (with rhcs_audit_nssdb), use the -k parameter to find events matching that key:

# ausearch -k rhcs_audit_nssdb

13.2.3.3. Displaying Time Change Events

Since these events are keyed (with rhcs_audit_time_change), use the -k parameter to find events matching that key:

# ausearch -k rhcs_audit_time_change

13.2.3.4. Displaying Package Update Events

Since these events are a typed message (of type SOFTWARE_UPDATE), use the -m parameter to find events matching that type:

# ausearch -m SOFTWARE_UPDATE

13.2.3.5. Displaying Changes to the PKI Configuration

Since these events are keyed (with rhcs_audit_config), use the -k parameter to find events matching that key:

# ausearch -k rhcs_audit_config

Chapter 14. 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.

14.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; planning the formats of certificates is covered in the Types of Certificates section in the Red Hat Certificate System 9 Planning, Installation, and Deployment Guide (Common Criteria Edition).

14.1.1. Certificate Manager Certificates

When a Certificate Manager is installed, the keys and requests for the CA signing certificate, TLS 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.

Section 14.1.1.1, “CA Signing Key Pair and Certificate”
Section 14.1.1.2, “OCSP Signing Key Pair and Certificate”
Section 14.1.1.3, “Subsystem Certificate”
Section 14.1.1.4, “TLS Server Key Pair and Certificate”
Section 14.1.1.5, “Audit Log Signing Key Pair and Certificate”

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

Note

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.

14.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, 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.

14.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 TLS 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.

14.1.1.4. TLS Server Key Pair and Certificate

Every Certificate Manager has at least one TLS 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 TLS 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 TLS-enabled communication with a publishing directory, it uses its TLS server certificate for client authentication to the publishing directory by default. The Certificate Manager can also be configured to use a different certificate for TLS client authentication.

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

Note

While other certificates can use ECC keys, the audit signing certificate must always use an RSA key.

14.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, TLS 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.

Section 14.1.2.2, “TLS Server Key Pair and Certificate”
Section 14.1.2.3, “Subsystem Certificate”
Section 14.1.2.4, “Audit Log Signing Key Pair and Certificate”
Section 14.1.2.5, “Recognizing Online Certificate Status Manager Certificates”

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

14.1.2.2. TLS Server Key Pair and Certificate

Every Online Certificate Status Manager has at least one TLS 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.

14.1.2.3. Subsystem Certificate

The default nickname for the certificate is subsystemCert cert-instance_ID.

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

Note

While other certificates can use ECC keys, the audit signing certificate must always use an RSA key.

14.1.2.5. Recognizing Online Certificate Status Manager Certificates

Depending on the CA which signed the Online Certificate Status Manager's TLS 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 TLS 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.

Note

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.

14.1.3. Key Recovery Authority Certificates

The KRA uses the following key pairs and certificates:

Section 14.1.3.1, “Transport Key Pair and Certificate”
Section 14.1.3.2, “Storage Key Pair”
Section 14.1.3.3, “TLS Server Certificate”
Section 14.1.3.4, “Subsystem Certificate”
Section 14.1.3.5, “Audit Log Signing Key Pair and Certificate”

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

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

14.1.3.3. TLS Server Certificate

Every Certificate System KRA has at least one TLS server certificate. The first TLS 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 TLS 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 TLS server certificate for server-side authentication to the KRA agent services interface. By default, the Key Recovery Authority uses a single TLS server certificate for authentication. However, additional TLS server certificates can be requested and installed for the KRA.

14.1.3.4. Subsystem Certificate

The default nickname for the certificate is subsystemCert cert-instance_ID.

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

Note

While other certificates can use ECC keys, the audit signing certificate must always use an RSA key.

14.1.4. TKS Certificates

The TKS has three certificates. The TLS server and subsystem certificates are used for standard operations. An additional signing certificate is used to protect audit logs.

Section 14.1.4.1, “TLS Server Certificate”
Section 14.1.4.2, “Subsystem Certificate”
Section 14.1.4.3, “Audit Log Signing Key Pair and Certificate”

14.1.4.1. TLS Server Certificate

Every Certificate System TKS has at least one TLS server certificate. The first TLS server certificate is generated when the TKS is configured. The default nickname for the certificate is Server-Cert cert-instance_ID.

14.1.4.2. Subsystem Certificate

The default nickname for the certificate is subsystemCert cert-instance_ID.

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

Note

While other certificates can use ECC keys, the audit signing certificate must always use an RSA key.

14.1.5. TPS Certificates

The TPS only uses three certificates: a server certificate, subsystem certificate, and audit log signing certificate.

Section 14.1.5.1, “TLS Server Certificate”
Section 14.1.5.2, “Subsystem Certificate”
Section 14.1.5.3, “Audit Log Signing Key Pair and Certificate”

14.1.5.1. TLS Server Certificate

Every Certificate System TPS has at least one TLS server certificate. The first TLS server certificate is generated when the TPS is configured. The default nickname for the certificate is Server-Cert cert-instance_ID.

14.1.5.2. Subsystem Certificate

The default nickname for the certificate is subsystemCert cert-instance_ID.

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

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

Note

The values in the example are for a CA. Other subsystems require different parameters.

For further details, see:

The Understanding the pkispawn Utility section in the Red Hat Certificate System Planning, Installation, and Deployment Guide (Common Criteria Edition).
The pki_default.cfg(5) man page for descriptions of the parameters and examples.

14.1.7. Using an HSM to Store Subsystem Certificates

By default, keys and certificates are stored in locally-managed databases, key3.db and cert8.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. For example:

serverCert="nethsm:Server-Cert cert-instance_ID

Note

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, nCipher netHSM and Chrysalis LunaSA.

14.2. Renewing Subsystem Certificates

For details about renewing subsystem certificates, see Section 3.4.1, “About Renewal”.

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

14.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 converted to a CMC request to be submitted to the CA. For details, see Section 5.2.1, “Creating a CSR Using certutil”.

Note

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=263163888660

Open the certificate database directory of the instance whose certificate is being renewed.
```
cd /var/lib/pki/instance_name/alias
```

List 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 CA

Copy the alias directory as a backup, then delete the original certificate from the certificate database. For example:
```
certutil -D -n "ServerCert cert-example"  -d .
```
Run the certutil command with the options set to the values in the existing certificate.
```
certutil -d . -R -k "NSS Certificate DB:cert-pki-tomcat CA" -s "cn=CA Authority,o=Example Domain" -a -o example.req2.txt
```
The difference between generating a new certificate and key pair and renewing the certificate is the value of the -k 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 -k 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.

14.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:
1. Create a temporary certificate:
```
# pki-server cert-create sslserver --temp
```
2. Import the temporary certificate into Certificate System's Network Security Services (NSS) database:
```
# pki-server cert-import sslserver
```
3. Start Certificate System:
```
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
```
Display the certificates and note the ID of the expired system certificate:
```
# pki-server cert-find
```
Create the new permanent certificate:
```
# pki-server cert-create certificate_ID
```

Stop Certificate System:

# systemctl stop pki-tomcatd-nuxwdog@instance_name.service

Import the new certificate to replace the expired certificate:
```
# pki-server cert-import certificate_ID
```

Start Certificate System:

# systemctl start pki-tomcatd-nuxwdog@instance_name.service

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

These tables list all of the configuration parameters for each of the subsystem's certificates:

Table 14.1, “CA Certificate Nickname Parameters”
Table 14.2, “KRA Certificate Nickname Parameters”
Table 14.3, “OCSP Certificate Nickname Parameters”
Table 14.4, “TKS Certificate Nickname Parameters”
Table 14.5, “TPS Nickname Parameters”

Table 14.1. CA Certificate Nickname Parameters
CA Signing Certificate	ca.cert.signing.nickname ca.signing.cacertnickname ca.signing.certnickname ca.signing.nickname cloning.signing.nickname
OCSP Signing Certificate	ca.ocsp_signing.cacertnickname ca.ocsp_signing.certnickname ca.cert.ocsp_signing.nickname ca.ocsp_signing.nickname cloning.ocsp_signing.nickname
Subsystem Certificate	ca.cert.subsystem.nickname ca.subsystem.nickname cloning.subsystem.nickname pkiremove.cert.subsystem.nickname
Server Certificate	ca.sslserver.nickname ca.cert.sslserver.nickname
Audit Signing Certificate	ca.audit_signing.nickname ca.cert.audit_signing.nickname cloning.audit_signing.nickname

Table 14.2. KRA Certificate Nickname Parameters
Transport Certificate	cloning.transport.nickname kra.cert.transport.nickname kra.transport.nickname tks.kra_transport_cert_nickname Note that this parameter is in the TKS configuration file. This needs changed in the TKS configuration if the KRA transport certificate nickname changes, even if the TKS certificates all stay the same.
Storage Certificate	cloning.storage.nickname kra.storage.nickname kra.cert.storage.nickname
Server Certificate	kra.cert.sslserver.nickname kra.sslserver.nickname
Subsystem Certificate	cloning.subsystem.nickname kra.cert.subsystem.nickname kra.subsystem.nickname pkiremove.cert.subsystem.nickname
Audit Log Signing Certificate	cloning.audit_signing.nickname kra.cert.audit_signing.nickname kra.audit_signing.nickname

Table 14.3. OCSP Certificate Nickname Parameters
OCSP Signing Certificate	cloning.signing.nickname ocsp.signing.certnickname ocsp.signing.cacertnickname ocsp.signing.nickname
Server Certificate	ocsp.cert.sslserver.nickname ocsp.sslserver.nickname
Subsystem Certificate	cloning.subsystem.nickname ocsp.subsystem.nickname ocsp.cert.subsystem.nickname pkiremove.cert.subsystem
Audit Log Signing Certificate	cloning.audit_signing.nickname ocsp.audit_signing.nickname ocsp.cert.audit_signing.nickname

Table 14.4. TKS Certificate Nickname Parameters
KRA Transport Certificate^[a]	tks.kra_transport_cert_nickname
Server Certificate	tks.cert.sslserver.nickname tks.sslserver.nickname
Subsystem Certificate	cloning.subsystem.nickname tks.cert.subsystem.nickname tks.subsystem.nickname pkiremove.cert.subsystem.nickname
Audit Log Signing Certificate	cloning.audit_signing.nickname tks.audit_signing.nickname tks.cert.audit_signing.nickname
^[a] This needs changed in the TKS configuration if the KRA transport certificate nickname changes, even if the TKS certificates all stay the same.

Table 14.5. TPS Nickname Parameters
Server Certificate	tps.cert.sslserver.nickname
Subsystem Certificate	tps.cert.subsystem.nickname selftests.plugin.TPSValidity.nickname selftests.plugin.TPSPresence.nickname pkiremove.cert.subsystem.nickname
Audit Log Signing Certificate	tps.cert.audit_signing.nickname

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

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

Section 14.4.1.1, “Installing Certificates through the Console”
Section 14.4.1.2, “Installing Certificates Using certutil”
Section 14.4.1.3, “About CA Certificate Chains”

14.4.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 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 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 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-----
```
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 Section 14.5, “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.

14.4.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/alias
```
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.

14.4.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 TLS-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.

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

Section 14.4.2.1, “Viewing Database Content through the Console”
Section 14.4.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.

14.4.2.1. Viewing Database Content through the Console

To view the contents of the database through the administrative 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.
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.
Figure 14.1. 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.

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

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

Section 14.4.3.1, “Deleting Certificates through the Console”
Section 14.4.3.2, “Deleting Certificates Using certutil”

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

14.4.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/al
```

Administration Guide (Common Criteria Edition)

Updated for Red Hat Certificate System 9.4 Common Criteria Certification

Red Hat

Chapter 1. Overview of Red Hat Certificate System Subsystems

1.1. Uses for Certificates

1.2. A Review of Certificate System Subsystems

1.3. A Look at Managing Certificates (Non-TMS)

1.4. A Look at the Token Management System (TMS)

1.5. Red Hat Certificate System services

Part I. Red Hat Certificate System User Interfaces

Chapter 2. User Interfaces

2.1. User Interfaces Overview

2.2. Client NSS Database Initialization

2.3. Graphical Interface

2.3.1. pkiconsole Initialization

2.3.2. Using pkiconsole for CA, OCSP, KRA, and TKS Subsystems

2.4. Web Interface

2.4.1. Browser Initialization

Importing a CA Certificate

Importing a Client Certificate

Accessing the Web Console

2.4.2. The Administrative Interfaces

2.4.3. Agent Interfaces

2.4.4. End User Pages

2.5. Command Line Interfaces

2.5.1. "pki" CLI

2.5.1.1. pki CLI Initialization

2.5.1.2. Using "pki" CLI

2.5.2. AtoB

2.5.3. AuditVerify

2.5.4. BtoA

2.5.5. CMCRequest

2.5.6. CMCRevoke

2.5.7. CMCSharedToken

2.5.8. CRMFPopClient

2.5.9. HttpClient

2.5.10. OCSPClient

2.5.11. PKCS10Client

2.5.12. PrettyPrintCert

2.5.13. PrettyPrintCrl

2.5.14. TokenInfo

2.5.15. tkstool

Part II. Setting up Certificate Services

Chapter 3. Making Rules for Issuing Certificates (Certificate Profiles)

3.1. About Certificate Profiles

3.1.1. The Enrollment Profile

3.1.2. Certificate Extensions: Defaults and Constraints

3.1.3. Inputs and Outputs

3.2. Setting up Certificate Profiles

3.2.1. Managing Certificate Enrollment Profiles Using the PKI Command-line Interface

3.2.1.1. Enabling and Disabling a Certificate Profile

3.2.1.2. Creating a Certificate Profile in Raw Format

3.2.1.3. Editing a Certificate Profile in Raw Format

3.2.1.4. Deleting a Certificate Profile

3.2.2. Managing Certificate Enrollment Profiles Using the Java-based Administration Console

3.2.2.1. Creating Certificate Profiles through the CA Console

3.2.2.2. Editing Certificate Profiles in the Console

3.2.3. Listing Certificate Enrollment Profiles

3.2.4. Displaying Details of a Certificate Enrollment Profile

3.3. Defining Key Defaults in Profiles

3.4. Configuring Profiles to Enable Renewal

3.4.1. About Renewal

3.4.1.1. The Renewal Process

3.4.1.1.1. Renewing Using the Same Key

3.4.1.1.2. Renewal Using a New Key

3.5. Setting the Signing Algorithms for Certificates

3.5.1. Setting the CA's Default Signing Algorithm

3.5.2. Setting the Signing Algorithm Default in a Profile

3.6. Managing CA-Related Profiles

3.6.1. Setting Restrictions on CA Certificates

3.6.2. Changing the Restrictions for CAs on Issuing Certificates

3.6.3. Using Random Certificate Serial Numbers

3.6.3.1. Enabling Random Certificate Serial Numbers

3.6.4. Allowing a CA Certificate to Be Renewed Past the CA's Validity Period

3.7. Managing Subject Names and Subject Alternative Names

3.7.1. Using the Requester CN or UID in the Subject Name

3.7.2. Inserting LDAP Directory Attribute Values and Other Information into the Subject Alt Name

3.7.3. Using the CN Attribute in the SAN Extension

3.7.4. Accepting SAN Extensions from a CSR

3.7.4.1. Configuring a Profile to Retrieve SANs from a CSR

2.3.1. `pkiconsole` Initialization

2.3.2. Using `pkiconsole` for CA, OCSP, KRA, and TKS Subsystems

5.2.1. Creating a CSR Using `certutil`

5.2.1.1. Using `certutil` to Create a CSR with EC Keys

5.2.1.2. Using `certutil` to Create a CSR With User-defined Extensions

5.2.2. Creating a CSR Using `PKCS10Client`

5.2.2.1. Using `PKCS10Client` to Create a CSR

5.2.2.2. Using `PKCS10Client` to Create a CSR for SharedSecret-based CMC

5.2.3. Creating a CSR Using `CRMFPopClient`

5.2.3.1. Using `CRMFPopClient` to Create a CSR with Key Archival

5.2.3.2. Using `CRMFPopClient` to Create a CSR for SharedSecret-based CMC

6.2.1.1. Revoking a Certificate Using `CMCRequest`

6.2.1.2. Revoking a Certificate Using `CMCRevoke`