Administration Guide
Red Hat Certificate System 10
Updated for Red Hat Certificate System 10.4
Abstract
This manual covers all aspects of installing, configuring, and managing Certificate System subsystems. 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
Every common PKI operation — issuing, renewing and revoking certificates; archiving and recovering keys; publishing CRLs and verifying certificate status — are 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 is 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.
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 section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
Enterprise Security Client
The Enterprise Security Client is not a subsystem since it does not perform any operations with certificates, keys, or tokens. The Enterprise Security Client is a user interface which allows people to manage certificates on smart cards very easily. The Enterprise Security Client sends all token operations, such as certificate requests, to the token processing system (TPS), which then sends them to the certificate authority (CA). For more information, see For more information, see Red Hat Certificate System Managing Smart Cards with the Enterprise Security Client.
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 the Red Hat Certificate System Planning, Installation, and Deployment Guide:
1.4. A Look at the Token Management System (TMS)
Certificate System creates, manages, renews, and revokes certificates, and it also archives and recovers keys. For organizations which 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 the Red Hat Certificate System Planning, Installation, and Deployment Guide:
1.5. Red Hat Certificate System services
There are various different interfaces for managing certificates and subsystems, depending on the user type: administrators, agents, auditors, and end users. For an overview of the different functions that are performed through each interface, see the User Interfaces section.
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.1.2, “Creating a CSR Using
PKCS10Client”.
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.
The Certificate System's PKI Console is a graphical interface. Please note that it is being deprecated. Section 2.3.1, “
pkiconsole Initialization” describes how to initialize this console interface. Section 2.3.2, “Using pkiconsole for CA, OCSP, KRA, and TKS Subsystems” gives an overview of using it. 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.
Note
To terminate a PKI Console session, click the 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:
2.3. Graphical Interface
Important
pkiconsole is being deprecated.
The Certificate System console,
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 the Importing a certificate into an NSS Database section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
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 the Managing Certificate/Key Crypto Token section in the Red Hat Certificate System Planning, Installation, and Deployment Guide:
$ 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.
- 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)
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 → → → .
- Select the Authorities tab and click the button.
- Select the
ca.crtfile and click .
Importing a Client Certificate
- Click → → → .
- Select the Your Certificates tab.
- Click on and select the client p12 file, such as
ca_admin_cert.p12. - Enter the password for the client certificate on the prompt.
- Click .
- 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. 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 the Importing a certificate into an NSS Database section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
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 the Managing Certificate/Key Crypto Token section in the Red Hat Certificate System Planning, Installation, and Deployment Guide:
$ 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 Section 16.3.2, “Using Signed Audit Logs”.
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 Section 7.2.1, “Revoking a Certificate Using CMCRequest”.
2.5.6. CMCRevoke
Legacy. Do not use.
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 Section 7.2.1, “Revoking a Certificate Using CMCRequest”.
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.
2.6. Enterprise Security Client
The Enterprise Security Client is a tool for Red Hat Certificate System which simplifies managing smart cards. End users can use security tokens (smart cards) to store user certificates used for applications such as single sign-on access and client authentication. End users are issued the tokens containing certificates and keys required for signing, encryption, and other cryptographic functions.
The Enterprise Security Client is the third part of Certificate System's complete token management system. Two subsystems — the Token Key Service (TKS) and Token Processing System (TPS) — are used to process token-related operations. The Enterprise Security Client is the interface which allows the smart card and user to access the token management system.
After a token is enrolled, applications such as Mozilla Firefox and Thunderbird can be configured to recognize the token and use it for security operations, like client authentication and S/MIME mail. Enterprise Security Client provides the following capabilities:
- Supports JavaCard 2.1 or higher cards and Global Platform 2.01-compliant smart cards like Safenet's 330J smart card.
- Supports Gemalto TOP IM FIPS CY2 tokens, both the smart card and GemPCKey USB form factor key.
- Supports SafeNet Smart Card 650 (SC650).
- Enrolls security tokens so they are recognized by TPS.
- Maintains the security token, such as re-enrolling a token with TPS.
- Provides information about the current status of the token or tokens being managed.
- Supports server-side key generation so that keys can be archived and recovered on a separate token if a token is lost.
The Enterprise Security Client is a client for end users to register and manage keys and certificates on smart cards or tokens. This is the final component in the Certificate System token management system, with the Token Processing System (TPS) and Token Key Service (TKS).
The Enterprise Security Client provides the user interface of the token management system. The end user can be issued security tokens containing certificates and keys required for signing, encryption, and other cryptographic functions. To use the tokens, the TPS must be able to recognize and communicate with them. Enterprise Security Client is the method for the tokens to be enrolled.
Enterprise Security Client communicates over an SSL/TLS HTTP channel to the back end of the TPS. It is based on an extensible Mozilla XULRunner framework for the user interface, while retaining a legacy web browser container for a simple HTML-based UI.
After a token is properly enrolled, web browsers can be configured to recognize the token and use it for security operations. Enterprise Security Client provides the following capabilities:
- Allows the user to enroll security tokens so they are recognized by the TPS.
- Allows the user to maintain the security token. For example, Enterprise Security Client makes it possible to re-enroll a token with the TPS.
- Provides support for several different kinds of tokens through default and custom token profiles. By default, the TPS can automatically enroll user keys, device keys, and security officer keys; additional profiles can be added so that tokens for different uses (recognized by attributes such as the token CUID) can automatically be enrolled according to the appropriate profile.
- Provides information about the current status of the tokens being managed.
Part II. Setting up Certificate Services
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
setentry 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
subjectaltnameextension is always set totrue.
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.32, “User Supplied Extension Default”.
3.1.3. Inputs and Outputs
Inputs set information that must be submitted to receive a certificate. This can be requester information, a specific format of certificate request, or organizational information.
The outputs configured in the profile define the format of the certificate that is issued.
In Certificate System, profiles are accessed by users through enrollment forms that are accessed through the end-entities pages. (Even clients, such as TPS, submit enrollment requests through these forms.) The inputs, then, correspond to fields in the enrollment forms. The outputs correspond to the information contained on the certificate retrieval pages.
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:
- Download and open the profile in the
VIeditor:# pki -c password -n caadmin ca-profile-edit caCMCserverCert
- 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
Important
pkiconsole is being deprecated.
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 .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 tofalseallows 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 . 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 .
- 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.
- To add a policy, click .
- Choose the default from the Default field, choose the constraints associated with that policy in the Constraints field, and click .
- 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.
- 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 . Then edit the default and constraints for that policy.To delete a policy, select the policy, and click . - 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 onlycmcCertReqInputand delete other profiles by selecting them and clicking the button.- To add an input, click .
- Choose the input from the list, and click . See Section A.1, “Input Reference” for complete details of the default inputs.
- The New Certificate Profile Editor window opens. Set the input ID, and click .
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 . - 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.- To add an output, click .
- Choose the output from the list, and click .
- Give a name or identifier for the output, and click .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 . - 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.
- Open the CA's services page.
https://server.example.com:8443/ca/services
- 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.
- Click the name of the certificate profile to approve.
- At the bottom of the page, click the 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 .
- 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.
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. Additional information can also be found at Red Hat Certificate System Planning, Installation, and Deployment Guide.
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,p103.4. Configuring Profiles to Enable Renewal
This section discusses how to set up profiles for certificate renewals. For more information on how to renew certificates, see Section 5.4, “Renewing Certificates”.
A profile that allows renewal is 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. 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.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.
Note
pkiconsole is being deprecated.
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 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”.
Note
pkiconsole is being deprecated.
3.6. Managing CA-Related Profiles
Certificate profiles and extensions must be used to set rules on how subordinate CAs can issue certificates. There are two parts to this:
- Managing the CA signing certificate
- Defining issuance rules
3.6.1. Setting Restrictions on CA Certificates
When a subordinate CA is created, the root CA can impose limits or restrictions on the subordinate CA. For example, the root CA can dictate the maximum depth of valid certification paths (the number of subordinate CAs allowed to be chained below the new CA) by setting the pathLenConstraint field of the Basic Constraints extension in the CA signing certificate.
A certificate chain generally consists of an entity certificate, zero or more intermediate CA certificates, and a root CA certificate. The root CA certificate is either self-signed or signed by an external trusted CA. Once issued, the root CA certificate is loaded into a certificate database as a trusted CA.
An exchange of certificates takes place when performing a TLS handshake, when sending an S/MIME message, or when sending a signed object. As part of the handshake, the sender is expected to send the subject certificate and any intermediate CA certificates needed to link the subject certificate to the trusted root. For certificate chaining to work properly the certificates should have the following properties:
- CA certificates must have the Basic Constraints extension.
- CA certificates must have the keyCertSign bit set in the Key Usage extension.
For more information on certificates and their extensions, see Internet X.509 Public Key Infrastructure - Certificate and Certificate Revocation List (CRL) Profile (RFC 5280), available at RFC 5280.
These extensions can be configured through the certificate profile enrollment pages. By default, the CA contains the required and reasonable configuration settings, but it is possible to customize these settings.
Note
This procedure describes editing the CA certificate profile used by a CA to issue CA certificates to its subordinate CAs.
The profile that is used when a CA instance is first configured is
/var/lib/pki/instance_name/ca/conf/caCert.profile. This profile cannot be edited in pkiconsole (since it is only available before the instance is configured). It is possible to edit the policies for this profile in the template file before the CA is configured using a text editor.
To modify the default in the CA signing certificate profile used by a CA:
- If the profile is currently enabled, it must be disabled before it can be edited. Open the agent services page, select Manage Certificate Profiles from the left navigation menu, select the profile, and click Disable profile.
- Open the CA Console.
pkiconsole https://server.example.com:8443/ca
- In the left navigation tree of the Configuration tab, select Certificate Manager, then Certificate Profiles.
- Select caCACert, or the appropriate CA signing certificate profile, from the right window, and click .
- In the Policies tab of the Certificate Profile Rule Editor, select and edit the Key Usage or Extended Key Usage Extension Default if it exists or add it to the profile.
- Select the Key Usage or Extended Key Usage Extension Constraint, as appropriate, for the default.
- Set the default values for the CA certificates. For more information, see Section B.1.13, “Key Usage Extension Default” and Section B.1.8, “Extended Key Usage Extension Default”.
- Set the constraint values for the CA certificates. There are no constraints to be set for a Key Usage extension; for an Extended Key Usage extension, set the appropriate OID constraints for the CA. For more information, see Section B.1.8, “Extended Key Usage Extension Default”.
- When the changes have been made to the profile, log into the agent services page again, and re-enable the certificate profile.
Note
pkiconsole is being deprecated.
For more information on modifying certificate profiles, see Section 3.2, “Setting up Certificate Profiles”.
3.6.2. Changing the Restrictions for CAs on Issuing Certificates
The restrictions on the certificates issued are set by default after the subsystem is configured. These include:
- Whether certificates can be issued with validity periods longer than the CA signing certificate. The default is to disallow this.
- The signing algorithm used to sign certificates.
- The serial number range the CA is able to use to issue certificates.
Subordinate CAs have constraints for the validity periods, types of certificates, and the types of extensions which they can issue. It is possible for a subordinate CA to issue certificates that violate these constraints, but a client authenticating a certificate that violates those constraints will not accept that certificate. Check the constraints set on the CA signing certificate before changing the issuing rules for a subordinate CA.
To change the certificate issuance rules:
- Open the Certificate System Console.
pkiconsole https://server.example.com:8443/ca
- Select the Certificate Manager item in the left navigation tree of the Configuration tab.
Figure 3.1. The General Settings Tab in non-subordinate CAs by default
- By default, in non-cloned CAs, the General Settings tab of the Certificate Manager menu item contains these options:
- Override validity nesting requirement. This checkbox sets whether the Certificate Manager can issue certificates with validity periods longer than the CA signing certificate validity period.If this checkbox is not selected and the CA receives a request with validity period longer than the CA signing certificate's validity period, it automatically truncates the validity period to end on the day the CA signing certificate expires.
- Certificate Serial Number. These fields display the serial number range for certificates issued by the Certificate Manager. The server assigns the serial number in the Next serial number field to the next certificate it issues and the number in the Ending serial number to the last certificate it issues.The serial number range allows multiple CAs to be deployed and balances the number of certificates each CA issues. The combination of an issuer name and a serial number uniquely identifies a certificate.
Note
The serial number ranges with cloned CAs are fluid. All cloned CAs share a common configuration entry which defines the next available range. When one CA starts running low on available numbers, it checks this configuration entry and claims the next range. The entry is automatically updated, so that the next CA gets a new range.The ranges are defined inbegin*Numberandend*Numberattributes, with separate ranges defined for requests and certificate serial numbers. For example:dbs.beginRequestNumber=1 dbs.beginSerialNumber=1 dbs.enableSerialManagement=true dbs.endRequestNumber=9980000 dbs.endSerialNumber=ffe0000 dbs.ldap=internaldb dbs.newSchemaEntryAdded=true dbs.replicaCloneTransferNumber=5
Serial number management can be enabled for CAs which are not cloned. However, by default, serial number management is disabled unless a system is cloned, when it is automatically enabled.The serial number range cannot be updated manually through the console. The serial number ranges are read-only fields. - Default Signing Algorithm. Specifies the signing algorithm the Certificate Manager uses to sign certificates. The options are
SHA256withRSA, andSHA512withRSA, if the CA's signing key type is RSA.The signing algorithm specified in the certificate profile configuration overrides the algorithm set here.
- By default, in cloned CAs, the General Settings tab of the Certificate Manager menu item contains these options:
- Enable serial number management
- Enable random certificate serial numbers
Select both check boxes.
Figure 3.2. The General Settings Tab in cloned CAs by default
- Click .
Note
pkiconsole is being deprecated.
3.6.3. Using Random Certificate Serial Numbers
Red Hat Certificate System contains a serial number range management for requests, certificates, and replica IDs. This allows the automation of cloning when installing
Identity Management (IdM).
There are these ways to reduce the likelihood of hash-based attacks:
- making part of the certificate serial number unpredictable to the attacker
- adding a randomly chosen component to the identity
- making the validity dates unpredictable to the attacker by skewing each one forwards or backwards
The random certificate serial number assignment method adds a randomly chosen component to the identity. This method:
- works with cloning
- allows resolving conflicts
- is compatible with the current serial number management method
- is compatible with the current workflows for administrators, agents, and end entities
- fixes the existing bugs in sequential serial number management
Note
Administrators must enable random certificate serial numbers.
3.6.3.1. Enabling Random Certificate Serial Numbers
You can enable automatic serial number range management either from the command line or from the console UI.
To enable automatic serial number management from the console UI:
- Tick the Enable serial number management option in the General Settings tab.
Figure 3.3. The General Settings Tab when Random Serial Number Assignment is enabled
- Tick the Enable random certificate serial numbers option.
Note
pkiconsole is being deprecated.
3.6.4. Allowing a CA Certificate to Be Renewed Past the CA's Validity Period
Normally, a certificate cannot be issued with a validity period that ends after the issuing CA certificate's expiration date. If a CA certificate has an expiration date of December 31, 2015, then all of the certificates it issues must expire by or before December 31, 2015.
This rule applies to other CA signing certificates issued by a CA — and this makes renewing a root CA certificate almost impossible. Renewing a CA signing certificate means it would necessarily have to have a validity period past its own expiration date.
This behavior can be altered using the CA Validity Default. This default allows a setting (
bypassCAnotafter) which allows a CA certificate to be issued with a validity period that extends past the issuing CA's expiration (notAfter) date.
Figure 3.4. CA Validity Default Configuration
In real deployments, what this means is that a CA certificate for a root CA can be renewed, when it might otherwise be prevented.
To enable CA certificate renewals past the original CA's validity date:
- Open the
caCACert.cfgfile.vim /var/lib/pki/instance_name/ca/conf/caCACert.cfg
- The CA Validity Default should be present by default. Set the value to
trueto allow a CA certificate to be renewed past the issuing CA's validity period.policyset.caCertSet.2.default.name=CA Certificate Validity Default policyset.caCertSet.2.default.params.range=2922 policyset.caCertSet.2.default.params.startTime=0
policyset.caCertSet.2.default.params.bypassCAnotafter=true - Restart the CA to apply the changes.
When an agent reviews a renewal request, there is an option in the Extensions/Fields area that allows the agent to choose to bypass the normal validity period constraint. If the agent selects
false, the constraint is enforced, even if bypassCAnotafter=true is set in the profile. If the agent selects true when the bypassCAnotafter value is not enabled, then the renewal request is rejected by the CA.
Figure 3.5. Bypass CA Constraints Option in the Agent Services Page
Note
The CA Validity Default only applies to CA signing certificate renewals. Other certificates must still be issued and renewed within the CA's validity period.
A separate configuration setting for the CA,
ca.enablePastCATime, can be used to allow certificates to be renewed past the CA's validity period. However, this applies to every certificate issued by that CA. Because of the potential security issues, this setting is not recommended for production environments.
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
patternconfiguration 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.27, “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.23, “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.- Open the CA Console.
pkiconsole https://server.example.com:8443/ca
- Select Authentication in the left navigation tree.
- In the Authentication Instance tab, click , and add an instance of the
SharedSecretauthentication plug-in. - 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
- Save the new plug-in instance.
Note
pkiconsoleis being deprecated.For information on setting a CMC shared token, see Section 10.4.2, “Setting a CMC Shared Secret”. - The
ldapStringAttributesparameter instructs the authentication plug-in to read the value of themailattribute 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 thednpatternparameter is covered in Section B.2.11, “Subject Name Constraint” and Section B.1.27, “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
mailattribute value in the Subject Alternative Name extension in thecaFullCMCSharedTokenCertprofile, 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.
| 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.requestor_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 SubjectThe previous example uses12as the set number. - Append the new policy set number to the
policyset.userCertSet.listparameter. 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.32, “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.5.2, “The CMC Enrollment Process” to complete the CMC enrollment.
Chapter 4. Setting up Key Archival and Recovery
For more information on Key Archival and Recovery, see the Archiving, Recovering, and Rotating Keys section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
This chapter explains how to setup the Key Recovery Authority (KRA), previously known as Data Recovery Manager (DRM), to archive private keys and to recover archived keys for restoring encrypted data.
Note
This chapter only discusses archiving keys through client-side key generation. Server-side key generation and archivals, whether it's initiated through TPS, or through CA's End Entity portal, are not discussed here.
For information on smart card key recovery, see Section 6.11, “Setting Up Server-side Key Generation”.
For information on server-side key generation provided at the CA’s EE portal, see Section 5.2.2, “Generating CSRs Using Server-Side Key Generation”.
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.
When KRA is installed, it joins a security domain, and is paired up with the CA. At such time, it is configured to archive and recover private encryption keys. However, if the KRA certificates are issued by an external CA rather than one of the CAs within the security domain, then the key archival and recovery process must be set up manually.
For more information, see the Manually Setting up Key Archival section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
Note
In a cloned environment, it is necessary to set up key archival and recovery manually. For more information, see the Updating CA-KRA Connector Information After Cloning section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
4.1. Configuring Agent-Approved Key Recovery in the Console
Note
While the number of key recovery agents can be configured in the Console, the group to use can only be set directly in the
CS.cfg file. The Console uses the Key Recovery Authority Agents Group by default.
- Open the KRA's console. For example:
pkiconsole https://server.example.com:8443/kra
- Click the Key Recovery Authority link in the left navigation tree.
- Enter the number of agents to use to approve key recover in the Required Number of Agents field.
Note
For more information on how to configure agent-approved key recovery in the
CS.cfg file, see the Configuring Agent-Approved Key Recovery in the Command Line section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
4.2. Testing the Key Archival and Recovery Setup
Note
Newer browsers do not support key archival from the browser; for Step 1, one should substitute CRMF generation clients for those browsers.
To test whether a key can be successfully archived:
- Enroll for dual certificates using the CA's Manual User Signing & Encryption Certificates Enrollment form.
- Submit the request. Log in to the agent services page, and approve the request.
- Log into the end-entities page, and check to see if the certificates have been issued. In the list of certificates, there should be two new certificates with consecutive serial numbers.
- Import the certificates into the web browser.
- 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:
- 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.
- Click .
- 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.
- Make sure that the Async Recovery checkbox is selected to allow the browser session to be closed while recovery is ongoing.
Note
An async recovery is the default and recommended way to perform a key recovery. If you want to perform a synchronous key recovery, the browser window cannot be shut and the KRA cannot be stopped during the recovery process. - 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.
- Once all the agents have authorized the recovery, the next screen requests a password to encrypt the PKCS #12 file with the certificate.
- 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 thegcr-viewerutility can fail in certain situations. To work around the problem, download the file and manually open it ingcr-viewer.
- Restore the key to the browser's database. Import the
.p12file 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 (described in Chapter 10, Authentication for Enrolling Certificates) 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 17, 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 certificate request (CSR) is generated.
- 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 requesting party retrieves the new certificate.
When the certificate reaches the end of its validity period, it can be renewed.
5.2. Creating Certificate Signing Requests
Traditionally, the following methods are used to generate Certificate requests (CSRs):
- Generating CSRs using command line utilities
- Generating CSRs inside a supporting browser
- Generating CSRs inside an application, such as the installer of a server
Some of these methods support direct submission of the CSRs, while some do not.
Starting from RHCS 9.7, Server-Side key generation is supported to overcome the inconvenience brought on by the removal of the key generation support inside newer versions of browsers, such as Firefox v69 and up, as well as Chrome. For this reason, in this section, we will not discuss browser support for key generation. Although there is no reason to believe that older versions of those browsers should not continue to function as specified in older RHCS documentation.
CSRs generated from an application generally take the form of PKCS#10. Provided that they are generated correctly, they should be supported by RHCS.
In the following subsections, we are going to go over the following methods supported by RHCS:
- Command-line utilities
- Server-Side Key Generation
5.2.1. Generating CSRs Using Command-Line Utilities
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.pki client-cert-request: Supports both PKCS#10 and CRMF requests.
The following sections provide some examples on how to use these utilities with the feature-rich enrollment profile framework.
5.2.1.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 --helpcommand
5.2.1.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.csrfile:$ 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.
5.2.1.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.csrfile:$ 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.
5.2.1.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 --helpcommand
5.2.1.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.csrfile:$ 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.1.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.csrfile:$ 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.1.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.1.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.csrfile:$ 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 falseoptions 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.1.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.csrfile:$ 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 falseoptions to the command.For further details about the parameters, see the output of theCRMFPopClient --helpcommand. - Optionally, verify that the CSR is correct:
$ cat /user_or_entity_database_directory/example.csr -----BEGIN CERTIFICATE REQUEST----- MIICzzCCAbcCAQAwgYkx ... -----END CERTIFICATE REQUEST-----
5.2.1.4. Creating a CSR using client-cert-request in the PKI CLI
The
pkicommand-line tool can also be used with the client-cert-request command to generate a CSR. However, unlike the previously discussed tools, CSR generated with pki are submitted directly to the CA. Both PKCS#10 or CRMF requests can be generated.
Example on generating a PKCS#10 request:
pki -d user token db directory -P https -p 8443 -h host.test.com -c user token db passwd client-cert-request "uid=test2" --length 4096 --type pkcs10
Example on generating a CRMF request:
pki -d user token db directory -P https -p 8443 -h host.test.com -c user token db passwd client-cert-request "uid=test2" --length 4096 --type crmf
A request id will be returned upon success.
Once a request is submitted, an agent could approve it by using the pki
ca-cert-request-approve command.
For example:
pki -d agent token db directory -P https -p 8443 -h host.test.com -c agent token db passwd -n <CA agent cert nickname> ca-cert-request-approve request id
For more information, see the man page by running the
pki client-cert-request --help command.
5.2.2. Generating CSRs Using Server-Side Key Generation
Many newer versions of browsers, including Firefox v69 and up, as well as Chrome, have removed the functionality to generate PKI keys and the support for CRMF for key archival. On RHEL, CLIs such as
CRMFPopClient (see CRMFPopClient --help) or pki (see pki client-cert-request --help) could be used as a workaround.
Server-Side Keygen enrollment has been around for a long time since the introduction of Token Key Management System (TMS), where keys could be generated on a KRA instead of locally on smart cards. Red Hat Certificate System now adopts a similar mechanism to resolve the browser keygen deficiency issue. Keys are generated on the server (specifically, on the KRA) and then transferred securely back to the client in PKCS#12.
Note
It is highly recommended to employ the Server-Side Keygen mechanism only for encryption certificates.
5.2.2.1. Functionality Highlights
- Certificate request keys are generated on the KRA (Note: a KRA must be installed to work with the CA)
- The profile default plugin,
serverKeygenUserKeyDefaultImpl, provides selection to enable or disable key archival (i.e. the enableArchival parameter) - Support for both RSA and EC keys
- Support for both manual (agent) approval and automatic approval (e.g. directory password-based)
5.2.2.2. Enrolling a Certificate Using Server-Side Keygen
The default Sever-Side Keygen enrollment profile can be found on the EE page, under the List Certificate Profiles tab:
Manual User Dual-Use Certificate Enrollment Using server-side Key generation
Figure 5.1. Server-Side Keygen Enrollment that requires agent manual approval
Directory-authenticated User Dual-Use Certificate Enrollment Using server-side Key generation
Figure 5.2. Server-Side Keygen Enrollment that will be automatically approved upon successful LDAP uid/pwd authentication
Regardless of how the request is approved, the Server-Side Keygen Enrollment mechanism requires the End Entity user to enter a password for the PKCS#12 package which will contain the issued certificate as well as the encrypted private key generated by the server once issued.
Important
Users should not share their passwords with anyone. Not even the CA or KRA agents.
When the enrollment request is approved, the PKCS#12 package will be generated and,
- In case of manual approval, the PKCS#12 file will be returned to the CA agent that approves the request; the agent is then expected to forward the PKCS#12 file to the user.
- In case of automatic approval, the PKCS#12 file will be returned to the user who submitted the request
Figure 5.3. Enrollment manually approved by an agent
Once the PKCS#12 file is received, the user could use a CLI such as
pkcs12util to import this file into their own user internal cert/key database for each application. E.g. the Firefox nss database of the user.
5.2.2.3. Key Recovery
If the enableArchival parameter is set to true in the certificate enrollment profile, then the private keys are archived at the time of Server-Side Keygen enrollment. The archived private keys could then be recovered by the authorized KRA agents.
5.2.2.4. Additional Information
5.2.2.4.1. KRA Request Records
Note
Due to the nature of this mechanism, in case the enableArchival parameter is set to true in the profile, there are two KRA requests records per Server-Side keygen request:
- One for the request type asymkeyGenRequestThis request type cannot be filtered using List Requests on the KRA agent page; you can select Show All Requests to see them listed.
- One for the request type recovery
5.2.2.4.2. Audit Records
Some audit records could be observed if enabled:
CA
- SERVER_SIDE_KEYGEN_ENROLL_KEYGEN_REQUEST
- SERVER_SIDE_KEYGEN_ENROLL_KEY_RETRIEVAL_REQUEST
KRA
- SERVER_SIDE_KEYGEN_ENROLL_KEYGEN_REQUEST_PROCESSED
- SERVER_SIDE_KEYGEN_ENROLL_KEY_RETRIEVAL_REQUEST_PROCESSED (not yet implemented)
5.3. Requesting and Receiving Certificates
As explained in Section 5.1, “About Enrolling and Renewing Certificates”, once CSRs are generated, they need to be submitted to the CA for issuance. Some of the methods discussed in Section 5.2, “Creating Certificate Signing Requests” submit CSRs to the CA directly, while some would require submission of the CSRs in a separate step, which could either be carried out by the user or pre-signed by an agent.
In this section, we are going to discuss the separate submission steps supported by the RHCS CA.
5.3.1. Requesting and Receiving a Certificate through the End-Entities Page
At the CA End Entity portal (i.e. https://host.domain:port#/ca/ee/ca), end entities can use the HTML enrollment forms presented at each applicable enrollment profile under the Enrollment/Renewal tab to submit their certificate requests (CSRs, see Section 5.2, “Creating Certificate Signing Requests” for how to generate CSRs).
This section assumes that you have the CSR in Base64 encoded format, including the marker lines -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST----- .
Many of the default enrollment profiles provide a Certificate Request text box where one could paste in the Base64 encoded CSR, along with a Certificate Request Type selection drop down list.
In the certificate enrollment form, enter the required information.
The standard requirements are as follows:
- Certificate Request Type. This is either PKCS#10 or CRMF. Certificate requests created through the subsystem administrative console are PKCS #10; those created through the
certutiltool and other utilities are usually PKCS #10. - Certificate Request. Paste the base-64 encoded blob, including the
-----BEGIN NEW CERTIFICATE REQUEST-----and-----END NEW CERTIFICATE REQUEST-----marker lines. - Requester Name. This is the common name of the person requesting the certificate.
- Requester Email. This is the email address of the requester. The agent or CA system will use this address to contact the requester when the certificate is issued. For example,
jdoe@someCompany.com. - Requester Phone. This is the contact phone number of the requester.
The submitted request is queued for agent approval. An agent needs to process and approve the certificate request.
Note
Some enrollment profiles may allow automatic approval such as by using the LDAP uid/pwd authentication method offered by Red Hat Certificate System. Enrollments through those profiles would not require manual agent approval in the next section. See Chapter 10, Authentication for Enrolling Certificates for supported approval methods.
In case of manual approval, once the certificate is approved and generated, you can retrieve the certificate.
- Open the Certificate Manager end-entities page, for example:
http
s://server.example.com:8443/ca/ee/ca - Click the Retrieval tab.
- Fill in the request ID number that was created when the certificate request was submitted, and click .
- The next page shows the status of the certificate request. If the status is
complete, then there is a link to the certificate. Click the Issued certificate link.
- The new certificate information is shown in pretty-print format, in base-64 encoded format, and in PKCS #7 format.
The following actions can be taken through this page:- To install this certificate on a server or other application, scroll down to the Installing This Certificate in a Server section, which contains the base-64 encoded certificate.
- Copy the base-64 encoded certificate, including the
-----BEGIN CERTIFICATE-----and-----END CERTIFICATE-----marker lines, to a text file. Save the text file, and use it to store a copy of the certificate in the security module of the entity where the private key resides. See Section 15.3.2.1, “Creating Users”.
5.4. Renewing Certificates
This section discusses how to renew certificates. For more information on how to set up certificate renewal, see Section 3.4, “Configuring Profiles to Enable Renewal”.
Renewing a certificate consists in regenerating the certificate with the same properties to be used for the same purpose as the original certificate. In general, there are two types of renewals:
- Same key Renewal 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. This can be done by either of the following methods:
- resubmitting the original certificate request (CSR) through the original profile, or
- regenerating a CSR with the original keys by using supporting tools such as certutil
- Re-keying a certificate requires regeneration of a certificate request with the same information, so that a new key pair is generated. The CSR is then submitted through the original profile.
5.4.1. Same Keys Renewal
5.4.1.1. Reusing CSR
There are three approval methods for same key renewal at the end entity portal.
- Agent-approved method requires submitting the serial number of the certificate to be renewed; This method would require a CA agent’s approval.
- Directory-based renewal requires submitting the serial number of the certificate to be renewed, and the CA draws the information from its current certificate directory entry. The certificate is automatically approved if the ldap uid/pwd is authenticated successfully.
- Certificate-based renewal uses the certificate in the browser database to authenticate and have the same certificate re-issued.
5.4.1.1.1. Agent-Approved or Directory-Based Renewals
Sometimes, a certificate renewal request has to be manually approved, either by a CA agent or by providing login information for the user directory.
- Open the end-entities services page for the CA which issued the certificate (or its clone).
http
s://server.example.com:8443/ca/ee/ca - Click the name of the renewal form to use.
- Enter the serial number of the certificate to renew. This can be in decimal or hexadecimal form.
- Click the renew button.
- The request is submitted. For directory-based renewals, the renewed certificate is automatically returned. Otherwise, the renewal request will be approved by an agent.
5.4.1.1.2. Certificate-Based Renewal
Some user certificates are stored directly in your browser, so some renewal forms will simply check your browser certificate database for a certificate to renew. If a certificate can be renewed, then the CA automatically approved and reissued it.
Important
If the certificate which is being renewed has already expired, then it probably cannot be used for certificate-based renewal. The browser client may disallow any SSL client authentication with an expired certificate.
In that case, the certificate must be renewed using one of the other renewal methods.
- Open the end-entities services page for the CA which issued the certificate (or its clone).
http
s://server.example.com:8443/ca/ee/ca - Click the name of the renewal form to use.
- There is no input field, so click the button.
- When prompted, select the certificate to renew.
- The request is submitted and the renewed certificate is automatically returned.
5.4.1.2. Renewal by generating CSR with same keys
Sometimes, the original CSR might not be available. The
certutil tool allows one to regenerate a CSR with the same keys, provided that the key pair is in the NSS database. This can be achieved by doing the following:
- Find the corresponding key id in the NSS db:
Certutil -d <nssdb dir> -K
- Generate a CSR using a specific key:
Certutil -d <nssdb dir> -R -k <key id> -s <subject DN> -o <CSR output file>
Alternatively, instead of keyid, if a key is associated with a certificate in the NSS db, nickname could be used:
- Generate a CSR using an existing nickname:
Certutil -d <nssdb dir> -R -k <nickname> -s <subject DN> -o <CSR output file>
5.4.2. Renewal by Re-keying Certificates
Since renewal by re-keying is basically generating a new CSR with the same info as the old certificate, just follow any one of the methods described in Section 5.2, “Creating Certificate Signing Requests”. Be mindful to enter the same information as the old certificate.
5.5. Submitting Certificate requests 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.
- The Enrolling with CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
- CMCRequest(1) man page
- CMCResponse(1) man page
CMC enrollment is possible in various ways to meet the requirements for different scenarios. Section 5.5.2, “The CMC Enrollment Process” supplements the Enrolling with CMC section in the Red Hat Certificate System Planning, Installation, and Deployment Guide with more details. Additionally, the Section 5.5.3, “Practical CMC Enrollment Scenarios” section enables administrators to decide which mechanisms should be used in which scenario.
5.5.1. Using CMC Enrollment
CMC enrollment allows an enrollment client to use a CMCAuth plug-in for authentication, by which the certificate request is pre-signed with an agent certificate. The Certificate Manager automatically issues certificates when a valid request signed with the agent certificate is received.
Note
CMC enrollments are enabled by default. It should not be necessary to enable the CMC enrollment authentication plug-ins or profiles unless the configuration has been changed.
The CMCAuth authentication plug-in also provides CMC revocation for the client. CMC revocation allows the client to have the certificate request signed by the agent certificate, and then send such a request to the Certificate Manager. The Certificate Manager automatically revokes certificates when a valid request signed with the agent certificate is received. CMC revocation can be created with the
CMCRevoke command line tool. For more information about CMCRevoke, see Section 7.2, “Performing a CMC Revocation”.
A CMC request can be submitted through browser end-entities forms or using a tool such as
HttpClient to post the request to the appropriate profile. The CMCRequest tool generates a signed certificate request which can then be submitted using the HttpClient tool or the browser end-entities forms to enroll and receive the certificate automatically and immediately.
The
CMCRequest tool has a simple command syntax, with all the configuration given in the .cfg input file:
CMCRequest /path/to/file.cfg
A single CMC enrollment can also be created using the
CMCEnroll tool, with the following syntax:
CMCEnroll -d /agent's/certificate/directory -h password -n cert_nickname -r certrequest.file -p certDB_passwd [-c "comment"]
These tools are described in more detail in the
CMCEnroll(1) man page.
Note
Surround values that include spaces in quotation marks.
5.5.1.1. Testing CMCEnroll
- Create a certificate request using the
certutiltool. - Copy the PKCS #10 ASCII output to a text file.
- Run the CMCEnroll utility.For example, if the input file called
request34.txt, the agent certificate is stored in the browser databases, the certificate common name of the agent certificate isCertificateManagerAgentsCert, and the password for the certificate database issecret, the command is as follows:CMCEnroll -d ~jsmith/.mozilla/firefox/1234.jsmith -n "CertificateManagerAgentsCert" -r /export/requests/request34.txt -p secret
The output of this command is stored in a file with the same filename with.outappended to the filename. - Submit the signed certificate through the end-entities page.
- Open the end-entities page.
http
s://server.example.com:8443/ca/ee/ca - Select the CMC enrollment form from the list of certificate profiles.
- Paste the content of the output file into the Certificate Request text area of this form.
- Remove
-----BEGIN NEW CERTIFICATE REQUEST-----and----END NEW CERTIFICATE REQUEST-----from the pasted content. - Fill in the contact information, and submit the form.
- The certificate is immediately processed and returned.
- Use the agent page to search for the new certificate.
5.5.2. 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
.p12file:$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 Managing Certificate/Key Crypto Token section in the Red Hat Certificate System Planning, Installation, and Deployment Guide:
$PKICertImport -d . -n "CA Admin - Client Certificate" -t ",," -a -i /root/.dogtag/instance/ca_admin_cert.crt -u CImportant
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, theCMCRequestutility stored the CMC request in the file specified in theoutputparameter 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 thenicknameparameter 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 theCMCAuthauthentication plug-in. Whereas in user-initiated enrollments, the profile must use theCMCUserSignedAuthplug-in. For further details, see the Section 10.3, “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
-iparameter of theCMCResponseutility. For example:$ CMCResponse -i /home/user_name/cmc-response.bin -o /home/user_name/cert_chain.crt
5.5.3. 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.5.2, “The CMC Enrollment Process”.
5.5.3.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.5.2, “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 10.3, “CMC Authentication Plug-ins”, or, alternatively, create a custom profile that uses the
CMCAuthauthentication mechanism. - CMC Signing Certificate
- For system certificates, the CA agent must generate and sign the CMC request. For this, set the
nicknameparameter in theCMCRequestconfiguration file to the nickname of the CA agent.Note
The CA agent must have access to its own private key. HttpClientTLS Client Nickname- Use the same certificate for signing in the
CMCRequestutility's configuration file as for TLS client authentication in the configuration file forHttpClient. HttpClientservletParameter- The
servletin the configuration file passed to theHttpClientutility 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
PopLinkWittnessV2feature must be disabled because the identification is checked by the agent.
5.5.3.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.5.3.2.1, “Signing a CMC Request with an Agent Certificate”.
- Certificate enrollment is authenticated by using a Shared Secret. See Section 5.5.3.2.2, “Authenticating for Certificate Enrollment Using a Shared Secret”.
5.5.3.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.5.3.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.5.3.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.5.3.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
EncryptedPOPcontrol. The user then uses the response and generates a CMC request that contains theDecryptedPOPcontrol and submits it in the second step.- For the first step, in addition to the default parameters, the user must set the following parameters in the configuration file passed to the
CMCRequestutility:identification.enablewitness.sharedSecretidentityProofV2.enableidentityProofV2.hashAlgidentityProofV2.macAlgpopLinkWitnessV2.enableif required by the CApopLinkWitnessV2.keyGenAlgif required by the CApopLinkWitnessV2.macAlgif required by the CArequest.privKeyId
For details, see the CMCRequest(1) man page.The response contains:- A CMC encrypted POP control
- The
CMCStatusInfoV2control with thePOP requirederror - The request ID
- For the second step, in addition to the default parameters, the user must set the following parameters in the configuration file passed to the
CMCRequestutility:decryptedPop.enableencryptedPopResponseFiledecryptedPopRequestFilerequest.privKeyId
For details, see the CMCRequest(1) man page.
5.5.3.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.1.3.1, “Using CRMFPopClient to Create a CSR with Key Archival” and Section 5.2.1.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.certfile:$ pki cert-show 12345 --output /home/user_name/kra.cert
- Use the
CRMFPopClientutility to:- Create a CSR with key archival:
- Change to the certificate database directory of the user or entity for which the certificate is being requested, for example:
$ cd /home/user_name/
- Use the
CRMFPopClientutility 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.reqfile:$ 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 therequest.privKeyIdparameter in the configuration file for the second trip.
- Create a configuration file for the
CRMRequestutility, such as/home/user_name/cmc.cfgwith 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 cert9.db, key4.db and pkcs11.txt dbdir=/home/user_name/.dogtag/nssdb/ #password: password for cert9.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, theCMCRequestutility stored the CMC request in the file specified in theoutputparameter 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:#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 cert9.db, key4.db and pkcs11.txt #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 cert9.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, theHTTPClientutility stored the CMC response in the file specified in theoutputparameter in the configuration file. - Verify the response by passing the response file to the
CMCResponseutility. For example:$ CMCResponse -d /home/user_name/.dogtag/nssdb/ -i /home/user_name/cmc-response_round_1.bin
If the first trip was successful,CMCResponsedisplays 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 cert9.db, key4.db and pkcs11.txt dbdir=/home/user_name/.dogtag/nssdb/ #password: password for cert9.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
DecryptPOPCMC request:$ CMCRequest /home/user_name/cmc.DecryptedPOP.cfg
If the command succeeds, theCMCRequestutility stored the CMC request in the file specified in thedecryptedPopRequestFileparameter 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 theDecryptedPOPCMC 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 cert9.db, key4.db and pkcs11.txt #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 cert9.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
DecryptedPOPCMC request to the CA:$ HttpClient /home/user_name/decrypted_POP_cmc-submit.cfg
If the command succeeds, theHTTPClientutility stored the CMC response in the file specified in theoutputparameter in the configuration file. - To convert the CMC response to a PKCS #7 certificate chain, pass the CMC response file to the
-iparameter of theCMCResponseutility. 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-vto the utility.If the second trip was successful,CMCResponsedisplays 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.6. Performing Bulk Issuance
There can be instances when an administrator needs to submit and generate a large number of certificates simultaneously. A combination of tools supplied with Certificate System can be used to post a file containing certificate requests to the CA. This example procedure uses the
PKCS10Client command to generate the requests and the sslget command to send the requests to the CA.
- Since this process is scripted, multiple variables need to be set to identify the CA (host, port) and the items used for authentication (the agent certificate and certificate database and password). For example, set these variables for the session by exporting them in the terminal:
export d=/var/tmp/testDir export p=password export f=/var/tmp/server.csr.txt export nick="CA agent cert" export cahost=1.2.3.4 export caport=8443
Note
The local system must have a valid security database with an agent's certificate in it. To set up the databases:- Export or download the agent user certificate and keys from the browser and save to a file, such as
agent.p12. - If necessary, create a new directory for the security databases.
mkdir ${d} - If necessary, create new security databases.
certutil -N -d ${d} - Stop the Certificate System instance.
pki-server stop instance_name
- Use
pk12utilto import the certificates.# pk12util -i /tmp/agent.p12 -d ${d} -W p12filepasswordIf the procedure is successful, the command prints the following output:pk12util: PKCS12 IMPORT SUCCESSFUL
- Start the Certificate System instance.
pki-server start instance_name
- Two additional variables must be set. A variable that identify the CA profile to be used to process the requests, and a variable that is used to send a post statement to supply the information for the profile form.
export post="cert_request_type=pkcs10&xmlOutput=true&profileId=caAgentServerCert&cert_request=" export url="/ca/ee/ca/profileSubmitSSLClient"
Note
This example submits the certificate requests to thecaAgentServerCertprofile (identified in theprofileIdelement of thepoststatement. Any certificate profile can be used, including custom profiles. - Test the variable configuration.
echo ${d} ${p} ${f} ${nick} ${cahost} ${caport} ${post} ${url} - Generate the certificate requests using (for this example)
PKCS10Client:time for i in {1..10}; do /usr/bin/PKCS10Client -d ${d} -p ${p} -o ${f}.${i} -s "cn=testms${i}.example.com"; cat ${f}.${i} >> ${f}; done perl -pi -e 's/\r\n//;s/\+/%2B/g;s/\//%2F/g' ${f} wc -l ${f} - Submit the bulk certificate request file created in step 4 to the CA profile interface using
sslget. For example:cat ${f} | while read thisreq; do /usr/bin/sslget -n "${nick}" -p ${p} -d ${d} -e ${post}${thisreq} -v -r ${url} ${cahost}:${caport}; done
5.7. Enrolling a Certificate on a Cisco Router
Simple Certificate Enrollment Protocol (SCEP), designed by Cisco, is a way for a router to communicate a certificate issuing authority, such as a CA, to enroll certificates for the router.
Normally, a router installer enters the CA's URL and a challenge password (also called a one-time PIN) into the router and issues a command to initiate the enrollment. The router then communicates with the CA over SCEP to generate, request, and retrieve the certificate. The router can also check the status of a pending request using SCEP.
5.7.1. Enabling SCEP Enrollments
For security reasons, SCEP enrollments are disabled by default in the CA. To allow routers to be enrolled, SCEP enrollments must be manually enabled for the CA.
- Stop the CA server, so that you can edit the configuration files.
pki-server stop instance_name
- Open the CA's
CS.cfgfile.vim
/var/lib/pki/instance_name/ca/conf/CS.cfg - Set the
ca.scep.enableto true. If the parameter is not present, then add a line with the parameter.ca.scep.enable=true
- Restart the CA server.
pki-server start instance_name
5.7.2. Configuring Security Settings for SCEP
Several different parameters allow administrators to set specific security requirements for SCEP connections, such as not using the same certificate for enrollment authentication and regular certificate enrollments, or setting allowed encryption algorithms to prevent downgrading the connection strength. These parameters are listed in Table 5.1, “Configuration Parameters for SCEP Security”.
| Parameter | Description |
|---|---|
| ca.scep.encryptionAlgorithm | Sets the default or preferred encryption algorithm. |
| ca.scep.allowedEncryptionAlgorithms | Sets a comma-separated list of allowed encryption algorithms. |
| ca.scep.hashAlgorithm | Sets the default or preferred hash algorithm. |
| ca.scep.allowedHashAlgorithms | Sets a comma-separated list of allowed hash algorithms. |
| ca.scep.nickname | Gives the nickname of the certificate to use for SCEP communication. The default is to use the CA's key pair and certificate unless this parameter is set. |
| ca.scep.nonceSizeLimit | Sets the maximum nonce size, in bytes, allowed for SCEP requests. The default is 16 bytes. |
To set security settings for connections for SCEP enrollments:
- Stop the CA server, so that you can edit the configuration files.
pki-server stop instance_name
- Open the CA's
CS.cfgfile.vim
/var/lib/pki/instance_name/ca/conf/CS.cfg - Set the desired security parameters, as listed in Table 5.1, “Configuration Parameters for SCEP Security”. If the parameter is not already present, then add it to the
CS.cfgfile.ca.scep.encryptionAlgorithm=DES3 ca.scep.allowedEncryptionAlgorithms=DES3 ca.scep.hashAlgorithm=SHA1 ca.scep.allowedHashAlgorithms=SHA1,SHA256,SHA512 ca.scep.nickname=Server-Cert ca.scep.nonceSizeLimit=20
- Restart the CA server.
pki-server start instance_name
5.7.3. Configuring a Router for SCEP Enrollment
Note
Not all versions of router IOS have the relevant crypto features. Make sure that the firmware image has the Certification Authority Interoperability feature. Certificate System SCEP support was tested on a Cisco 2611 router running IOS C2600 Software (C2600-JK9S-M), version 12.2(40), RELEASE SOFTWARE (fc1).
Before enrolling SCEP certificates on the router, make sure that the router is appropriately configured:
- The router must be configured with an IP address, DNS server, and routing information.
- The router's date/time must be correct.
- The router's hostname and dnsname must be configured.
See the router documentation for instructions on configuring the router hardware.
5.7.4. Generating the SCEP Certificate for a Router
The following procedure details how to generate the SCEP certificate for a router.
- Pick a random PIN.
- Add the PIN and the router's ID to the
flatfile.txtfile so that the router can authenticate directly against the CA. For example:vim /var/lib/pki/instance_name/ca/conf/flatfile.txt UID:172.16.24.238 PWD:Uojs93wkfd0IS
Be sure to insert an empty line after thePWDline.The router's IP address can be an IPv4 address or an IPv6 address.Using flat file authentication is described in Section 10.2.4, “Configuring Flat File Authentication”. - Log into the router's console. For this example, the router's name is
scep:scep>
- Enable privileged commands.
scep> enable
- Enter configuration mode.
scep# conf t
- Import the CA certificate for every CA in the certificate chain, starting with the root. For example, the following command sequence imports two CA certificates in the chain into the router:
scep(config)# crypto ca trusted-root1 scep(ca-root)# root CEP http://server.example.com:8080/ca/cgi-bin/pkiclient.exe scep(ca-root)# crl optional scep(ca-root)# exit scep(config)# cry ca authenticate 1 scep(config)# crypto ca trusted-root0 scep(ca-root)# root CEP http://server.example.com:8080/ca/cgi-bin/pkiclient.exe scep(ca-root)# crl optional scep(ca-root)# exit scep(config)# cry ca authenticate 0
- Set up a CA identity, and enter the URL to access the SCEP enrollment profile. For example, for the CA:
scep(config)# crypto ca identity CA scep(ca-identity)# enrollment url http://server.example.com:8080/ca/cgi-bin scep(ca-identity)# crl optional
- Get the CA's certificate.
scep(config)# crypto ca authenticate CA Certificate has the following attributes: Fingerprint: 145E3825 31998BA7 F001EA9A B4001F57 % Do you accept this certificate? [yes/no]: yes
- Generate RSA key pair.
scep(config)# crypto key generate rsa The name for the keys will be: scep.server.example.com Choose the size of the key modulus in the range of 360 to 2048 for your General Purpose Keys. Choosing a key modulus greater than 512 may take a few minutes. How many bits in the modulus [512]: Generating RSA keys ... [OK]
- Lastly, generate the certificate on the router.
scep(config)# crypto ca enroll CA % % Start certificate enrollment .. % Create a challenge password. You will need to verbally provide this password to the CA Administrator in order to revoke your certificate. For security reasons your password will not be saved in the configuration. Please make a note of it. Password: secret Re-enter password: secret % The subject name in the certificate will be: scep.server.example.com % Include the router serial number in the subject name? [yes/no]: yes % The serial number in the certificate will be: 57DE391C % Include an IP address in the subject name? [yes/no]: yes % Interface: Ethernet0/0 % Request certificate from CA? [yes/no]: yes % Certificate request sent to Certificate Authority % The certificate request fingerprint will be displayed. % The 'show crypto ca certificate' command will also show the fingerprint. % Fingerprint:D89DB555 E64CC2F7 123725B4 3DBDF263 Jan 12 13:41:17.348: %CRYPTO-6-CERTRET: Certificate received from Certificate
- Close configuration mode.
scep(config)# exit
- To make sure that the router was properly enrolled, list all of the certificates stored on the router.
scep# show crypto ca certificates Certificate Status: Available Certificate Serial Number: 0C Key Usage: General Purpose Issuer: CN = Certificate Authority O = Sfbay Red hat Domain 20070111d12 Subject Name Contains: Name: scep.server.example.com IP Address: 10.14.1.94 Serial Number: 57DE391C Validity Date: start date: 21:42:40 UTC Jan 12 2007 end date: 21:49:50 UTC Dec 31 2008 Associated Identity: CA CA Certificate Status: Available Certificate Serial Number: 01 Key Usage: Signature Issuer: CN = Certificate Authority O = Sfbay Red hat Domain 20070111d12 Subject: CN = Certificate Authority O = Sfbay Red hat Domain 20070111d12 Validity Date: start date: 21:49:50 UTC Jan 11 2007 end date: 21:49:50 UTC Dec 31 2008 Associated Identity: CA
5.7.5. Working with Subordinate CAs
Before a router can authenticate to a CA, every CA certificate in the CA's certificate chain must be imported into the router, starting with the root. For example, the following command sequence imports two CA certificates in the chain into the router:
scep(config)# crypto ca trusted-root1 scep(ca-root)# root CEP http://server.example.com:8080/ca/cgi-bin/pkiclient.exe scep(ca-root)# crl optional scep(ca-root)# exit scep(config)# cry ca authenticate 1 scep(config)# crypto ca trusted-root0 scep(ca-root)# root CEP http://server.example.com:8080/ca/cgi-bin/pkiclient.exe scep(ca-root)# crl optional scep(ca-root)# exit scep(config)# cry ca authenticate 0
If the CA certificates do not have the CRL distribution point extension set, turn off the CRL requirement by setting it to
optional:
scep(ca-root)# crl optional
After that, set up the CA identity as described in Section 5.7.4, “Generating the SCEP Certificate for a Router”.
5.7.6. Re-enrolling a Router
Before a router can be re-enrolled with new certificates, the existing configuration has to be removed.
- Remove (zeroize) the existing keys.
scep(config)# crypto key zeroize rsa % Keys to be removed are named scep.server.example.com. Do you really want to remove these keys? [yes/no]: yes
- Remove the CA identity.
scep(config)# no crypto ca identity CA % Removing an identity will destroy all certificates received from the related Certificate Authority. Are you sure you want to do this? [yes/no]: yes % Be sure to ask the CA administrator to revoke your certificates. No enrollment sessions are currently active.
5.7.7. Enabling Debugging
The router provides additional debugging during SCEP operations by enabling the debug statements.
scep# debug crypto pki callbacksCrypto PKI callbacks debugging is onscep# debug crypto pki messagesCrypto PKI Msg debugging is onscep# debug crypto pki transactionsCrypto PKI Trans debugging is onscep#debug crypto verboseverbose debug output debugging is on
5.7.8. Issuing ECC Certificates with SCEP
By default, an ECC CA does not support SCEP out of box. However, it is possible to work around it by using a designated RSA certificate to handle each of the following two areas:
- encryption/decryption cert - designate an RSA cert having encryption/decryption capability; (scepRSAcert in the following example)
- signature cert - get an RSA cert to use on the client side for signing purpose instead of self-signed; (signingCert cert in the following example)
For example, with scepRSAcert cert being the encrypt/decrypt cert, and signingCert being the signing cert:
sscep enroll -c ca.crt -e scepRSAcert.crt -k local.key -r local.csr -K sign.key -O sign.crt -E 3des -S sha256 -l cert.crt -u 'http://example.example.com:8080/ca/cgi-bin/pkiclient.exe'
5.8. Using Certificate Transparency
Certificate System provides a basic version of Certificate Transparency (CT) V1 support (rfc 6962). It has the capability of issuing certificates with embedded Signed Certificate Time stamps (SCTs) from any trusted log where each deployment site choses to have its root CA cert included. You can also configure the system to support multiple CT logs. A minimum of one trusted CT log is required for this feature to work.
Important
It is the responsibility of the deployment site to establish its trust relationship with a trusted CT log server.
For more information on how to configure Certificate Transparency, see the Configuring Certificate Transparency section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
5.8.1. Testing Certificate Transparency
As example on how to test a CT setup, the following procedure describes an actual test against Google CT test logs. A more comprehensive test procedure would involve setting up a TLS server and test for the inclusion of its certs from its specified CT logs. However, the following serves as a quick test that checks for inclusion of the SCT extension once a certificate has been issued.
The test procedure consists in generating and submitting a Certificate Signing Request (CSR), in order to verify its SCT extension using
openssl. The test configuration in the CS.cfg file is as follows:
ca.certTransparency.mode=enabled ca.certTransparency.log.1.enable=true ca.certTransparency.log.1.pubKey=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEw8i8S7qiGEs9NXv0ZJFh6uuOm<snip> ca.certTransparency.log.1.url=http://ct.googleapis.com:80/testtube/ ca.certTransparency.log.1.version=1 ca.certTransparency.log.2.enable=true ca.certTransparency.log.2.pubKey=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEKATl2B3SAbxyzGOfNRB+AytNTG<snip> ca.certTransparency.log.2.url=http://ct.googleapis.com:80/logs/crucible/ ca.certTransparency.log.2.version=1 ca.certTransparency.log.3.enable=false ca.certTransparency.log.3.pubKey=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEiKfWtuoWCPMEzSKySjMjXpo38W<snip> ca.certTransparency.log.3.url=http://ct.googleapis.com:80/logs/solera2020/ ca.certTransparency.log.3.version=1 ca.certTransparency.log.num=3
- First, generate a CSR, e.g:
# PKCS10Client -d . -p passwd -l 2048 -n "cn=user.test.domain.com,OU=user-TEST,O=TestDomain" -o pkcs10-TLS.req
- Next, submit the CSR to an enrollment profile depending on the CT mode defined by the
ca.certTransparency.modeparameter inCS.cfg:- if the parameter is set to enabled, use any enrollment profile
- if the parameter is set to perProfile, use one of the CT profiles: e.g. caServerCertWithSCT
- Copy the issued b64 cert into a file, e.g.
.ct1.pem. - Convert the pem to binary:
# AtoB ct1.pem ct1.bin
- Display the DER certificate content:
# openssl x509 -noout -text -inform der -in ct1.bin
- Observe that the SCT extension is present, e.g:
CT Precertificate SCTs: Signed Certificate Timestamp: Version : v1 (0x0) Log ID : B0:CC:83:E5:A5:F9:7D:6B:AF:7C:09:CC:28:49:04:87: 2A:C7:E8:8B:13:2C:63:50:B7:C6:FD:26:E1:6C:6C:77 Timestamp : Jun 11 23:07:14.146 2020 GMT Extensions: none Signature : ecdsa-with-SHA256 30:44:02:20:6E:E7:DC:D6:6B:A6:43:E3:BB:8E:1D:28: 63:C6:6B:03:43:4E:7A:90:0F:D6:2B:E8:ED:55:1D:5F: 86:0C:5A:CE:02:20:53:EB:75:FA:75:54:9C:9F:D3:7A: D4:E7:C6:6C:9B:33:2A:75:D8:AB:DE:7D:B9:FA:2B:19: 56:22:BB:EF:19:AD Signed Certificate Timestamp: Version : v1 (0x0) Log ID : C3:BF:03:A7:E1:CA:88:41:C6:07:BA:E3:FF:42:70:FC: A5:EC:45:B1:86:EB:BE:4E:2C:F3:FC:77:86:30:F5:F6 Timestamp : Jun 11 23:07:14.516 2020 GMT Extensions: none Signature : ecdsa-with-SHA256 30:44:02:20:4A:C9:4D:EF:64:02:A7:69:FF:34:4E:41: F4:87:E1:6D:67:B9:07:14:E6:01:47:C2:0A:72:88:7A: A9:C3:9C:90:02:20:31:26:15:75:60:1E:E2:C0:A3:C2: ED:CF:22:A0:3B:A4:10:86:D1:C1:A3:7F:68:CC:1A:DD: 6A:5E:10:B2:F1:8F
Alternatively, verify the SCT by running an asn1 dump:# openssl asn1parse -i -inform der -in ct1.bin
and observe the hex dump, e.g:740:d=4 hl=4 l= 258 cons: SEQUENCE 744:d=5 hl=2 l= 10 prim: OBJECT :CT Precertificate SCTs 756:d=5 hl=3 l= 243 prim: OCTET STRING [HEX DUMP]:0481F000EE007500B0CC83E5A5F97D6B<snip>
Chapter 6. Using and Configuring the Token Management System: TPS and TKS
This chapter provides procedures for using hardware security modules, also called HSMs or tokens, to generate and store Certificate System instance certificates and keys.
This chapter only contains administration procedures. For general information on the concepts behind the Token Management System, see the Red Hat Certificate System Planning, Installation and Deployment Guide.
6.1. TPS Profiles
Note
See the TPS Profiles section of the Red Hat Certificate System Planning, Installation and Deployment Guide for general information.
Unlike CA enrollment profiles, which are defined and stored in individual files or in LDAP, TPS profiles (also known as token types) are defined in the TPS configuration file,
CS.cfg.
TPS profile (token type) configuration parameters are set in the following format:
op.<explicit op>.<profile id>.<implicit op>.<key type>.*
In the above, <explicit op> and <implicit op> are one of the explicit and implicit operations discussed in the TPS Operations section below, and <key type> is the name given for each certificate type.
An example configuration parameter may look like the following example:
op.enroll.userKey.keyGen.encryption.*
6.2. TPS Operations
Explicit Operations
An explicit operation is an operation called by a user. Explicit operations include enroll (op.enroll.*), format (op.format.*), and pinReset (op.pinReset.*).
Implicit Operations
An implicit operation is an operation that takes place due to the policy or status of a token at a time when an explicit operation is being processed. Implicit operations include keyGen (op.enroll.userKey.keyGen.*), renewal (op.enroll.userKey.renewal.*), update.applet (op.enroll.userKey.update.applet.*), and key update (op.enroll.userKey.update.symmetricKeys.*).
Some implicit operations are controlled per key type. These include
recovery, serverKeygen, and revocation.
The following example of a TPS profile specifies user keys to be generated on the server side:
op.enroll.userKey.keyGen.encryption.serverKeygen.archive=true op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=kra1 op.enroll.userKey.keyGen.encryption.serverKeygen.enable=true
Additionally, the following example tells TPS that a token whose keys are compromised should revoke the certification with revocation reason
1 during the state transition:
op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1
According to RFC 5280, possible revocation reasons and their codes are defined as follows:
| Reason | Code |
|---|---|
| unspecified | 0 |
| keyCompromise | 1 |
| CACompromise | 2 |
| affiliationChanged | 3 |
| superseded | 4 |
| cessationOfOperation | 5 |
| certificateHold | 6 |
| removeFromCRL | 8 |
| privilegeWithdrawn | 9 |
| AACompromise | 10 |
6.3. Token Policies
This section provides a list of token policies that can be applied on a per token basis using the TPS UI. Ech section will show how each policy is reflected in the configuration.
Note
See the Token Policies section of the Red Hat Certificate System Planning, Installation and Deployment Guide for general information.
The policy is a collection of policies each separated by a semicolon ("
;""). Each policy can be turned on or off with the keywords YES or NO. Each policy in the list below will be introduced with its default value - the action taken by TPS if the setting did not exist at all in the policy string.
- RE_ENROLL=YES
- This policy controls whether or not a token allows a reenroll operation. This allows an already enrolled token (with certificates) to be reenrolled and given new ones. If set to
NO, the server will return an error if a reenrollment is attempted.This policy does not require special configuration. The enrollment will proceed with the standard enrollment profile, which likely enrolled the token originally. - RENEW=NO;RENEW_KEEP_OLD_ENC_CERTS=YES
- Renewal allows a token to have their profile generated certificates to be renewed in place on the token. If
RENEWis set toYES, a simple enrollment from the Enterprise Security Client (ESC) will result in a renewal instead of a reenrollment as discussed above.TheRENEW_KEEP_OLD_ENC_CERTSsetting determines if a renewal operation will retain the previous version of the encryption certificate. Retaining the previous certificate allows users to access data encrypted with the old certificate. Setting this option toNOwill mean that anything encrypted with the old certificate will no longer be recoverable.Configuration:op.enroll.userKey.renewal.encryption.ca.conn=ca1 op.enroll.userKey.renewal.encryption.ca.profileId=caTokenUserEncryptionKeyRenewal op.enroll.userKey.renewal.encryption.certAttrId=c2 op.enroll.userKey.renewal.encryption.certId=C2 op.enroll.userKey.renewal.encryption.enable=true op.enroll.userKey.renewal.encryption.gracePeriod.after=30 op.enroll.userKey.renewal.encryption.gracePeriod.before=30 op.enroll.userKey.renewal.encryption.gracePeriod.enable=false op.enroll.userKey.renewal.keyType.num=2 op.enroll.userKey.renewal.keyType.value.0=signing op.enroll.userKey.renewal.keyType.value.1=encryption op.enroll.userKey.renewal.signing.ca.conn=ca1 op.enroll.userKey.renewal.signing.ca.profileId=caTokenUserSigningKeyRenewal op.enroll.userKey.renewal.signing.certAttrId=c1 op.enroll.userKey.renewal.signing.certId=C1 op.enroll.userKey.renewal.signing.enable=true op.enroll.userKey.renewal.signing.gracePeriod.after=30 op.enroll.userKey.renewal.signing.gracePeriod.before=30 op.enroll.userKey.renewal.signing.gracePeriod.enable=false
This type of renewal configuration mirrors the basicuserKeystandard enrollment profile with a few added settings that are renewal specific. This parity is needed because we went to renew exactly the number and type of certs that were enrolled originally on to the token before renewal is to be put into play. - FORCE_FORMAT=NO
- This policy causes every enrollment operation to prompt a format operation if enabled. This is a last-step option to allow tokens to be reset without a user having to return it to an administrator. If set to
YES, every enrollment operation initiated by the user will cause a format to happen, esentially resetting the token to the formatted state.No additional configuration is necessary. A simple format occurs given the same TPS profile used to perform a standard format operation. - PIN_RESET=NO
- This policy determines if an already enrolled token can perform an explicit “pin reset” change using the ESC. This value must be set to
YESor the attempted operation will be rejected with an error by the server.Configuration:op.enroll.userKey.pinReset.enable=true op.enroll.userKey.pinReset.pin.maxLen=10 op.enroll.userKey.pinReset.pin.maxRetries=127 op.enroll.userKey.pinReset.pin.minLen=4
In the above example, the settings forminLenandmaxLenput constraints on the length of a chosen password, and themaxRetriessetting sets the token to only allow a given number of retries before locking up.
TPS policies can be edited easily using the latest TPS user interface. Navigate to the token that needs a policy change and click Edit. This will bring up a dialog that will allow you to edit the field, which is a collection of semi colon separated policies strung together. Each supported policy must be set to
<POLICYNAME>=YES or <POLICYNAME>=NO in order to be recognized by TPS.
6.4. Token Operation and Policy Processing
This section discusses major operations (both explicit and implicit) that involve a token. The list below will discuss each feature and its configuration.
Note
See the Token Policiessection in the Red Hat Certificate System Planning, Installation and Deployment Guide for general information.
- Format
- The Format operation (user-initiated) takes a token in a completely blank state as supplied by the manufacturer, and loads a Coolkey applet on it.Configuration example:
#specify that we want authentication for format. We almost always want this at true: op.format.userKey.auth.enable=true #specify the ldap authentication configuration, so TPS knows where to validate credentials: op.format.userKey.auth.id=ldap1 #specify the connection the the CA op.format.userKey.ca.conn=ca1 #specify id of the card manager applet on given token op.format.userKey.cardmgr_instance=A0000000030000 #specify if we need to match the visa cuid to the nist sp800sp derivation algorithm KDD value. Mostly will be false: op.format.userKey.cuidMustMatchKDD=false #enable ability to restrict key changoever to a specific range of key set: op.format.userKey.enableBoundedGPKeyVersion=true #enable the phone home url to write to the token: op.format.userKey.issuerinfo.enable=true #actual home url to write to token: op.format.userKey.issuerinfo.value=http://server.example.com:8080/tps/phoneHome #specify whether to request a login from the client. Mostly true, external reg may want this to be false: op.format.userKey.loginRequest.enable=true #Actual range of desired keyset numbers: op.format.userKey.maximumGPKeyVersion=FF op.format.userKey.minimumGPKeyVersion=01 #Whether or not to revoke certs on the token after a format, and what the reason will be if so: op.format.userKey.revokeCert=true op.format.userKey.revokeCert.reason=0 #This will roll back the reflected keyyset version of the token in the tokendb. After a failed key changeover operation. This is to keep the value in sync with reality in the tokendb. Always false, since this version of TPS avoids this situation now: op.format.userKey.rollbackKeyVersionOnPutKeyFailure=false #specify connection to the TKS: op.format.userKey.tks.conn=tks1 #where to get the actual applet file to write to the token: op.format.userKey.update.applet.directory=/usr/share/pki/tps/applets #Allows a completely blank token to be recognized by TPS. Mostly should be true: op.format.userKey.update.applet.emptyToken.enable=true #Always should be true, not supported: op.format.userKey.update.applet.encryption=true #Actual version of the applet file we want to upgrade to. This file will have a name something like: 1.4.54de7a99.ijc: op.format.userKey.update.applet.requiredVersion=1.4.54de790f #Symm key changeover: op.format.userKey.update.symmetricKeys.enable=false op.format.userKey.update.symmetricKeys.requiredVersion=1 #Make sure the token db is in sync with reality. Should always be true: op.format.userKey.validateCardKeyInfoAgainstTokenDB=true
- Enrollment
- The basic enrollment operation takes a formatted token and places certs and keys onto the token in an effort to personalize the token. The following configuration example will explain how this can be controlled.The example shows basic enrollment which does not deal with renewal and internal recovery. Settings not discussed here are either covered in the Format section, or not crucial.
op.enroll.userKey.auth.enable=true op.enroll.userKey.auth.id=ldap1 op.enroll.userKey.cardmgr_instance=A0000000030000 op.enroll.userKey.cuidMustMatchKDD=false op.enroll.userKey.enableBoundedGPKeyVersion=true op.enroll.userKey.issuerinfo.enable=true op.enroll.userKey.issuerinfo.value=http://server.example.com:8080/tps/phoneHome #configure the encryption cert and keys we want on the token: #connection the the CA, which issues the certs: op.enroll.userKey.keyGen.encryption.ca.conn=ca1 #Profile id we want the CA to use to issue our encrytion cert: op.enroll.userKey.keyGen.encryption.ca.profileId=caTokenUserEncryptionKeyEnrollment #These two cover the indexes of the certs written to the token. Each cert needs a unique index or “slot”. In our sample the enc cert will occupy slot 2 and the signing cert, shown later, will occupy slot 1. Avoid overlap with these numbers: op.enroll.userKey.keyGen.encryption.certAttrId=c2 op.enroll.userKey.keyGen.encryption.certId=C2 op.enroll.userKey.keyGen.encryption.cuid_label=$cuid$ #specify size of generated private key: op.enroll.userKey.keyGen.encryption.keySize=1024 op.enroll.userKey.keyGen.encryption.keyUsage=0 op.enroll.userKey.keyGen.encryption.keyUser=0 #specify pattern for what the label of the cert will look like when the cert nickname is displayed in browsers and mail clients: op.enroll.userKey.keyGen.encryption.label=encryption key for $userid$ #specify if we want to overwrite certs on a re-enrollment operation. This is almost always the case: op.enroll.userKey.keyGen.encryption.overwrite=true #The next several settings specify the capabilities that the private key on the final token will inherit. For instance this will determine if the cert can be used for encryption or digital signatures. There are settings for both the private and public key. op.enroll.userKey.keyGen.encryption.private.keyCapabilities.decrypt=true op.enroll.userKey.keyGen.encryption.private.keyCapabilities.derive=false op.enroll.userKey.keyGen.encryption.private.keyCapabilities.encrypt=false op.enroll.userKey.keyGen.encryption.private.keyCapabilities.private=true op.enroll.userKey.keyGen.encryption.private.keyCapabilities.sensitive=true op.enroll.userKey.keyGen.encryption.private.keyCapabilities.sign=false op.enroll.userKey.keyGen.encryption.private.keyCapabilities.signRecover=false op.enroll.userKey.keyGen.encryption.private.keyCapabilities.token=true op.enroll.userKey.keyGen.encryption.private.keyCapabilities.unwrap=true op.enroll.userKey.keyGen.encryption.private.keyCapabilities.verify=false op.enroll.userKey.keyGen.encryption.private.keyCapabilities.verifyRecover=false op.enroll.userKey.keyGen.encryption.private.keyCapabilities.wrap=false op.enroll.userKey.keyGen.encryption.privateKeyAttrId=k4 op.enroll.userKey.keyGen.encryption.privateKeyNumber=4 op.enroll.userKey.keyGen.encryption.public.keyCapabilities.decrypt=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.derive=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.encrypt=true op.enroll.userKey.keyGen.encryption.public.keyCapabilities.private=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.sensitive=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.sign=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.signRecover=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.token=true op.enroll.userKey.keyGen.encryption.public.keyCapabilities.unwrap=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.verify=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.verifyRecover=false op.enroll.userKey.keyGen.encryption.public.keyCapabilities.wrap=true #The following index numbers correspond to the index or slot that the private and public keys occupy. The common formula we use is that the public key index will be 2 * cert id + 1, and the private key index, shown above will be 2 * cert id. In this example the cert id is 2, so the key ids will be 4 and 5 respectively. When composing these, be careful not to create conflicts. This applies to the signing key section below. op.enroll.userKey.keyGen.encryption.publicKeyAttrId=k5 op.enroll.userKey.keyGen.encryption.publicKeyNumber=5 #specify if, when a certificate is slated for revocation, based on other rules, we want to check to see if some other token is using this cert in a shared situation. If this is set to true, and this situation is found the cert will not be revoked until the last token wants to revoke this cert: op.enroll.userKey.keyGen.encryption.recovery.destroyed.holdRevocationUntilLastCredential=false #specify, if we want server side keygen, if we want to have that generated key archived to the drm. This is almost always the case, since we want the ability to later recover a cert and its encryption private key back to a new token: op.enroll.userKey.keyGen.encryption.serverKeygen.archive=true #connection to drm to generate the key for us: op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=kra1 #specify server side keygen of the encryption private key. This most often will be desired: op.enroll.userKey.keyGen.encryption.serverKeygen.enable=true #This setting tells us how many certs we want to enroll for this TPS profile, in the case “userKey”. Here we want 2 total certs. The next values then go on to index into the config what two types of certs we want, signing and encryption: op.enroll.userKey.keyGen.keyType.num=2 op.enroll.userKey.keyGen.keyType.value.0=signing op.enroll.userKey.keyGen.keyType.value.1=encryption #configure the signing cert and keys we want on the token the settings for these are similar to the encryption settings already discussed, except the capability flags presented below, since this is a signing key. op.enroll.userKey.keyGen.signing.ca.conn=ca1 op.enroll.userKey.keyGen.signing.ca.profileId=caTokenUserSigningKeyEnrollment op.enroll.userKey.keyGen.signing.certAttrId=c1 op.enroll.userKey.keyGen.signing.certId=C1 op.enroll.userKey.keyGen.signing.cuid_label=$cuid$ op.enroll.userKey.keyGen.signing.keySize=1024 op.enroll.userKey.keyGen.signing.keyUsage=0 op.enroll.userKey.keyGen.signing.keyUser=0 op.enroll.userKey.keyGen.signing.label=signing key for $userid$ op.enroll.userKey.keyGen.signing.overwrite=true op.enroll.userKey.keyGen.signing.private.keyCapabilities.decrypt=false op.enroll.userKey.keyGen.signing.private.keyCapabilities.derive=false op.enroll.userKey.keyGen.signing.private.keyCapabilities.encrypt=false op.enroll.userKey.keyGen.signing.private.keyCapabilities.private=true op.enroll.userKey.keyGen.signing.private.keyCapabilities.sensitive=true op.enroll.userKey.keyGen.signing.private.keyCapabilities.sign=true op.enroll.userKey.keyGen.signing.private.keyCapabilities.signRecover=true op.enroll.userKey.keyGen.signing.private.keyCapabilities.token=true op.enroll.userKey.keyGen.signing.private.keyCapabilities.unwrap=false op.enroll.userKey.keyGen.signing.private.keyCapabilities.verify=false op.enroll.userKey.keyGen.signing.private.keyCapabilities.verifyRecover=false op.enroll.userKey.keyGen.signing.private.keyCapabilities.wrap=false op.enroll.userKey.keyGen.signing.privateKeyAttrId=k2 op.enroll.userKey.keyGen.signing.privateKeyNumber=2 op.enroll.userKey.keyGen.signing.public.keyCapabilities.decrypt=false op.enroll.userKey.keyGen.signing.public.keyCapabilities.derive=false op.enroll.userKey.keyGen.signing.public.keyCapabilities.encrypt=false op.enroll.userKey.keyGen.signing.public.keyCapabilities.private=false op.enroll.userKey.keyGen.signing.public.keyCapabilities.sensitive=false op.enroll.userKey.keyGen.signing.public.keyCapabilities.sign=false op.enroll.userKey.keyGen.signing.public.keyCapabilities.signRecover=false op.enroll.userKey.keyGen.signing.public.keyCapabilities.token=true op.enroll.userKey.keyGen.signing.public.keyCapabilities.unwrap=false op.enroll.userKey.keyGen.signing.public.keyCapabilities.verify=true op.enroll.userKey.keyGen.signing.public.keyCapabilities.verifyRecover=true op.enroll.userKey.keyGen.signing.public.keyCapabilities.wrap=false op.enroll.userKey.keyGen.signing.publicKeyAttrId=k3 op.enroll.userKey.keyGen.signing.publicKeyNumber=3
- Pin Reset
- The configuration for pin reset is discussed in Section 6.3, “Token Policies”, because pin reset relies on a policy to determine if it is to be legally performed or not.
- Renewal
- The configuration for renewal is discussed in Section 6.3, “Token Policies”, since renewal relies on a policy to determine if it is legal to perform or not upon an already enrolled token.
- Recovery
- Recovery is implicitly set into motion when the user of the TPS user interface marks a previously active token into an unfavorable state such as “lost” or “destroyed”. Once this happens, the next enrollment of a new token by the same user will adhere to the following configuration to recover the certificates from the user’s old token, to this new token.The end result of this operation is that the user will have a new physical token that may contain the encryption certificates recovered from the old token, so that the user can continue to encrypt and decrypt data as needed. A new signing certificate is also usually placed on this token as shown in the sample config examples below.The following is a list of supported states into which a token can be placed manually in the TPS user interface, as seen in the configuration:
tokendb._069=#-DAMAGED (1): Corresponds todestroyedin the recovery configuration. Used when a token has been physically damaged.tokendb._070=#-PERM_LOST (2): Corresponds tokeyCompromisein the recovery configuration. Used when a token has been lost permanently.tokendb._071=#-SUSPENDED (3): Corresponds toonHoldin the recovery configuration. Used when a token has been temporarily misplaced, but the user expects to find it again.tokendb._072=#-TERMINATED (6): Corresponds toterminatedin the recovery configuration. Used to take a token out of service forever for internal reasons.
Example recovery configuration:#When a token is marked destroyed, don’t revoke the certs on the token unless all other tokens do not have the certs included: op.enroll.userKey.keyGen.encryption.recovery.destroyed.holdRevocationUntilLastCredential=false #specify if we even want to revoke certs a token is marked destroyed: op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert=false #if we want to revoke any certs here, specify the reason for revocation that will be sent to the CA: op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert.reason=0 #speficy if we want to revoke expired certs when marking the token destroyed: op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeExpiredCerts=false
Additional settings are used to specify what kind of supported static recovery should be used when performing a recovery operation to a new token (when the original token has been marked destroyed). The following schemes are supported:- Recover Last (
RecoverLast): Recover the latest encryption certificate to be placed on the token. - Generate New Key and Recover Last (
GenerateNewKeyAndRecoverLast): Same as Recover Last, but also generate a new encryption certificate and upload it to the token as well. The new token will then have two certificates. - Generate New Key (
GenerateNewKey): Generate a new encryption certificate and place it on the token. Do not recover any old certificates.
For example:op.enroll.userKey.keyGen.encryption.recovery.destroyed.scheme=RecoverLast
The following configuration example determines how to recover tokens marked as permanently lost:op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.holdRevocationUntilLastCredential=false op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1 op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeExpiredCerts=false op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.scheme=GenerateNewKey # Section when a token is marked terminated. op.enroll.userKey.keyGen.encryption.recovery.terminated.holdRevocationUntilLastCredential=false op.enroll.userKey.keyGen.encryption.recovery.terminated.revokeCert=true op.enroll.userKey.keyGen.encryption.recovery.terminated.revokeCert.reason=1 op.enroll.userKey.keyGen.encryption.recovery.terminated.revokeExpiredCerts=false op.enroll.userKey.keyGen.encryption.recovery.terminated.scheme=GenerateNewKey # This section details the recovery profile with respect to which certs and of what kind get recovered on the token. op.enroll.userKey.keyGen.recovery.destroyed.keyType.num=2 op.enroll.userKey.keyGen.recovery.destroyed.keyType.value.0=signing op.enroll.userKey.keyGen.recovery.destroyed.keyType.value.1=encryption
Finally, the following example determines what the system will do about the signing certificate that was on the old token. In most cases, theGenerateNewKeyrecovery scheme should be used in order to avoid potentially having multiple copies of a signing private key available (for example, one that is recovered on a new token, and one on an old token that was permanently lost but found by somebody else).op.enroll.userKey.keyGen.recovery.keyCompromise.keyType.value.0=signing op.enroll.userKey.keyGen.recovery.keyCompromise.keyType.value.1=encryption op.enroll.userKey.keyGen.recovery.onHold.keyType.num=2 op.enroll.userKey.keyGen.recovery.onHold.keyType.value.0=signing op.enroll.userKey.keyGen.recovery.onHold.keyType.value.1=encryption op.enroll.userKey.keyGen.signing.recovery.destroyed.holdRevocationUntilLastCredential=false op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert.reason=0 op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeExpiredCerts=false op.enroll.userKey.keyGen.signing.recovery.destroyed.scheme=GenerateNewKey op.enroll.userKey.keyGen.signing.recovery.keyCompromise.holdRevocationUntilLastCredential=false op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert.reason=1 op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeExpiredCerts=false op.enroll.userKey.keyGen.signing.recovery.keyCompromise.scheme=GenerateNewKey op.enroll.userKey.keyGen.signing.recovery.onHold.holdRevocationUntilLastCredential=false op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert.reason=6 op.enroll.userKey.keyGen.signing.recovery.onHold.revokeExpiredCerts=false op.enroll.userKey.keyGen.signing.recovery.onHold.scheme=GenerateNewKey op.enroll.userKey.keyGen.signing.recovery.terminated.holdRevocationUntilLastCredential=false op.enroll.userKey.keyGen.signing.recovery.terminated.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.terminated.revokeCert.reason=1 op.enroll.userKey.keyGen.signing.recovery.terminated.revokeExpiredCerts=false op.enroll.userKey.keyGen.signing.recovery.terminated.scheme=GenerateNewKey # Configuration for the case when we mark a token “onHold” or temporarily lost op.enroll.userKeyTemporary.keyGen.encryption.recovery.onHold.revokeCert=true op.enroll.userKeyTemporary.keyGen.encryption.recovery.onHold.revokeCert.reason=0 op.enroll.userKeyTemporary.keyGen.encryption.recovery.onHold.scheme=RecoverLast op.enroll.userKeyTemporary.keyGen.recovery.onHold.keyType.num=2 op.enroll.userKeyTemporary.keyGen.recovery.onHold.keyType.value.0=signing op.enroll.userKeyTemporary.keyGen.recovery.onHold.keyType.value.1=encryption op.enroll.userKeyTemporary.keyGen.signing.recovery.onHold.revokeCert=true op.enroll.userKeyTemporary.keyGen.signing.recovery.onHold.revokeCert.reason=0 op.enroll.userKeyTemporary.keyGen.signing.recovery.onHold.scheme=GenerateNewKey
- Applet Update
- The following example shows how to configure a Coolkey applet update operation. This operation can be performed during format, enrollment, and PIN reset operations:
op.format.userKey.update.applet.directory=/usr/share/pki/tps/applets op.format.userKey.update.applet.emptyToken.enable=true op.format.userKey.update.applet.encryption=true op.format.userKey.update.applet.requiredVersion=1.4.54de790f
Some of these options have already been demonstrated in the Format section. They provide information needed to determine if applet upgrade should be allowed, where to find the applet files, and the applet version to upgrade the token to. The version in therequiredVersionmaps to a file name inside thedirectory. - Key Update
- This operation, which can take place during format, enrollment, and PIN reset operations, allows the user to have their Global Platform key set version upgraded from the default supplied by the manufacturer.
- TPS
- The following options will instruct the TPS to upgrade the keyset from 1 to 2 during the next format operation requested on behalf of a given token. After this is done, the TKS must derive the three new keys that will be written to the token, Afterwards, the token must be used with the same TPS and TKS installation, otherwise it will become locked.
op.format.userKey.update.symmetricKeys.enable=true op.format.userKey.update.symmetricKeys.requiredVersion=2
You can also specify a version lower than current to downgrade the keyset instead. - TKS
- As mentioned above, the TKS must be configured to generate the new keys to write to the token. First, the new master key identifier,
02, must be mapped to its PKCS #11 object nickname in the TKSCS.cfg, as shown in the following example:tks.mk_mappings.#02#01=internal:new_master tks.defKeySet.mk_mappings.#02#01=internal:new_master
The above will map a key set number to an actual master key which exists in the TKS NSS database.Master keys are identified by IDs such as01. The TKS maps these IDs to PKCS #11 object nicknames specified in themasterKeyIdpart of the mapping. Therefore, the first number is updated as the master key version is updated, and the second number stays consistent.When attempting to upgrade from version 1 to version 2, the mapping determines how to find the master key nickname which will be used to derive the 3 parts of the new key set.The setting ofinternalin the above example references the name of the token where the master key resides. It could also be an external HSM module with a name such asnethsm. The strongnew_masteris an example of the master key nickname itself.
6.5. Internal Registration
Note
See the TPS Profiles section of the Red Hat Certificate System Planning, Installation and Deployment Guide for general information.
In case of Internal Registration, the TPS profile (token type) is determined by the Mapping Resolver. In contrast with External Registration, authentication information is defined within the profile itself. For example:
op.enroll.userKey.auth.enable=true op.enroll.userKey.auth.id=ldap1
Another difference from External Registration is that the CA and KRA connector information is defined under each key type of each profile. For example:
op.enroll.userKey.keyGen.encryption.ca.conn=ca1 op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=kra1
TKS connector information, however, is defined per profile:
op.enroll.userKey.tks.conn=tks1
Note
Switching registration types between Internal and External Registration means you have to format all previously registered tokens before you can continue using them.
6.6. External Registration
External Registration obtains the token type (TPS profile) from the authenticated user LDAP record. It also allows certificate/key recovery information to be specified in the same user record.
An External Registration TPS profile is similar to the Internal Registration profile discussed previously. It allows you to specify new certificate enrollments for both client-side and server-side key generation. Unlike Internal Registration, it allows you to choose specific certificate (and its matching keys) to be retrieved and loaded onto the token.
Note
Switching registration types between Internal and External Registration means you have to format all previously registered tokens before you can continue using them.
6.6.1. Enabling External Registration
External Registration can only be enabled globally for an entire TPS instance. The following example shows a set of global configuration parameters pertaining to External Registration:
externalReg.allowRecoverInvalidCert.enable=true externalReg.authId=ldap1 externalReg.default.tokenType=externalRegAddToToken externalReg.delegation.enable=true externalReg.enable=true externalReg.recover.byKeyID=false externalReg.format.loginRequest.enable=true externalReg.mappingResolver=keySetMappingResolver
6.6.2. Customizing User LDAP Record Attribute Names
Authentication parameters pertaining to External Registration are shown in the following example (with their default values):
auths.instance.ldap1.externalReg.certs.recoverAttributeName=certsToAdd auths.instance.ldap1.externalReg.cuidAttributeName=tokenCUID auths.instance.ldap1.externalReg.tokenTypeAttributeName=tokenType
The LDAP record attribute names can be customized here. Make sure that the actual attributes in the user's LDAP records match this configuration.
6.6.3. Configuring certsToAdd attributes
The
certsToAdd attribute takes multiple values in the following form:
<cert serial # in decimal>,<CA connector ID>,<key ID>,<kra connector ID>
For example:
59,ca1,0,kra1
Important
By default, key recovery searches for the key by certificate, which makes the <key ID> value irrelevant. However, the TPS can optionally be configured to search for the key using this attribute, and therefore it is typically simpler to set the value to 0. That value is invalid, which avoids the possibility of retrieving an unmatched key.
Recovering by key ID is not recommended, because the KRA can not verify if the certificate matches with the key in this situation.
When specifying the
certsToAdd attribute with only certificate and CA information, the TPS assumes that the certificate in question is already on the token, and that it should be preserved. This concept is called Key Retention.
The following examples show relevant attributes in the user LDAP record:
tokenType: externalRegAddToToken certstoadd: 59,ca1,0,kra1 certstoadd: 134,ca1,0,kra1 Certstoadd: 24,ca1
6.6.4. Token to User Matching Enforcement
Optionally, you can set the system up so that the token used for registration must match the token record card-unique ID (CUID) attribute in the user record. If this attribute (
tokencuid) is missing from the record, CUID matching is not enforced.
Tokencuid: a10192030405028001c0
Another attribute about External Registration is that the Token Policies on each token are bypassed.
Note
For the certificate and keys to be “recovered” in External Registration, connector information for CA and KRA is specified in the user LDAP record. Any CA and/or KRA connector information specified in the TPS profile pertaining to the certificate/keys to be “recovered” is to be ignored.
certstoadd: 59,ca1,0,kra1
6.6.5. Delegation Support
Delegation support is useful where a user has delegates who can act on their behalf (for example, an executive at a company has one or more delegates) in terms of authentication (logins), data encryption and decryption, or signing (with limitations).
An example scenario could be that each delegate has their own token which they use to act on behalf of the executive. This token contains a combination of the following certificates and keys (determined by TPS profiles):
- Authentication certificate/keys: The CN contains the name and unique ID of the delegate. The Subject Alternative Name (SAN) extension contains the Principal Name (UPN) of the executive.
- Encryption certificate: An exact copy of the executive's encryption certificate.
- Signing certificate: The CN contains the delegate's name and unique ID. The SAN contains the RFC822Name of the executive.
Use the following parameter to enable delegation support:
externalReg.delegation.enable=true
Important
To work around a bug, manually set the
op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId parameter in the /var/lib/pki/instance_name/tps/conf/CS.cfg file to caTokenUserDelegateAuthKeyEnrollment:
op.enroll.delegateISEtoken.keyGen.encryption.ca.profileId=caTokenUserDelegateAuthKeyEnrollment
6.6.6. SAN and DN Patterns
The
auths.instance.<authID>.ldapStringAttributes in the authentication instance configuration specifies which attributes will be retrieved during authentication. For example:
auths.instance.ldap1.ldapStringAttributes=mail,cn,uid,edipi,pcc,firstname,lastname,exec-edipi,exec-pcc,exec-mail,certsToAdd,tokenCUID,tokenType
Once retrieved from the user's LDAP record, the values of these attributes can be referenced and used to form the Subject Alternative Name (SAN) or Distinguished Name (DN) of the certificate in the format of
$auth.<attribute name>$. For example:
op.enroll.delegateIEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@EXAMPLE.com op.enroll.delegateIEtoken.keyGen.authentication.dnpattern=cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org
When patterns are used in TPS profiles for SAN and DN, it is important to ensure the CA enrollment profile specified in the TPS profile is set up correctly. For example:
- On TPS, in profile delegateIEtoken
op.enroll.delegateIEtoken.keyGen.authentication.ca.profileId=caTokenUserDelegateAuthKeyEnrollment
- On CA, in enrollment profile caTokenUserDelegateAuthKeyEnrollment
- The
subjectDNInputImplplug-in must be specified as one of the inputs in order to allow the DN to be specified by the TPS profile above:input.i2.class_id=subjectDNInputImpl input.i2.name=subjectDNInputImpl
Similarly, to allow the SAN to be specified by the above TPS profile, thesubjectAltNameExtInputImplplug-in must be specified:input.i3.class_id=subjectAltNameExtInputImpl input.i3.name=subjectAltNameExtInputImpl
ThesubjAltExtpatternmust be specified as well:policyset.set1.p6.default.params.subjAltExtPattern_0=(UTF8String)1.3.6.1.4.1.311.20.2.3,$request.req_san_pattern_0$
In the above example, the OID1.3.6.1.4.1.311.20.2.3is the OID for the User Principal Name (UPN), andrequest.req_san_pattern_0is the first SAN pattern specified in thedelegateIEtokenSAN pattern.
You can specify multiple SANs at the same time. On the TPS side, specify multiple SANs in the
SANpattern, delimited by a comma (","). On the CA side, a corresponding amount of subjAltExtPattern needs to be defined in the following format:
policyset.<policy set id>.<policy id>.default.params.subjAltExtPattern_<ordered number>=
In the above, the <ordered number> starts with 0 and increases by one for each SAN pattern specified on the TPS side:
policyset.set1.p6.default.params.subjAltExtPattern_0= policyset.set1.p6.default.params.subjAltExtPattern_1= ...
The following is a complete example:
Example 6.1. SANpattern and DNpattern configuration
The LDAP record contains the following information:
givenName: user1a mail: user1a@example.org firstname: user1a edipi: 123456789 pcc: AA exec-edipi: 999999999 exec-pcc: BB exec-mail: user1b@EXAMPLE.com tokenType: delegateISEtoken certstoadd: 59,ca1,0,kra1
TPS External Registration profile
delegateIEtoken contains:
SANpattern:op.enroll.delegateISEtoken.keyGen.authentication.SANpattern=$auth.exec-edipi$.$auth.exec-pcc$@EXAMPLE.com
DNPattern:op.enroll.delegateISEtoken.keyGen.authentication.dnpattern=cn=$auth.firstname$.$auth.lastname$.$auth.edipi$,e=$auth.mail$,o=TMS Org
CA
caTokenUserDelegateAuthKeyEnrollment contains:
input.i2.class_id=subjectDNInputImpl input.i2.name=subjectDNInputImpl input.i3.class_id=subjectAltNameExtInputImpl input.i3.name=subjectAltNameExtInputImpl policyset.set1.p6.constraint.class_id=noConstraintImpl policyset.set1.p6.constraint.name=No Constraint policyset.set1.p6.default.class_id=subjectAltNameExtDefaultImpl policyset.set1.p6.default.name=Subject Alternative Name Extension Default policyset.set1.p6.default.params.subjAltExtGNEnable_0=true policyset.set1.p6.default.params.subjAltExtPattern_0=(UTF8String)1.3.6.1.4.1.311.20.2.3,$request.req_san_pattern_0$ policyset.set1.p6.default.params.subjAltExtType_0=OtherName policyset.set1.p6.default.params.subjAltNameExtCritical=false policyset.set1.p6.default.params.subjAltNameNumGNs=1
The resulting certificate then contains:
Subject: CN=user1a..123456789,E=user1a@example.org,O=TMS Org Identifier: Subject Alternative Name - 2.5.29.17 Critical: no Value: OtherName: (UTF8String)1.3.6.1.4.1.311.20.2.3,999999999.BB@EXAMPLE.com
6.7. Mapping Resolver Configuration
The Token Processing System provides a single mapping resolver by default. The resolver is called
FilterMappingResolver. This section will cover its configuration.
Note
See the Mapping Resolver section of the Red Hat Certificate System Planning, Installation, and Deployment Guide for general information about the Mapping Resolver.
6.7.1. Key Set Mapping Resolver
During External Registration, the key set must be resolved using the resolver before a user can authenticate.
The key set mapping resolver name is defined as follows:
externalReg.mappingResolver=<keySet mapping resolver name>
For example:
externalReg.mappingResolver=keySetMappingResolver
The following configuration example shows a full instance configuration:
mappingResolver.keySetMappingResolver.class_id=filterMappingResolverImpl mappingResolver.keySetMappingResolver.mapping.0.filter.appletMajorVersion=0 mappingResolver.keySetMappingResolver.mapping.0.filter.appletMinorVersion=0 mappingResolver.keySetMappingResolver.mapping.0.filter.keySet= mappingResolver.keySetMappingResolver.mapping.0.filter.tokenATR= mappingResolver.keySetMappingResolver.mapping.0.filter.tokenCUID.end=a1000000000000000000 mappingResolver.keySetMappingResolver.mapping.0.filter.tokenCUID.start=a0000000000000000000 mappingResolver.keySetMappingResolver.mapping.0.target.keySet=defKeySet mappingResolver.keySetMappingResolver.mapping.1.filter.appletMajorVersion=1 mappingResolver.keySetMappingResolver.mapping.1.filter.appletMinorVersion=1 mappingResolver.keySetMappingResolver.mapping.1.filter.keySet= mappingResolver.keySetMappingResolver.mapping.1.filter.tokenATR=1234 mappingResolver.keySetMappingResolver.mapping.1.filter.tokenCUID.end= mappingResolver.keySetMappingResolver.mapping.1.filter.tokenCUID.start= mappingResolver.keySetMappingResolver.mapping.1.target.keySet=defKeySet mappingResolver.keySetMappingResolver.mapping.2.filter.appletMajorVersion= mappingResolver.keySetMappingResolver.mapping.2.filter.appletMinorVersion= mappingResolver.keySetMappingResolver.mapping.2.filter.keySet= mappingResolver.keySetMappingResolver.mapping.2.filter.tokenATR= mappingResolver.keySetMappingResolver.mapping.2.filter.tokenCUID.end= mappingResolver.keySetMappingResolver.mapping.2.filter.tokenCUID.start= mappingResolver.keySetMappingResolver.mapping.2.target.keySet=jForte mappingResolver.keySetMappingResolver.mapping.order=0,1,2
The above example defines three mappings named
0, 1, and 2. They are ordered in ascending order using the mappingResolver.keySetMappingResolver.mapping.order=0,1,2 line in the example. This order means the input parameters will be run against the mapping filter 0 first; only if they do not match that filter, the next one in the mapping order will be tried. For example, if a token with the following characteristics is evaluated:
CUID=a0000000000000000011 appletMajorVersion=0 appletMinorVersion=0
Then it would pass mapping
0 and be assigned its target, which is configured to defKeySet, because the applet version matches and the CUID falls within the CUID start and end range for that mapping.
On the other hand, if a token has the following parameters:
CUID=b0000000000000000000 ATR=2222 appletMajorVersion=1 appletMinorVersion=1
In this case this token fails mapping
0 because it is outside the specified CUID range. It also fails mapping 1 because while the applet versions match, the ATR does not. The above token will be assigned to mapping 2 and its target, jForte.
Note how mapping
2 has no assignments for any of its filters. This causes the mapping to match all tokens, effectively making it a "default" value. Mappings like this must be specified last in the mapping order, because any other mappings after it will never be evaluated.
6.7.2. Token Type (TPS) Mapping Resolver
There are three default
tokenType mapping resolvers defined in the Token Processing System: formatProfileMappingResolver, enrollProfileMappingResolver, and pinResetProfileMappingResolver. Compared to the External Registration case discussed in the previous section, in the Internal Registration case token types are actually calculated from the defined mapping resolver.
The token type mapping resolver names are defined as follows:
op.<op>.mappingResolver=<mapping resolver name>
For example:
op.enroll.mappingResolver=enrollProfileMappingResolver
The following configuration example describes the
enrollProfileMappingResolver:
mappingResolver.enrollProfileMappingResolver.class_id=filterMappingResolverImpl mappingResolver.enrollProfileMappingResolver.mapping.0.filter.appletMajorVersion=1 mappingResolver.enrollProfileMappingResolver.mapping.0.filter.appletMinorVersion= mappingResolver.enrollProfileMappingResolver.mapping.0.filter.tokenATR= mappingResolver.enrollProfileMappingResolver.mapping.0.filter.tokenCUID.end=b1000000000000000000 mappingResolver.enrollProfileMappingResolver.mapping.0.filter.tokenCUID.start=b0000000000000000000 mappingResolver.enrollProfileMappingResolver.mapping.0.filter.tokenType=userKey mappingResolver.enrollProfileMappingResolver.mapping.0.target.tokenType=userKey mappingResolver.enrollProfileMappingResolver.mapping.1.filter.appletMajorVersion=1 mappingResolver.enrollProfileMappingResolver.mapping.1.filter.appletMinorVersion= mappingResolver.enrollProfileMappingResolver.mapping.1.filter.tokenATR= mappingResolver.enrollProfileMappingResolver.mapping.1.filter.tokenCUID.end=a0000000000000001000 mappingResolver.enrollProfileMappingResolver.mapping.1.filter.tokenCUID.start=a0000000000000000000 mappingResolver.enrollProfileMappingResolver.mapping.1.filter.tokenType=soKey mappingResolver.enrollProfileMappingResolver.mapping.1.target.tokenType=soKey mappingResolver.enrollProfileMappingResolver.mapping.2.filter.appletMajorVersion= mappingResolver.enrollProfileMappingResolver.mapping.2.filter.appletMinorVersion= mappingResolver.enrollProfileMappingResolver.mapping.2.filter.tokenATR= mappingResolver.enrollProfileMappingResolver.mapping.2.filter.tokenCUID.end= mappingResolver.enrollProfileMappingResolver.mapping.2.filter.tokenCUID.start= mappingResolver.enrollProfileMappingResolver.mapping.2.filter.tokenType= mappingResolver.enrollProfileMappingResolver.mapping.2.target.tokenType=userKey mappingResolver.enrollProfileMappingResolver.mapping.order=1,0,2
Three mappings are defined for the
enrollProfileMappingResolver in the above example. The mappings are named 0, 1, and 2. The mappingResolver.enrollProfileMappingResolver.mapping.order=1,0,2 line defines the order in which the mappings will be processed. If a token matches a mapping, no further mappings in the order will be evaluated; if it does not match a mapping, the next one in the order will be tried.
In case of a token with the following parameters:
CUID=a0000000000000000011 appletMajorVersion=1 appletMinorVersion=0 extension: tokenType=soKey
A token with this configuration will match the filters for mapping
1 because the applet version matches, the CUID fails within the specified start and end range, and the extension tokenType matches. Therefore, this token will be assigned the target for that mapping - soKey.
In another case, if the token has the following parameters:
CUID=b0000000000000000010 appletMajorVersion=1 appletMinorVersion=1
In this case, the token will fail mapping
1 because the CUID is outside the specified range. Then it will also fail mapping 0, because the tokenType extension is missing. This token will then match mapping 2, because it has no specified filters in order to match all tokens which did not match any of the previous filters.
6.8. Authentication Configuration
The Token Processing System supports directory-based authentication using a user ID and password (
UidPwdDirAuthentication) by default. Authentication instances are defined in the CS.cfg file using the following pattern:
auths.instance.<auths ID>.*
The <auths ID> is the authenticator name to be referenced by the TPS profiles for authentication preferences. For example:
op.enroll.userKey.auth.id=ldap1
The following configuration example shows a full definition of an authentication instance:
auths.impl.UidPwdDirAuth.class=com.netscape.cms.authentication.UidPwdDirAuthentication auths.instance.ldap1.pluginName=UidPwdDirAuth auths.instance.ldap1.authCredName=uid auths.instance.ldap1.dnpattern= auths.instance.ldap1.externalReg.certs.recoverAttributeName=certsToAdd auths.instance.ldap1.externalReg.cuidAttributeName=tokenCUID auths.instance.ldap1.externalReg.tokenTypeAttributeName=tokenType auths.instance.ldap1.ldap.basedn=dc=sjc,dc=example,dc=com auths.instance.ldap1.ldap.ldapauth.authtype=BasicAuth auths.instance.ldap1.ldap.ldapauth.bindDN= auths.instance.ldap1.ldap.ldapauth.bindPWPrompt=ldap1 auths.instance.ldap1.ldap.ldapauth.clientCertNickname=subsystemCert cert-pki-tomcat auths.instance.ldap1.ldap.ldapconn.host=host1.EXAMPLE.com auths.instance.ldap1.ldap.ldapconn.port=389 auths.instance.ldap1.ldap.ldapconn.secureConn=False auths.instance.ldap1.ldap.ldapconn.version=3 auths.instance.ldap1.ldap.maxConns=15 auths.instance.ldap1.ldap.minConns=3 auths.instance.ldap1.ldapByteAttributes= auths.instance.ldap1.ldapStringAttributes=mail,cn,uid,edipi,pcc,firstname,lastname,exec-edipi,exec-pcc,exec-mail,certsToAdd,tokenCUID,tokenType auths.instance.ldap1.ldapStringAttributes._000=################################# auths.instance.ldap1.ldapStringAttributes._001=# For isExternalReg auths.instance.ldap1.ldapStringAttributes._002=# attributes will be available as auths.instance.ldap1.ldapStringAttributes._003=# $<attribute>$ auths.instance.ldap1.ldapStringAttributes._004=# attributes example: auths.instance.ldap1.ldapStringAttributes._005=#mail,cn,uid,edipi,pcc,firstname,lastname,exec-edipi,exec-pcc,exec-mail,certsToAdd,tokenCUID,tokenType auths.instance.ldap1.ldapStringAttributes._006=################################# auths.instance.ldap1.pluginName=UidPwdDirAuth auths.instance.ldap1.ui.description.en=This authenticates user against the LDAP directory. auths.instance.ldap1.ui.id.PASSWORD.credMap.authCred=pwd auths.instance.ldap1.ui.id.PASSWORD.credMap.msgCred.extlogin=PASSWORD auths.instance.ldap1.ui.id.PASSWORD.credMap.msgCred.login=password auths.instance.ldap1.ui.id.PASSWORD.description.en=LDAP Password auths.instance.ldap1.ui.id.PASSWORD.name.en=LDAP Password auths.instance.ldap1.ui.id.UID.credMap.authCred=uid auths.instance.ldap1.ui.id.UID.credMap.msgCred.extlogin=UID auths.instance.ldap1.ui.id.UID.credMap.msgCred.login=screen_name auths.instance.ldap1.ui.id.UID.description.en=LDAP User ID auths.instance.ldap1.ui.id.UID.name.en=LDAP User ID auths.instance.ldap1.ui.retries=3 auths.instance.ldap1.ui.title.en=LDAP Authentication
TPS authentication instances are configured in a way similar to the CA's
UidPwdDirAuthentication authentication instance, since both are handled by the same plug-in. However, the TPS requires several extra parameters on top of the CA configuration.
In case of common operations (for both Internal and External registration), profiles that call for this authentication method allow TPS to project how the UID and password will be labeled on the client side. This is controlled by the
auths.instance.ldap1.ui.id.UID.name.en=LDAP User ID and auths.instance.ldap1.ui.id.PASSWORD.name.en=LDAP Password parameters in the above example; this configuration tells clients to display the UID/password pair as "LDAP User ID" and "LDAP Password". Both parameters can be customized.
The
credMap.authCred entries configure how the internal authentication plug-in accepts information presented to it, and the credMap.msgCred entries configure how this information is passed to the TPS. These fields allow you to use customized plug-in implementations, and should be left at their default values unless you are using a custom authentication plug-in.
Parameters related to External Registration are discussed in Section 6.6, “External Registration”.
Similarly to CA authentication configuration, you can define multiple authentication instances for the same authentication implementation. This may be useful when the TPS serves multiple groups of users; you can direct each group to use its own TPS profile, each configured to use its own directory server authentication.
6.9. Connectors
Connectors define how the TPS communicates with other subsystems - namely CA, KRA, and TKS. In general, these parameters are set up during TPS installation. The following is an example of connector configuration:
tps.connector.ca1.enable=true tps.connector.ca1.host=host1.EXAMPLE.com tps.connector.ca1.maxHttpConns=15 tps.connector.ca1.minHttpConns=1 tps.connector.ca1.nickName=subsystemCert cert-pki-tomcat tps.connector.ca1.port=8443 tps.connector.ca1.timeout=30 tps.connector.ca1.uri.enrollment=/ca/ee/ca/profileSubmitSSLClient tps.connector.ca1.uri.getcert=/ca/ee/ca/displayBySerial tps.connector.ca1.uri.renewal=/ca/ee/ca/profileSubmitSSLClient tps.connector.ca1.uri.revoke=/ca/ee/subsystem/ca/doRevoke tps.connector.ca1.uri.unrevoke=/ca/ee/subsystem/ca/doUnrevoke tps.connector.kra1.enable=true tps.connector.kra1.host=host1.EXAMPLE.com tps.connector.kra1.maxHttpConns=15 tps.connector.kra1.minHttpConns=1 tps.connector.kra1.nickName=subsystemCert cert-pki-tomcat tps.connector.kra1.port=8443 tps.connector.kra1.timeout=30 tps.connector.kra1.uri.GenerateKeyPair=/kra/agent/kra/GenerateKeyPair tps.connector.kra1.uri.TokenKeyRecovery=/kra/agent/kra/TokenKeyRecovery tps.connector.tks1.enable=true tps.connector.tks1.generateHostChallenge=true tps.connector.tks1.host=host1.EXAMPLE.com tps.connector.tks1.keySet=defKeySet tps.connector.tks1.maxHttpConns=15 tps.connector.tks1.minHttpConns=1 tps.connector.tks1.nickName=subsystemCert cert-pki-tomcat tps.connector.tks1.port=8443 tps.connector.tks1.serverKeygen=true tps.connector.tks1.timeout=30 tps.connector.tks1.tksSharedSymKeyName=sharedSecret tps.connector.tks1.uri.computeRandomData=/tks/agent/tks/computeRandomData tps.connector.tks1.uri.computeSessionKey=/tks/agent/tks/computeSessionKey tps.connector.tks1.uri.createKeySetData=/tks/agent/tks/createKeySetData tps.connector.tks1.uri.encryptData=/tks/agent/tks/encryptData
TPS profiles refer to these connectors by their IDs. For example
op.enroll.userKey.keyGen.signing.ca.conn=ca1
Multiple connector of the same kind (for example, multiple CA connectors) can be defined. This may be useful when one TPS instance serves multiple backend Certificate System servers for different groups of tokens.
Note
Automatic failover for connectors in TPS is currently not supported. A manual failover procedure must be performed to point the TPS to alternate CA, KRA, or TKS, as long as they are clones of the original systems.
6.10. Revocation Routing Configuration
To configure revocation routing, you must first define a list of relevant CA connectors and add them to the connector list in the following format:
tps.connCAList=ca1,ca2
Additionally, you must add the CA signing certificate to the TPS
nssdb and set up trust:
#cd <TPS instance directory>/alias
#certutil -d . -A -n <CA signing cert nickname> -t “CT,C,C” -i <CA signing cert b64 file name>
Finally, the nickname of the CA signing certificate must be added to the connector using the following option:
tps.connector.ca1.caNickname=caSigningCert cert-pki-tomcat CA
Note
During CA discovery, the TPS may automatically calculate the Authority Key Identifier of the CA and add it to the connector configuration. For example:
tps.connector.ca1.caSKI=i9wOnN0QZLkzkndAB1MKMcjbRP8=
This behavior is expected.
6.11. Setting Up Server-side Key Generation
Server-side key generation means that keys are generated by a Key Recovery Authority (KRA), an optional Certificate System subsystem. Generating keys by the KRA is necessary to allow recovery of keys on lost or damaged tokens, or key retrieval in the case of external registration. This section describes how to configure server-side key generation in TMS.
During TPS installation you are asked to specify whether you want to use key archival. If you confirm, setup will perform automatic basic configuration, specifically the following parameters:
- TPS connector parameters for the KRA:
tps.connector.kra1.enable=true tps.connector.kra1.host=host1.EXAMPLE.com tps.connector.kra1.maxHttpConns=15 tps.connector.kra1.minHttpConns=1 tps.connector.kra1.nickName=subsystemCert cert-pki-tomcat tps.connector.kra1.port=8443 tps.connector.kra1.timeout=30 tps.connector.kra1.uri.GenerateKeyPair=/kra/agent/kra/GenerateKeyPair tps.connector.kra1.uri.TokenKeyRecovery=/kra/agent/kra/TokenKeyRecovery
- TPS profile-specific parameters for server-side key generation:
op.enroll.userKey.keyGen.encryption.serverKeygen.archive=true op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=kra1 op.enroll.userKey.keyGen.encryption.serverKeygen.enable=true
Set theserverKeygen.enable=trueoption forserverKeygen.archiveto take effect.Important
The LunaSA HSM does not support a smaller key size than 2048 bits for RSA encryption.For example, to configure a key size of 2048 bits, set the following parameter in the/var/lib/pki/instance_name/tps/conf/CS.cfgfile:op.enroll.userKey.keyGen.encryption.keySize=2048
- TKS configuration:
- The following configures the nickname of the transport certificate used for communication between the TKS and KRA (via TPS):
tks.drm_transport_cert_nickname=transportCert cert-pki-tomcat KRA
The referenced transport certificate must also exist in the TKS instance security module. For example:transportCert cert-pki-tomcat KRA u,u,u
- KRA configuration
- Depending on the PKCS#11 token, parameters
kra.keygen.temporaryPairs,kra.keygen.sensitivePairs, andkra.keygen.extractablePairscan be customized for key generation options. These parameters are all set tofalseby default.The following values for these parameters have been tested with some of the security modules supported by Red Hat Certificate System:- NSS (when in FIPS mode):
kra.keygen.extractablePairs=true
- nCipher nShield Connect 6000 (works by default without specifying):
- For specifying RSA keys:
kra.keygen.temporaryPairs=true
(Do not specify any other parameters.)For generating ECC keys:kra.keygen.temporaryPairs=true kra.keygen.sensitivePairs=false kra.keygen.extractablePairs=true
- LunaSA CKE - Key Export Model (non-FIPS mode):
kra.keygen.temporaryPairs=true kra.keygen.sensitivePairs=true kra.keygen.extractablePairs=true
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.
Note
When LunaSA CKE – Key Export Model is in FIPS mode, pki private keys cannot be extracted.
6.12. Setting Up New Key Sets
This section describes setting up an alternative to the default key set in the Token Processing System (TPS) and in the Token Key Service (TKS).
- TKS configuration
- The default key set is configured in the TKS using the following options in the
/var/lib/pki/instance_name/tks/conf/CS.cfgfile:tks.defKeySet._000=## tks.defKeySet._001=## Axalto default key set: tks.defKeySet._002=## tks.defKeySet._003=## tks.defKeySet.mk_mappings.#02#01=<tokenname>:<nickname> tks.defKeySet._004=## tks.defKeySet.auth_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f tks.defKeySet.kek_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f tks.defKeySet.mac_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f tks.defKeySet.nistSP800-108KdfOnKeyVersion=00 tks.defKeySet.nistSP800-108KdfUseCuidAsKdd=false
The above configuration defines settings specific to a certain type or class of tokens that can be used in the TMS. The most important part are the 3 developer or (out of the box) session keys, which are used to create a secure channel before symmetric key handover takes place. A different type of key may have different default values for these keys.The settings describing thenistSP800key diversification method control whether this method or the standard Visa method is used. Specifically, the value of thetks.defKeySet.nistSP800-108KdfOnKeyVersionoption determines that the NIST version will be used. ThenistSP800-108KdfUseCuidAsKddoption allows you to use the legacy key ID value of CUID during processing. The newer KDD value is most commonly used and therefore this option is disabled (false) by default. This allows you to configure a new key set to enable support for a new class of keys.Example 6.2. Enabling Support for the
jForteClassTo enable support for thejForteclass, set:tks.jForte._000=## tks.jForte._001=## SAFLink's jForte default key set: tks.jForte._002=## tks.jForte._003=## tks.jForte.mk_mappings.#02#01=<tokenname>:<nickname> tks.jForte._004=## tks.jForte.auth_key=#30#31#32#33#34#35#36#37#38#39#3a#3b#3c#3d#3e#3f tks.jForte.kek_key=#50#51#52#53#54#55#56#57#58#59#5a#5b#5c#5d#5e#5f tks.jForte.mac_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f tks.jForte.nistSP800-108KdfOnKeyVersion=00 tks.jForte.nistSP800-108KdfUseCuidAsKdd=false
Note the difference in the 3 static session keys compared to the previous example.Certificate System supports the Secure Channel Protocol 03 (SCP03) for Giesecke & Devrient (G&D) Smart Cafe 6 smart cards. To enable SCP03 support for these smart cards in a TKS, set in the/var/lib/pki/instance_name/tks/conf/CS.cfgfile:tks.defKeySet.prot3.divers=emv tks.defKeySet.prot3.diversVer1Keys=emv tks.defKeySet.prot3.devKeyType=DES3 tks.defKeySet.prot3.masterKeyType=DES3
- TPS configuration
- The TPS must be configured to recognize the new key set when a supported client attempts to perform an operation on a token. The default
defKeySetis used most often.The primary method to determine thekeySetin the TPS involves Section 6.7, “Mapping Resolver Configuration”. See the linked section for a discussion of the exact settings needed to establish this resolver mechanism.If the KeySet Mapping Resolver is not present, several fallback methods are available for the TPS to determine the correctkeySet:- You can add the
tps.connector.tks1.keySet=defKeySetto theCS.cfgconfiguration file of the TPS. - Certain clients can possibly be configured to explicitly pass the desired
keySetvalue. However, the Enterprise Security Client does not have this ability at this point. - When the TPS calculates the proper
keySetbased on the desired method, all requests to the TKS to help create secure channels pass thekeySetvalue as well. The TKS can then use its ownkeySetconfiguration (described above) to determine how to proceed.
6.13. Setting Up a New Master Key
This section will describe the procedures and configuration required to set up a new master key in the Token Key Service (TKS). See the Red Hat Certificate System Planning, Installation, and Deployment Guide for background information.
Procedure 6.1. Creating a New Master Key
- Obtain internal the PIN required to access the TKS security databases:
#cat /var/lib/pki/pki-tomcat/tks/conf/password.confinternal=649713464822 internaldb=secret12 replicationdb=-752230707 - Open the
alias/directory of the TKS instance:#cd /var/lib/pki/pki-tomcat/alias - Generate a new master key using the
tkstoolutility. For example:#tkstool -M -n new_master -d /var/lib/pki/pki-tomcat/alias -h <token_name>Enter Password or Pin for "NSS Certificate DB": Generating and storing the master key on the specified token . . . Naming the master key "new_master" . . . Computing and displaying KCV of the master key on the specified token . . . new_master key KCV: CA5E 1764 - Verify that the keys have been properly added to the database:
#tkstool -L -d .slot: NSS User Private Key and Certificate Services token: NSS Certificate DB Enter Password or Pin for "NSS Certificate DB": <0> new_master
6.13.1. Generating and Transporting Wrapped Master Keys (Key Ceremony)
If a master key is going to be used on an external token or in multiple locations, then it must be wrapped so that it can be safely transported to the hardware tokens. The
tkstool utility can be used to generate transport keys, which are then used to send the master key to the facility where the tokens are generated. The process of transferring wrapped master keys is commonly called a Key Ceremony.
Note
Transport keys can only be used with the master key they were generated with.
Procedure 6.2. Generating and Transporting Wrapped Master Keys
- Obtain the internal PIN required to access the Token Key Service security databases:
#cat /var/lib/pki/pki-tomcat/tks/conf/password.conf - Open the TKS instance
alias/directory:#cd /var/lib/pki/pki-tomcat/alias - Create a transport key named
transport:#tkstool -T -d . -n transportNote
Thetkstoolutility prints out the key shares and KCV values for each of the three session keys generated. Save them to a file as they are necessary to regenerate the transport key in new databases later in this procedure, and to regenerate the key if lost. - When prompted, fill in the database password. Then, follow on-screen instructions to generate a random seed.
A random seed must be generated that will be used in the creation of your key. One of the easiest ways to create a random seed is to use the timing of keystrokes on a keyboard. To begin, type keys on the keyboard until this progress meter is full. DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD! Continue typing until the progress meter is full: |************************************************************| Finished. Type the word "proceed" and press enter
- The next prompt will generate a series of session keys. Follow on-screen instructions until the final message:
Successfully generated, stored, and named the transport key!
- Use the transport key to generate and wrap a master key and store it in a file named
file:#tkstool -W -d . -n new_master -t transport -o file - Copy the wrapped master key over to the appropriate locations or facility.
- If necessary, generate new security databases on the HSM or at the facility:
#tkstool -N -d <directory>Alternatively, add the-Ioption to produce a key identical to the one generated originally in a the new database. Regenerating the transport key in this way requires that you input the session key share and KCV for each of the session keys generated earlier in this procedure.#tkstool -I -d <directory> -n verify_transport - Use the transport key to unwrap the master key stored in the file. Provide the security database PIN when prompted:
#tkstool -U -d directory -n new_master -t verify_transport -i file - Verify that the keys have been added to the database properly:
#tkstool -L -d
6.15. Using Different Applets for Different SCP Versions
In Certificate System, the following parameter in the
/var/lib/instance_name/tps/conf/CS.cfg file specifies which applet should be loaded for all Secure Channel Protocol (SCP) versions for each token operation:
op.operation.token_type.update.applet.requiredVersion=version
However, you can also set individual applets for specific SCP versions, by adding the following parameter:
op.operation.token_type.update.applet.requiredVersion.prot.protocol_version=version
Certificate System supports setting individual protocol versions for the following operations:
formatenrollpinReset
Example 6.3. Setting Protocol Versions for Enrollment Operations
To configure a specific applet for SCP03 and a different applet for all other protocols when performing enrollment operations for the
userKey token:
- Edit the
/var/lib/instance_name/tps/conf/CS.cfgfile:- Set the
op.enroll.userKey.update.applet.requiredVersionparameter to specify the applet used by default. For example:op.enroll.userKey.update.applet.requiredVersion=1.4.58768072
- Set the
op.enroll.userKey.update.applet.requiredVersion.prot.3parameter to configure the applet Certificate System uses for the SCP03 protocol. For example:op.enroll.userKey.update.applet.requiredVersion.prot.3=1.5.558cdcff
- Restart Certificate System:
pki-server restart instance_name
For details about enabling SCP03 for Giesecke & Devrient (G&D) Smart Cafe 6 smart cards in a TKS, see Section 6.12, “Setting Up New Key Sets”.
Chapter 7. 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.
7.1. About Revoking Certificates
Certificates can be revoked by an end user (the original owner of the certificate) or by a Certificate Manager agent. End users can revoke certificates by using the revocation form provided in the end-entities page. Agents can revoke end-entity certificates by using the appropriate form in the agent services interface. Certificate-based (SSL/TLS client authentication) is required in both cases.
An end user can revoke only certificates that contain the same subject name as the certificate presented for authentication. After successful authentication, the server lists the certificates belonging to the end user. The end user can then select the certificate to be revoked or can revoke all certificates in the list. The end user can also specify additional details, such as the date of revocation and revocation reason for each certificate or for the list as a whole.
Agents can revoke certificates based on a range of serial numbers or based on subject name components. When the revocation request is submitted, agents receive a list of certificates from which they can pick the ones to be revoked. For instructions on how agents revoke end-entity certificates, see the Red Hat Certificate System Planning, Installation, and Deployment Guide.
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 7.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 Section 7.3.4, “Setting a CA to Use a Different Certificate to Sign CRLs”.
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.
7.1.1. User-Initiated Revocation
When an end user submits a certificate revocation request, the first step in the revocation process is for the Certificate Manager to identify and authenticate the end user to verify that the user is attempting to revoke his own certificate, not a certificate belonging to someone else.
In SSL/TSL client authentication, the server expects the end user to present a certificate that has the same subject name as the one to be revoked and uses that for authentication purposes. The server verifies the authenticity of a revocation request by mapping the subject name in the certificate presented for client authentication to certificates in its internal database. The server revokes the certificate only if the certificate maps successfully to one or more valid or expired certificates in its internal database.
After successful authentication, the server lists the valid or expired certificates that match the subject name of the certificate presented for client authentication. The user can then either select the certificates to be revoked or revoke all certificates in the list.
7.1.2. Reasons for Revoking a Certificate
A Certificate Manager can revoke any certificate it has issued. There are generally accepted reason codes for revoking a certificate that are often included in the CRL, such as the following:
0. Unspecified; no particular reason is given.1. The private key associated with the certificate was compromised.2. The private key associated with the CA that issued the certificate was compromised.3. The owner of the certificate is no longer affiliated with the issuer of the certificate and either no longer has rights to the access gained with the certificate or no longer needs it.4. Another certificate replaces this one.5. The CA that issued the certificate has ceased to operate.6. The certificate is on hold pending further action. It is treated as revoked but may be taken off hold in the future so that the certificate is active and valid again.8. The certificate is going to be removed from the CRL because it was removed from hold. This only occurs in delta CRLs.9. The certificate is revoked because the privilege of the owner of the certificate has been withdrawn.
A certificate can be revoked by administrators, agents, and end entities. Agents and administrators with agent privileges can revoke certificates using the forms in the agent services page. End users can revoke certificates using the forms in the Revocation tab of the end-entity interface. End users can revoke only their own certificates, whereas agents and administrators can revoke any certificates issued by the server. End users are also required to authenticate to the server in order to revoke a certificate.
Whenever a certificate is revoked, the Certificate Manager updates the status of the certificate in its internal database. The server uses the entries in the internal database to track of all revoked certificates, and, when configured, it makes the CRLs public by publishing it to a central repository to notify other users that the certificates in the list are no longer valid.
7.1.3. 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.
7.1.4. 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.
7.1.5. 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 9, 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 9.8, “Setting up Resumable CRL Downloads”.
7.1.6. Certificate Revocation Pages
The end-entities page of the Certificate Manager includes default HTML forms for revocation authenticated by an SSL/TLS client. The forms are accessible from the Revocation tab. You can see the form for such a revocation by clicking the User Certificate link.
To change the form appearance to suit organization's requirements, edit the
UserRevocation.html, the form that allows the SSL/TSL client authenticated revocation of client or personal certificates. The file is in the /var/lib/instance_name/webapps/subsystem_type/ee/subsystem_type directory.
7.2. 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 Enabling the CMC Shared Secret Feature.
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 7.2.1, “Revoking a Certificate UsingCMCRequest”.CMCRevoke. For details, see Section 7.2.2, “Revoking a Certificate UsingCMCRevoke”.
Important
Red Hat recommends using the
CMCRequest utility to generate CMC revocation requests, because it provides more options than CMCRevoke.
7.2.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 cert9.db, key4.db and pkcs11.txt dbdir=/home/user_name/.dogtag/nssdb/ #password: password for cert9.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, theCMCRequestutility stores the CMC request in the file specified in theoutputparameter 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 SSL client authentication certificate #can be found (default is internal) #This parameter will be ignored if secure=false tokenname=internal #dbdir: directory for cert9.db, key4.db and pkcs11.txt #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 cert9.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 thesecureandclientmodeparameters totrueand, additionally, fill thenicknameparameter. - Depending on who signed the request, the
servletparameter in the configuration file forHttpClientmust 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/profileSubmitSelfSignedCMCFull
- 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.
7.2.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).
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— unspecified1— the key was compromised2— the CA key was compromised3— the employee's affiliation changed4— the certificate has been superseded5— cessation of operation6— the certificate is on hold
The available tool arguments are described in detail in the Command-Line Tools Guide.
7.2.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 isAgentCert, and the serial number of the certificate is22, 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.
http
s://server.example.com:8443/ca/ee/ca - Select the Revocation tab.
- Select the CMC Revoke link on the menu.
- Paste the output from the
CMCRevokeinto the text area. - Remove
-----BEGIN NEW CERTIFICATE REQUEST-----and----END NEW CERTIFICATE REQUEST-----from the pasted content. - Click .
- The returned page should confirm that correct certificate has been revoked.
7.3. Issuing CRLs
- The Certificate Manager uses its CA signing certificate 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 Section 7.3.4, “Setting a CA to Use a Different Certificate to Sign CRLs” for more information.
- Set up CRL issuing points. An issuing point is already set up and enabled for a master CRL.
Figure 7.1. Default CRL Issuing Point
Additional issuing points for the CRLs can be created. See Section 7.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 7.3.2, “Configuring CRLs for Each Issuing Point” for details.
- Set up the CRL extensions which are configured for the issuing point. See Section 7.3.3, “Setting CRL Extensions” for details.
- Set up the delta CRL for an issuing point by enabling extensions for that issuing point,
DeltaCRLIndicatororCRLNumber. - Set up the
CRLDistributionPointextension to include information about the issuing point. - Set up publishing CRLs to files, an LDAP directory, or an OCSP responder. See Chapter 9, Publishing Certificates and CRLs for details about setting up publishing.
7.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 . 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 . The CRL Issuing Point Editor window opens.
Figure 7.2. 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 .
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 7.3.2, “Configuring CRLs for Each Issuing Point” for details on configuring an issuing point. See Section 7.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.
Note
pkiconsole is being deprecated.
7.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
nextUpdatefield in the generated CRLs. ThenextUpdateparameter 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, enablingExtend next update time in full CRLswill make thenextUpdateparameter in a full CRL show when the next full CRL will be issued. Otherwise, thenextUpdateparameter 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
- 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, theUpdate CRL every time a certificate is revoked or released from holdoption also requires you to fill out the twograce periodsettings. Thus, in order to select this option you need to first select theUpdate CRL everyoption and enter a number for theNext update grace period # minutesbox. - The Cache tab sets whether caching is enabled and the cache frequency.
Figure 7.3. 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 7.1, “About Revoking Certificates”.
- Update cache every. This field sets how frequently the cache is written to the internal database. Set to
0to 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 7.4. 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 7.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 .
- Extensions are allowed for this issuing point and can be configured. See Section 7.3.3, “Setting CRL Extensions” for details.
Note
pkiconsole is being deprecated.
7.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 7.5. CRL Extensions
- To modify a rule, select it, and click .
- 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 .
- Click to see the updated status of all the rules.
Note
pkiconsole is being deprecated.
7.3.4. Setting a CA to Use a Different Certificate to Sign CRLs
For instruction on how to configure this feature by editing the
CS.cfg file, see the Setting a CA to Use a Different Certificate to Sign CRLs section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
7.3.5. 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.
7.3.5.1. Configuring CRL Generation from Cache in the Console
Note
pkiconsole is being deprecated.
- 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.
7.3.5.2. Configuring CRL Generation from Cache in CS.cfg
For instruction on how to configure this feature by editing the
CS.cfg file, see the Configuring CRL Generation from Cache in CS.cfg section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
7.4. Setting Full and Delta CRL Schedules
CRLs are generated periodically. Setting that period is touched on in the configuration in Section 7.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.
7.4.1. Configuring CRL Update Intervals in the Console
Note
pkiconsole is being deprecated.
- 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.
7.4.2. Configuring Update Intervals for CRLs in CS.cfg
For instruction on how to configure this feature by editing the
CS.cfg file, see the Configuring Update Intervals for CRLs in CS.cfg section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
7.4.3. Configuring CRL Generation Schedules over Multiple Days
By default, CRL generation 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
The semicolon and asterisk syntax works in both the console and when manually editing the
CS.cfg file.
7.5. Enabling Revocation Checking
Revocation checking means that a Certificate System subsystem verifies that a certificate is both valid and not revoked when an agent or administrator attempts to access the instance's secure interfaces. This leverages a local OCSP service (either a CA's internal OCSP service or a separate OCSP responder) to check the revocation status of the certificate.
OCSP configuration is covered in Section 7.6, “Using the Online Certificate Status Protocol (OCSP) Responder”.
See Enabling Automatic Revocation Checking on the CA in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
See Enabling Certificate Revocation Checking for Subsystems in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
7.6. Using the Online Certificate Status Protocol (OCSP) Responder
7.6.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 9, 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 7.6.4, “Enabling the Certificate Manager's Internal OCSP Service”).
- Configure the OCSP Responder.
- Configure the Revocation Info store (Section 7.6.2.2, “Configure the Revocation Info Stores: Internal Database” and Section 7.6.2.3, “Configure the Revocation Info Stores: LDAP Directory”).
- Identify every publishing Certificate Manager to the OCSP responder (Section 7.6.2, “Identifying the CA to the OCSP Responder”).
- If necessary, configure the trust settings for the CA which signed the OCSP signing certificate (Section 17.7, “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 7.6.2.1, “Verify Certificate Manager and Online Certificate Status Manager Connection”).
7.6.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 SSL/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 .
- 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).
7.6.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 SSL/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.
7.6.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 the
defStorevalues.
- 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.byNameparameter. IfbyNameparameter is true or is missing, the OCSP authority signing certificate subject name is used as the ResponderID field of the OCSP response. IfbyNameparameter 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.
Note
pkiconsole is being deprecated.
7.6.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 to enable the
ldapStoreoption. - Select
ldapStore, and click . - Set the
ldapStoreparameters.
- 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-SSL/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.byNameparameter. IfbyNameparameter is true or is missing, the OCSP authority signing certificate subject name is used as the ResponderID field of the OCSP response. IfbyNameparameter 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.
Note
pkiconsole is being deprecated.
7.6.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.
7.6.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 the
notFoundAsGoodvalue. Selecting the checkbox means that the OCSP returns a value ofGOODeven if the serial number on the certificate is bad. Unselecting the checkbox means that the OCSP sends a value ofUNKNOWN, which the client can intrepret as an error. - Restart the OCSP Manager.
]# pki-server restart instance-name
Note
pkiconsole is being deprecated.
7.6.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-SSL/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:
http
s://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 URINamevalue, such ashttp.s://server.example.com:8443/ca/ocsp - Update the enrollment profiles to enable the Authority Information Access extension, and set the
Locationparameter 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.
]# pki-server restart instance-name
Note
To disable the Certificate Manager's internal OCSP service, edit the CA's
CS.cfg file and change the value of the ca.ocsp parameter to false.
ca.ocsp=false
7.6.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:
| 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 |
7.6.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
curlto 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
For certificates issued by a 7.1 CA with the Authority Information Access extension to be sent to the OCSP with the GET method, a redirect needs to be created to forward the requests to the appropriate URL, as described in Section 7.6.7, “Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier”.
7.6.7. Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier
The location for the OCSP user pages, specified in the URL with the file root
/ocsp/ee/ocsp/, is different in Certificate System 10 or Certificate System 8.1 than the location in Certificate System 7.1, which was simply /ocsp/. In order for certificates issued by a 7.1 or earlier CA with the Authority Information Access extension to be sent to the OCSP, create a redirect to forward the requests to the appropriate URL.
Note
Setting the redirect is only required to manage certificates issued by a 7.1 or earlier CA with the Authority Information Access extension. If the certificates are issued by a later version Certificate Manager or do not contain the Authority Information Access extension, then this configuration is not necessary.
- Stop the OCSP Responder.
]# pki-server stop instance-name
- Change to the OCSP's end user web applications directory. For example:
]# cd /var/lib/pki-ocsp/webapps/ocsp
- Change to the
ROOT/WEB-INF/directory in theROOTfolder of the OCSP's web applications directory. For example:]# cd /var/lib/pki-ocsp/webapps/ocsp/ROOT/WEB-INF/
- Create and open the
lib/directory in theROOTfolder of the OCSP's web applications directory.]# mkdir lib ]# cd lib/
- Create a symlink that links back to the
/usr/share/java/pki/cms.jarJAR file. For example:]# ln -s /usr/share/java/pki/cms.jar cms.jar
- Move up to the main web application directory. For example:
]# cd /var/lib/pki-ocsp/webapps/ocsp/
- Rename the current instance (
ocsp) directory. For example:]# mv /var/lib/pki-ocsp/webapps/ocsp/ocsp /var/lib/pki-ocsp/webapps/ocsp/ocsp2
- Change to the
WEB-INF/directory in the originalocsp/directory. For example:]# cd /var/lib/pki-ocsp/webapps/ocsp/ocsp/WEB-INF
- In the original
ocsp/WEB-INF/directory, edit theweb.xmlfile and add lines mapping between theeeocspAddCRLandcsadmin-wizardservlets.<servlet-mapping> <servlet-name> ocspOCSP </servlet-name> <url-pattern> /ee/ocsp/* </url-pattern> </servlet-mapping> - Create and install the
web.xmlfile in theROOTdirectory. For example:<?xml version="1.0" encoding="ISO-8859-1"?> <web-app> <display-name>Welcome to Tomcat</display-name> <description> Welcome to Tomcat </description> <servlet> <servlet-name>ocspProxy</servlet-name> <servlet-class>com.netscape.cms.servlet.base.ProxyServlet</servlet-class> <init-param> <param-name>destContext</param-name> <param-value>/ocsp2</param-value> </init-param> <init-param> <param-name>destServlet</param-name> <param-value>/ee/ocsp</param-value> </init-param> </servlet> <servlet> <servlet-name>ocspOther</servlet-name> <servlet-class>com.netscape.cms.servlet.base.ProxyServlet</servlet-class> <init-param> <param-name>destContext</param-name> <param-value>/ocsp2</param-value> </init-param> <init-param> <param-name>srcContext</param-name> <param-value>/ocsp</param-value> </init-param> <init-param> <param-name>destServlet</param-name> <param-value></param-value> </init-param> <init-param> <param-name>matchURIStrings</param-name> <param-value>/ocsp/registry,/ocsp/acl,/ocsp/jobsScheduler,/ocsp/ug,/ocsp/server,/ocsp/log, /ocsp/auths,/ocsp/start,/ocsp/ocsp,/ocsp/services,/ocsp/agent,/ocsp/ee, /ocsp/admin</param-value> </init-param> <init-param> <param-name>destServletOnNoMatch</param-name> <param-value>/ee/ocsp</param-value> </init-param> <init-param> <param-name>appendPathInfoOnNoMatch</param-name> <param-value>/ocsp</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>ocspProxy</servlet-name> <url-pattern>/ocsp</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>ocspOther</servlet-name> <url-pattern>/ocsp/*</url-pattern> </servlet-mapping> </web-app> - Edit the
/var/lib/pki-ocsp/conf/context.xmlfile, changing the following line:<Context> to <Context crossContext="true" > - Edit the
/var/lib/pki-ocsp/webapps/ocsp/ocsp2/services.templatefile and change the following line:result.recordSet[i].uri); to result.recordSet[i].uri + "/"); - Start the OCSP instance.
]# pki-server start instance-name
Chapter 8. Managing PKI ACME Responder
This chapter describes how to manage PKI ACME Responder.
For information on how to set up PKI ACME Responder, see the Setting up PKI ACME Responder chapter in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
8.1. Enabling/Disabling ACME Services
Users that belong to the Administrators group can enable or disable services in the ACME responder. The user can authenticate either with basic authentication or client certificate authentication.
- To enable or disable ACME services with basic authentication, specify the username and password:
$ pki -u <username> -p <password> acme-<enable/disable>
- To enable or disable ACME services with client certificate authentication, specify the certificate nickname and NSS database password:
$ pki -n <nickname> -c <password> acme-<enable/disable>
8.2. Checking the Status of PKI ACME Responder
- To check the status of the ACME responder, run the following command:
$ pki acme-info Status: Available Terms of Service: https://www.example.com/acme/tos.pdf Website: https://www.example.com CAA Identities: example.com External Account Required:false
If the services are disabled, the command will show the following result:$ pki acme-info Status: Unavailable
Note
The actual output depends on what is configured in the
metadata.conf configuration file.
Part III. Additional Configuration to Manage CA Services
Chapter 9. Publishing Certificates and CRLs
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 7, 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.
9.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. For details, see Chapter 13, Setting Automated Jobs.
Setting up publishing involves configuring publishers, mappers, and rules.
9.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.
9.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.
9.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.
9.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.derorcert-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 number1234iscert-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
.deror 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 valueThis Update: Friday January 28 15:36:00 PST 2020, isMasterCRL-20200128-153600.der.
9.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 7.6, “Using the Online Certificate Status Protocol (OCSP) Responder”.
9.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 SSL (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 9.12.2, “Manually Updating the CRL in the Directory”.
9.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 to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
- Select the
FileBasedPublishermodule, 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 9.5, “Creating Rules”.
Note
pkiconsole is being deprecated.
9.3. Configuring Publishing to an OCSP
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 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.
9.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 to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
- Select the
OCSPPublishermodule, 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 15.3.2.1, “Creating Users”.
After configuring the publisher, configure the rules for the published certificates and CRLs, as described in Section 9.5, “Creating Rules”.
Note
pkiconsole is being deprecated.
9.4. Configuring Publishing to an LDAP Directory
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.
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 9.4.3, “Creating Mappers”.
- Create rules to connect publishers to mappers, as described in Section 9.5, “Creating Rules”.
- Enable publishing, as described in Section 9.6, “Enabling Publishing”.
9.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
cncomponent, create a newpersonentry for the CA. Selecting a different type of entry may not allow thecncomponent to be specified. - If the CA's DN begins with the
oucomponent, create a neworganizationalunitentry for the CA.
The entry does not have to be in thepkiCAorcertificationAuthorityobject class. The Certificate Manager will convert this entry to thepkiCAorcertificationAuthorityobject class automatically by publishing its CA's signing certificate.Note
ThepkiCAobject class is defined in RFC 4523, while thecertificationAuthorityobject 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 namedinetOrgPersonallows this attribute. ThestrongAuthenticationUserobject 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 theuserCertificate;binaryattribute, 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 thepkiCAorcertificationAuthorityobject 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 thepkiCAorcertificationAuthorityobject class. The value of the attribute is the DER-encoded binary X.509 CRL. The CA's entry must already contain thepkiCAorcertificationAuthorityobject 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 thedeltaCRLorcertificationAuthority-V2object 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); SSL without client authentication (simple username and password); and SSL with client authentication (certificate-based).See the Red Hat Directory Server documentation for instructions on setting up these methods of communication with the server.
9.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.
| 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. |
9.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 9.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 . 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 .
See Section C.2, “Mapper Plug-in Modules ” for detailed information about each mapper.
Note
pkiconsole is being deprecated.
9.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 9.5, “Creating Rules”.
Once the configuration is complete, enable publishing, as described in Section 9.6, “Enabling Publishing”.
9.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 . This opens the Rule Editor window.
- To create a rule, click . This opens the Select Rule Plug-in Implementation window.
Select theRulemodule. 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 isxcert. For all other types of certificates, the value iscerts. For CRLs, specifycrl. - 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 9.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 9.3, “Predicate Expressions” lists the predicates that can be used to identify CRL issuing points and delta CRLs and certificate profiles.
| 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.
|
Note
pkiconsole is being deprecated.
9.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 7, 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 SSL client authenticated communication, the name must match the
cncomponent in the subject DN of the Directory Server's SSL 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.conffile. For example:CA LDAP Publishing:password
Note
The parameter name which identifies the publishing password (CA LDAP Publishing) is set in the Certificate Manager'sCS.cfgfile in theca.publish.ldappublish.ldap.ldapauth.bindPWPromptparameter, and it can be edited. - Client certificate. This sets the certificate the Certificate Manager uses for SSL client authentication to the publishing directory. By default, the Certificate Manager uses its SSL server certificate.
- LDAP version. Select LDAP version 3.
- Authentication. The way the Certificate Manager authenticates to the Directory Server. The choices are
Basic authenticationandSSL client authentication.If the Directory Server is configured for basic authentication or for SSL communication without client authentication, selectBasic authenticationand specify values for the Directory manager DN and password.If the Directory Server is configured for SSL communication with client authentication, selectSSL client authenticationand theUse SSL communicationoption, and identify the certificate that the Certificate Manager must use for SSL 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.
Note
pkiconsole is being deprecated.
9.7. Enabling a Publishing Queue
Part of the enrollment process includes publishing the issued certificate to any directories or files. This, essentially, closes out the initial certificate request. However, publishing a certificate to an external network can significantly slow down the issuance process — which leaves the request open.
To avoid this situation, administrators can enable a publishing queue. The publishing queue separates the publishing operation (which may involve an external LDAP directory) from the request and enrollment operations, which uses a separate request queue. The request queue is updated immediately to show that the enrollment process is complete, while the publishing queue sends the information at the pace of the network traffic.
The publishing queue sets a defined, limited number of threads that publish generated certificates, rather than opening a new thread for each approved certificate.
The publishing queue is disabled by default. It can be enabled in the CA Console, along with enabling publishing.
Note
pkiconsole is being deprecated.
Note
While the publishing queue is disabled by default, the queue is automatically enabled if LDAP publishing is enabled in the Console. Otherwise, the queue can be enabled manually.
Figure 9.1. Enabling the Publishing Queue
Note
Enabling the publishing queue by editing the
CS.cfg file allows administrators to set other options for publishing, like the number of threads to use for publishing operations and the queue page size.
For instruction on how to configure this feature by editing the
CS.cfg file, see the Enabling and Configuring a Publishing Queue section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
9.8. 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.
9.8.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 9.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 SSL for the connection, so it is not necessary to configure SSL between the host and client. |
| -d | Prints debug information. |
9.9. 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 and create a new rule.
- Select xcerts from the type drop-down menu.
- Make sure the enable checkbox is selected.
- Select LdapCaCertMap from the mapper drop-down menu.
- 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.
For more information on using cross-pair certificates, see Section 17.5, “Using Cross-Pair Certificates”.
For more information on creating cross-pair certificate profiles, see the Configuring Cross-Pair profiles section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.
Note
pkiconsole is being deprecated.
<