Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

13.2. CS.cfg Files

The runtime properties of a Certificate System subsystem are governed by a set of configuration parameters. These parameters are stored in a file that is read by the server during startup, CS.cfg.
The CS.cfg, an ASCII file, is created and populated with the appropriate configuration parameters when a subsystem is first installed. The way the instance functions are modified is by making changes through the subsystem console, which is the recommended method. The changes made in the administrative console are reflected in the configuration file.
It is also possible to edit the CS.cfg configuration file directly, and in some cases this is the easiest way to manage the subsystem.

13.2.1. Locating the CS.cfg File

Each instance of a Certificate System subsystem has its own configuration file, CS.cfg. The contents of the file for each subsystem instance is different depending on the way the subsystem was configured, additional settings and configuration (like adding new profiles or enabling self-tests), and the type of subsystem.
The CS.cfg file is located in the configuration directory for the instance. 
/var/lib/pki/instance_name/subsystem_type/conf
Copy to Clipboard
For example: 
/var/lib/pki/instance_name/ca/conf
Copy to Clipboard

13.2.2. Editing the Configuration File

Warning

Do not edit the configuration file directly without being familiar with the configuration parameters or without being sure that the changes are acceptable to the server. The Certificate System fails to start if the configuration file is modified incorrectly. Incorrect configuration can also result in data loss.
To modify the CS.cfg file:
  1. Stop the subsystem instance. 
    # systemctl stop pki-tomcatd@instance_name.service
    Copy to Clipboard
    OR (if using nuxwdog watchdog) 
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard
    The configuration file is stored in the cache when the instance is started. Any changes made to the instance through the Console are changed in the cached version of the file. When the server is stopped or restarted, the configuration file stored in the cache is written to disk. Stop the server before editing the configuration file or the changes will be overwritten by the cached version when the server is stopped.
  2. Open the /var/lib/pki/instance_name/subsystem_type/conf directory.
  3. Open the CS.cfg file in a text editor.
  4. Edit the parameters in the file, and save the changes.
  5. Start the subsystem instance. 
    # systemctl start pki-tomcatd@instance_name.service
    Copy to Clipboard
    OR (if using nuxwdog watchdog) 
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard

13.2.3. Overview of the CS.cfg Configuration File

Each subsystem instances has its own main configuration file, CS.cfg, which contains all of the settings for the instance, such as plug-ins and Java classes for configuration. The parameters and specific settings are different depending on the type of subsystem, but, in a general sense, the CS.cfg file defines these parts of the subsystem instance:
  • Basic subsystem instance information, like its name, port assignments, instance directory, and hostname
  • Logging
  • Plug-ins and methods to authenticate to the instance's user directory (authorization)
  • The security domain to which the instance belongs
  • Subsystem certificates
  • Other subsystems used by the subsystem instance
  • Database types and instances used by the subsystem
  • Settings for PKI-related tasks, like the key profiles in the TKS, the certificate profiles in the CA, and the required agents for key recovery in the KRA
Many of the configuration parameters (aside from the ones for PKI tasks) are very much the same between the CA, OCSP, KRA, and TKS because they all use a Java-based console, so configuration settings which can be managed in the console have similar parameters.
The CS.cfg file a basic parameter=value format. 
#comment
parameter=value
Copy to Clipboard
In the CS.cfg file, many of the parameter blocks have descriptive comments, commented out with a pound (#) character. Comments, blank lines, unknown parameters, or misspelled parameters are ignored by the server.

Note

A bug in the TPS prevents it from ignoring lines which are commented out in the CS.cfg file. Rather than commenting out lines in the TPS CS.cfg file, simply delete those lines.
Parameters that configure the same area of the instance tend to be grouped together into the same block.

Example 13.1. Logging Settings in the CS.cfg File

log.instance.System._000=##
log.instance.System._001=## System Logging
log.instance.System._002=##
log.instance.System.bufferSize=512
log.instance.System.enable=true
log.instance.System.expirationTime=0
log.instance.System.fileName=/var/lib/pki-ca/logs/system
log.instance.System.flushInterval=5
log.instance.System.level=3
log.instance.System.maxFileSize=2000
log.instance.System.pluginName=file
log.instance.System.rolloverInterval=2592000
log.instance.System.type=system
Copy to Clipboard
Some areas of functionality are implemented through plug-ins, such as self-tests, jobs, and authorization to access the subsystem. For those parameters, the plug-in instance has a unique identifier (since there can be multiple instances of even the same plug-in called for a subsystem), the implementation plug-in name, and the Java class.

Example 13.2. Subsystem Authorization Settings

authz.impl._000=##
authz.impl._001=## authorization manager implementations
authz.impl._002=##
authz.impl.BasicAclAuthz.class=com.netscape.cms.authorization.BasicAclAuthz
authz.instance.BasicAclAuthz.pluginName=BasicAclAuthz
Copy to Clipboard

Note

The values for configuration parameters must be properly formatted, so they must obey two rules:
  • The values that need to be localized must be in UTF8 characters.
  • The CS.cfg file supports forward slashes (/) in parameter values. If a back slash (\) is required in a value, it must be escaped with a back slash, meaning that two back slashes in a row must be used.
The following sections are snapshots of CS.cfg file settings and parameters. These are not exhaustive references or examples of CS.cfg file parameters. Also, the parameters available and used in each subsystem configuration file is very different, although there are similarities.

13.2.3.1. Basic Subsystem Settings

Basic settings are specific to the instance itself, without directly relating to the functionality or behavior of the subsystem. This includes settings for the instance name, root directory, the user ID for the process, and port numbers. Many of the settings assigned when the instance is first installed or configured are prefaced with pkispawn.

Example 13.3. Basic Instance Parameters for the CA: pkispawn file ca.cfg

[DEFAULT]
pki_admin_password=Secret.123
pki_client_pkcs12_password=Secret.123
pki_ds_password=Secret.123
# Optionally keep client databases
pki_client_database_purge=False
# Separated CA instance name and ports
pki_instance_name=pki-ca
 pki_http_port=18080
pki_https_port=18443
# This Separated CA instance will be its own security domain
pki_security_domain_https_port=18443

[Tomcat]
# Separated CA Tomcat ports
pki_ajp_port=18009
pki_tomcat_server_port=18005
Copy to Clipboard

Important

While information like the port settings is included in the CS.cfg file, it is not set in the CS.cfg. The server configuration is set in the server.xml file.
The ports in CS.cfg and server.xml must match for a working RHCS instance.

13.2.3.2. Logging Settings

There are several different types of logs that can be configured, depending on the type of subsystem. Each type of log has its own configuration entry in the CS.cfg file.
For example, the CA has this entry for transaction logs, which allows log rotation, buffered logging, and log levels, among other settings: 
log.instance.Transactions._000=##
log.instance.Transactions._001=## Transaction Logging
log.instance.Transactions._002=##
log.instance.Transactions.bufferSize=512
log.instance.Transactions.enable=true
log.instance.Transactions.expirationTime=0
log.instance.Transactions.fileName=/var/log/pki/pki-tomcat/ca/logs/transactions
log.instance.Transactions.flushInterval=5
log.instance.Transactions.level=1
log.instance.Transactions.maxFileSize=2000
log.instance.Transactions.pluginName=file
log.instance.Transactions.rolloverInterval=2592000
log.instance.Transactions.type=transaction
Copy to Clipboard
For more information about these parameters and their values, see Section 17.1, “Certificate System Log Settings”. As long as audit logging is enabled, these values do not affect compliance.

13.2.3.3. Authentication and Authorization Settings

The CS.cfg file sets how users are identified to access a subsystem instance (authentication) and what actions are approved (authorization) for each authenticated user.
A CS subsystem uses authentication plug-ins to define the method for logging into the subsystem.
The following example shows an authentication instance named SharedToken that instantiates a JAVA plug-in named SharedSecret. 
auths.impl.SharedToken.class=com.netscape.cms.authentication.SharedSecret
auths.instance.SharedToken.pluginName=SharedToken
auths.instance.SharedToken.dnpattern=
auths.instance.SharedToken.ldap.basedn=ou=People,dc=example,dc=org
auths.instance.SharedToken.ldap.ldapauth.authtype=BasicAuth
auths.instance.SharedToken.ldap.ldapauth.bindDN=cn=Directory Manager
auths.instance.SharedToken.ldap.ldapauth.bindPWPrompt=Rule SharedToken
auths.instance.SharedToken.ldap.ldapauth.clientCertNickname=
auths.instance.SharedToken.ldap.ldapconn.host=server.example.com
auths.instance.SharedToken.ldap.ldapconn.port=636
auths.instance.SharedToken.ldap.ldapconn.secureConn=true
auths.instance.SharedToken.ldap.ldapconn.version=3
auths.instance.SharedToken.ldap.maxConns=
auths.instance.SharedToken.ldap.minConns=
auths.instance.SharedToken.ldapByteAttributes=
auths.instance.SharedToken.ldapStringAttributes=
auths.instance.SharedToken.shrTokAttr=shrTok
Copy to Clipboard
For some authorization settings, it is possible to select an authorization method that uses an LDAP database to store user entries, in which case the database settings are configured along with the plug-in as shown below. 
authz.impl.DirAclAuthz.class=com.netscape.cms.authorization.DirAclAuthz
authz.instance.DirAclAuthz.ldap=internaldb
authz.instance.DirAclAuthz.pluginName=DirAclAuthz
authz.instance.DirAclAuthz.ldap._000=##
authz.instance.DirAclAuthz.ldap._001=## Internal Database
authz.instance.DirAclAuthz.ldap._002=##
authz.instance.DirAclAuthz.ldap.basedn=dc=server.example.com-pki-ca
authz.instance.DirAclAuthz.ldap.database=server.example.com-pki-ca
authz.instance.DirAclAuthz.ldap.maxConns=15
authz.instance.DirAclAuthz.ldap.minConns=3
authz.instance.DirAclAuthz.ldap.ldapauth.authtype=SslClientAuth
authz.instance.DirAclAuthz.ldap.ldapauth.bindDN=cn=Directory Manager
authz.instance.DirAclAuthz.ldap.ldapauth.bindPWPrompt=Internal LDAP Database
authz.instance.DirAclAuthz.ldap.ldapauth.clientCertNickname=
authz.instance.DirAclAuthz.ldap.ldapconn.host=localhost
authz.instance.DirAclAuthz.ldap.ldapconn.port=11636
authz.instance.DirAclAuthz.ldap.ldapconn.secureConn=true
authz.instance.DirAclAuthz.ldap.multipleSuffix.enable=false
Copy to Clipboard
For more information on securely configuring LDAP and an explanation of parameters, refer to Section 6.5.4, “Enabling TLS Client Authentication”. The parameters paths differ than what is shown there, but the same names and values are allowed in both places.
The CA also has to have a mechanism for approving user requests. As with configuring authorization, this is done by identifying the appropriate authentication plug-in and configuring an instance for it: 
auths.impl.AgentCertAuth.class=com.netscape.cms.authentication.AgentCertAuthentication
auths.instance.AgentCertAuth.agentGroup=Certificate Manager Agents
auths.instance.AgentCertAuth.pluginName=AgentCertAuth
Copy to Clipboard

13.2.3.4. Subsystem Certificate Settings

Several of the subsystems have entries for each subsystem certificate in the configuration file. 
ca.sslserver.cert=MIIDmDCCAoCgAwIBAgIBAzANBgkqhkiG9w0BAQUFADBAMR4wHAYDVQQKExVSZWR...
ca.sslserver.certreq=MIICizCCAXMCAQAwRjEeMBwGA1UEChMVUmVkYnVkY29tcHV0ZXIgRG9tYWluMSQwIgYDV...
ca.sslserver.nickname=Server-Cert cert-pki-ca
ca.sslserver.tokenname=Internal Key Storage Token
Copy to Clipboard

13.2.3.5. Settings for Required Subsystems

At a minimum, each subsystem depends on a CA, which means that the CA (and any other required subsystem) has to be configured in the subsystem's settings. Any connection to another subsystem is prefaced by conn. and then the subsystem type and number. 
conn.ca1.clientNickname=subsystemCert cert-pki-tps
conn.ca1.hostadminport=server.example.com:8443
conn.ca1.hostagentport=server.example.com:8443
conn.ca1.hostport=server.example.com:9443
conn.ca1.keepAlive=true
conn.ca1.retryConnect=3
conn.ca1.servlet.enrollment=/ca/ee/ca/profileSubmitSSLClient
conn.ca1.servlet.renewal=/ca/ee/ca/profileSubmitSSLClient
conn.ca1.servlet.revoke=/ca/subsystem/ca/doRevoke
conn.ca1.servlet.unrevoke=/ca/subsystem/ca/doUnrevoke
conn.ca1.timeout=100
Copy to Clipboard

13.2.3.6. Database Settings

All of the subsystems use an LDAP directory to store their information. This internal database is configured in the internaldb parameters, except for the TPS which configured it in the tokendb parameters with a lot of other configuration settings. 
internaldb._000=##
internaldb._000=##
internaldb._001=## Internal Database
internaldb._002=##
internaldb.basedn=o=pki-tomcat-ca-SD
internaldb.database=pki-tomcat-ca
internaldb.maxConns=15
internaldb.minConns=3
internaldb.ldapauth.authtype=SslClientAuth
internaldb.ldapauth.clientCertNickname=HSM-A:subsystemCert pki-tomcat-ca
internaldb.ldapconn.host=example.com
internaldb.ldapconn.port=11636
internaldb.ldapconn.secureConn=true
internaldb.multipleSuffix.enable=false
Copy to Clipboard
For further information on securely configuring LDAP and an explanation of parameters, refer to Section 6.5.4, “Enabling TLS Client Authentication”. No additional configuration is necessary outside of what is done as part Section 6.5.4, “Enabling TLS Client Authentication”.

13.2.3.7. Enabling and Configuring 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

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.
Enabling the Publishing Queue

Figure 13.1. Enabling the Publishing Queue

13.2.3.7.1. Enabling and Configuring a Publishing Queue by editing the CS.cfg file
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.
  1. Stop the CA server, so that you can edit the configuration files. 
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard
  2. Open the CA's CS.cfg file. 
    # vim /var/lib/pki/instance_name/ca/conf/CS.cfg
    Copy to Clipboard
  3. Set the ca.publish.queue.enable to true. If the parameter is not present, then add a line with the parameter. 
    ca.publish.queue.enable=true
    Copy to Clipboard
  4. Set other related publishing queue parameters:
    • ca.publish.queue.maxNumberOfThreads sets the maximum number of threads that can be opened for publishing operations. The default is 3.
    • ca.publish.queue.priorityLevel sets the priority for publishing operations. The priority value ranges from -2 (lowest priority) to 2 (highest priority). Zero (0) is normal priority and is also the default.
    • ca.publish.queue.pageSize sets the maximum number of requests that can be stored in the publishing queue page. The default is 40.
    • ca.publish.queue.saveStatus sets the interval to save its status every specified number of publishing operations. This allows the publishing queue to be recovered if the CA is restarted or crashes. The default is 200, but any non-zero number will recover the queue when the CA restarts. Setting this parameter to 0 disables queue recovery. 
    ca.publish.queue.maxNumberOfThreads=1
	ca.publish.queue.priorityLevel=0
	ca.publish.queue.pageSize=100
	ca.publish.queue.saveStatus=200
    Copy to Clipboard

    Note

    Setting ca.publish.queue.enable to false and ca.publish.queue.maxNumberOfThreads to 0 disables both the publishing queue and using separate threads for publishing issued certificates.
  5. Restart the CA server. 
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard

13.2.3.8. Settings for PKI Tasks

The CS.cfg file is used to configure the PKI tasks for every subsystem. The parameters are different for every single subsystem, without any overlap.
For example, the KRA has settings for a required number of agents to recover a key. 
kra.noOfRequiredRecoveryAgents=1
Copy to Clipboard
Review the CS.cfg file for each subsystem to become familiar with its PKI task settings; the comments in the file are a decent guide for learning what the different parameters are.
  • The CA configuration file lists all of the certificate profiles and policy settings, as well as rules for generating CRLs.
  • The TPS configures different token operations.
  • The TKS lists profiles for deriving keys from different key types.
  • The OCSP sets key information for different key sets.

13.2.3.9. Changing DN Attributes in CA-Issued Certificates

In certificates issued by the Certificate System, DNs identify the entity that owns the certificate. In all cases, if the Certificate System is connected with a Directory Server, the format of the DNs in the certificates should match the format of the DNs in the directory. It is not necessary that the names match exactly; certificate mapping allows the subject DN in a certificate to be different from the one in the directory.
In the Certificate System, the DN is based on the components, or attributes, defined in the X.509 standard. Table 13.8, “Allowed Characters for Value Types” lists the attributes supported by default. The set of attributes is extensible.
Table 13.8. Allowed Characters for Value Types
Attribute Value Type Object Identifier
cn DirectoryString 2.5.4.3
ou DirectoryString 2.5.4.11
o DirectoryString 2.5.4.10
c PrintableString , two-character 2.5.4.6
l DirectoryString 2.5.4.7
st DirectoryString 2.5.4.8
street DirectoryString 2.5.4.9
title DirectoryString 2.5.4.12
uid DirectoryString 0.9.2342.19200300.100.1.1
mail IA5String 1.2.840.113549.1.9.1
dc IA5String 0.9.2342.19200300.100.1.2.25
serialnumber PrintableString 2.5.4.5
unstructuredname IA5String 1.2.840.113549.1.9.2
unstructuredaddress PrintableString 1.2.840.113549.1.9.8
By default, the Certificate System supports the attributes identified in Table 13.8, “Allowed Characters for Value Types”. This list of supported attributes can be extended by creating or adding new attributes. The syntax for adding additional X.500Name attributes, or components, is as follows: 
X500Name.NEW_ATTRNAME.oid=n.n.n.n
X500Name.NEW_ATTRNAME.class=string_to_DER_value_converter_class
Copy to Clipboard
The value converter class converts a string to an ASN.1 value; this class must implement the netscape.security.x509.AVAValueConverter interface. The string-to-value converter class can be one of the following:
  • netscape.security.x509.PrintableConverter converts a string to a PrintableString value. The string must have only printable characters.
  • netscape.security.x509.IA5StringConverter converts a string to an IA5String value. The string must have only IA5String characters.
  • netscape.security.x509.DirStrConverter converts a string to a DirectoryString. The string is expected to be in DirectoryString format according to RFC 2253.
  • netscape.security.x509.GenericValueConverter converts a string character by character in the following order, from the smallest characterset to the largest:
    • PrintableString
    • IA5String
    • BMPString
    • Universal String
An attribute entry looks like the following: 
X500Name.MY_ATTR.oid=1.2.3.4.5.6
X500Name.MY_ATTR.class=netscape.security.x509.DirStrConverter
Copy to Clipboard
13.2.3.9.1. Adding New or Custom Attributes
To add a new or proprietary attribute to the Certificate System schema, do the following:
  1. Stop the Certificate Manager. 
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard
  2. Open the /var/lib/pki/cs_instance/conf/ directory.
  3. Open the configuration file, CS.cfg.
  4. Add the new attributes to the configuration file.
    For example, to add three proprietary attributes, MYATTR1 that is a DirectoryString, MYATTR2 that is an IA5String, and MYATTR3 that is a PrintableString, add the following lines at the end of the configuration file: 
    X500Name.attr.MYATTR1.oid=1.2.3.4.5.6
X500Name.attr.MYATTR1.class=netscape.security.x509.DirStrConverter
X500Name.attr.MYATTR2.oid=11.22.33.44.55.66
X500Name.attr.MYATTR2.class=netscape.security.x509.IA5StringConverter
X500Name.attr.MYATTR3.oid=111.222.333.444.555.666
X500Name.attr.MYATTR3.class=netscape.security.x509.PrintableConverter
    Copy to Clipboard
  5. Save the changes, and close the file.
  6. Restart the Certificate Manager. 
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard
  7. Reload the enrollment page and verify the changes; the new attributes should show up in the form.
  8. To verify that the new attributes are in effect, request a certificate using the manual enrollment form.
    Enter values for the new attributes so that it can be verified that they appear in the certificate subject names. For example, enter the following values for the new attributes and look for them in the subject name: 
    MYATTR1: a_value
MYATTR2: a.Value
MYATTR3: aValue
cn: John Doe
o: Example Corporation
    Copy to Clipboard
  9. Open the agent services page, and approve the request.
  10. When the certificate is issued, check the subject name. The certificate should show the new attribute values in the subject name.
13.2.3.9.2. Changing the DER-Encoding Order
It is possible to change the DER-encoding order of a DirectoryString, so that the string is configurable since different clients support different encodings.
The syntax for changing the DER-encoding order of a DirectoryString is as follows: 
X500Name.directoryStringEncodingOrder=encoding_list_separated_by_commas
Copy to Clipboard
The possible encoding values are as follows:
  • PrintableString
  • IA5String
  • UniversalString
  • BMPString
  • UTF8String
For example, the DER-encoding ordered can be listed as follows: 
X500Name.directoryStringEncodingOrder=PrintableString,BMPString
Copy to Clipboard
To change the DirectoryString encoding, do the following:
  1. Stop the Certificate Manager. 
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard
  2. Open the /var/lib/pki/cs_instance/conf/ directory.
  3. Open the CS.cfg configuration file.
  4. Add the encoding order to the configuration file.
    For example, to specify two encoding values, PrintableString and UniversalString, and the encoding order is PrintableString first and UniversalString next, add the following line at the end of the configuration file: 
    X500Name.directoryStringEncodingOrder=PrintableString,UniversalString
    Copy to Clipboard
  5. Save the changes, and close the file.
  6. Start the Certificate Manager. 
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard
  7. To verify that the encoding orders are in effect, enroll for a certificate using the manual enrollment form. Use John_Doe for the cn.
  8. Open the agent services page, and approve the request.
  9. When the certificate is issued, use the dumpasn1 tool to examine the encoding of the certificate.
    The cn component of the subject name should be encoded as a UniversalString.
  10. Create and submit a new request using John Smith for the cn.
    The cn component of the subject name should be encoded as a PrintableString.

13.2.3.10. Setting a CA to Use a Different Certificate to Sign CRLs

A Certificate Manager uses the key pair corresponding to its OCSP signing certificate for signing certificates and certificate revocation lists (CRLs). To use a different key pair to sign the CRLs that the Certificate Manager generates, then a CRL signing certificate can be created. The Certificate Manager's CRL signing certificate must be signed or issued by itself.
To enable a Certificate Manager to sign CRLs with a different key pair, do the following:
  1. Request a CRL signing certificate for the Certificate Manager.
    Alternatively, use a tool that is capable of generating keypairs, such as the certutil tool to generate a key pair, request a certificate for the key pair, and install the certificate in the Certificate Manager's certificate database. For more information about the certutil tool, see http://www.mozilla.org/projects/security/pki/nss/tools/.
  2. When the certificate request has been created, submit it through the Certificate Manager end-entities page, selecting the right profile, such as the "Manual OCSP Manager Signing Certificate Enrollment" profile. The page has a URL in the following format: 
    		https://hostname:port/ca/ee/ca
    Copy to Clipboard
  3. After the request is submitted, log into the agent services page.
  4. Check the request for required extensions. The CRL signing certificate must contain the Key Usage extension with the crlSigning bit set.
  5. Approve the request.
  6. After the CRL signing certificate is generated, install the certificate in the Certificate Manager's database through System Keys and Certificates in the console.
  7. Stop the Certificate Manager. 
    # systemctl stop pki-tomcatd@instance_name.service
    Copy to Clipboard
  8. Update the Certificate Manager's configuration to recognize the new key pair and certificate.
    1. Change to the Certificate Manager instance configuration directory. 
      # cd /var/lib/pki/instance-name/ca/conf/
      Copy to Clipboard
    2. Open the CS.cfg file and add the following lines: 
      ca.crl_signing.cacertnickname=nickname cert-instance_ID
ca.crl_signing.defaultSigningAlgorithm=signing_algorithm
ca.crl_signing.tokenname=token_name
      Copy to Clipboard
      nickname is the name assigned to the CRL signing certificate.
      instance_ID is the name of the Certificate Manager instance.
      If the installed CA is a RSA-based CA, signing_algorithm can be SHA256withRSA, SHA384withRSA, or SHA512withRSA. If the installed CA is an EC-based CA, signing_algorithm can be SHA256withEC, SHA384withEC, SHA512withEC.
      token_name is the name of the token used for generating the key pair and the certificate. If the internal/software token is used, use Internal Key Storage Token as the value.
      For example, the entries might look like this: 
      ca.crl_signing.cacertnickname=crlSigningCert cert-pki-ca
ca.crl_signing.defaultSigningAlgorithm=SHAMD512withRSA
ca.crl_signing.tokenname=Internal Key Storage Token
      Copy to Clipboard
    3. Save the changes, and close the file.
  9. Restart the Certificate Manager. 
    # systemctl restart pki-tomcatd@instance_name.service
    Copy to Clipboard
    Now the Certificate Manager is ready to use the CRL signing certificate to sign the CRLs it generates.

13.2.3.11. Configuring CRL Generation from Cache in CS.cfg

The CRL cache is a simple mechanism that allows cert revocation information to be taken from a collection of revocation information maintained in memory. For best performance, it is recommended that this feature be enabled, which already represents the default behavior. The following configuration information (which is the default) is presented for information purposes or if changes are desired.
  1. Stop the CA server. 
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard
  2. Open the CA configuration directory. 
    # cd /var/lib/instance_name/conf/
    Copy to Clipboard
  3. Edit the CS.cfg file, setting the enableCRLCache and enableCacheRecovery parameters to true: 
    ca.crl.MasterCRL.enableCRLCache=true
ca.crl.MasterCRL.enableCacheRecovery=true
    Copy to Clipboard
  4. Start the CA server. 
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard

13.2.3.12. Configuring Update Intervals for CRLs in CS.cfg

The following describes how to configure the CRL system flexibly to reflect desired behavior. The goal is to configure CRL updates according to some schedule of two types. One type allows for a list of explicit times and the other consists of a length of time interval between updates. There is also a hybrid scenario where both are enabled to account for drift. The Note entry just below actually represents the default out of the box scenario.
The default scenario is listed as follows: 
ca.crl.MasterCRL.updateSchema=3
ca.crl.MasterCRL.enableDailyUpdates=true
ca.crl.MasterCRL.enableUpdateInterval=true
ca.crl.MasterCRL.autoUpdateInterval=240
ca.crl.MasterCRL.dailyUpdates=1:00
ca.crl.MasterCRL.nextUpdateGracePeriod=0
Copy to Clipboard
Deviate from this only when a more detailed and specific update schedule is desired. The rest of the section will talk about how that is accomplished.
Configuring the settings for full and delta CRLs in the CS.cfg file involves editing parameters.
Table 13.9. CRL Extended Interval Parameters
Parameter Description Accepted Values
updateSchema Sets the ratio for how many delta CRLs are generated per full CRL. An integer value
enableDailyUpdates Enables and disables setting CRL updates based on set times. true or false
enableUpdateInterval Enables and disables setting CRL updates based on set intervals. true or false
dailyUpdates Sets the times the CRLs should be updated A comma-delimited list of times
autoUpdateInterval Sets the interval in minutes to update the CRLs. An integer value
nextUpdateGracePeriod Adds the time in minutes to the CRL validity period to ensure that CRLs remain valid throughout the publishing or replication period. An integer value
refreshInSec Sets the periodicity in seconds of the thread on the clone OCSP to check LDAP for any updates of the CRL. An integer value

Procedure 13.1. How to configure CRL update intervals in CS.cfg

  1. Stop the CA server. 
    # systemctl stop pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard
  2. Change to the CA configuration directory. 
    # cd /var/lib/instance_name/conf/
    Copy to Clipboard
  3. Edit the CS.cfg file, and add the following line to set the update interval: 
    ca.crl.MasterCRL.updateSchema=3
    Copy to Clipboard
    The default interval is 1, meaning a full CRL is generated every time a CRL is generated. The updateSchema interval can be set to any integer.
  4. Set the update frequency, either by specifying a cyclical interval or set times for the updates to occur:
    • Specify set times by enabling the enableDailyUpdates parameter, and add the desired times to the dailyUpdates parameter: 
      ca.crl.MasterCRL.enableDailyUpdates=true
	ca.crl.MasterCRL.enableUpdateInterval=false
	ca.crl.MasterCRL.dailyUpdates=0:50,04:55,06:55
      Copy to Clipboard
      This field sets a daily time when the CRL should be updated. To specify multiple times, enter a comma-separated 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, set 01:50,04:55,06:55;02:00,05:00,17:00 to configure revocation on Day 1 of the cycle at 1:50am, 4:55am, and 6:55am and then Day 2 at 2am, 5am, and 5pm.
      Specify intervals by enabling the enableUpdateInterval parameter, and add the required interval in minutes to the autoUpdateInterval parameter: 
      ca.crl.MasterCRL.enableDailyUpdates=false
	ca.crl.MasterCRL.enableUpdateInterval=true
	ca.crl.MasterCRL.autoUpdateInterval=240
      Copy to Clipboard
  5. Set the following parameters depending on your environment:
    • If you run a CA without an OCSP subsystem, set: 
      ca.crl.MasterCRL.nextUpdateGracePeriod=0
      Copy to Clipboard
    • If you run a CA with an OCSP subsystem, set: 
      ca.crl.MasterCRL.nextUpdateGracePeriod=time_in_minutes
      Copy to Clipboard
      The ca.crl.MasterCRL.nextUpdateGracePeriod parameter defines the time in minutes, and the value must be big enough to enable the CA to propagate the new CRL to the OCSP. You must set the parameter to a non-zero value.
      If you additionally have OCSP clones in your environment, also set: 
      ocsp.store.defStore.refreshInSec=time_in_seconds
      Copy to Clipboard
      The ocsp.store.defStore.refreshInSec parameter sets the frequency in seconds with which the clone OCSP instances are informed of CRL updates through LDAP replication updates from the master OCSP instance.
    See Table 13.9, “CRL Extended Interval Parameters” for details on the parameters.
  6. Restart the CA server. 
    # systemctl start pki-tomcatd-nuxwdog@instance_name.service
    Copy to Clipboard

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, set both enableDailyUpdates and enableUpdateInterval parameters to true, and add the required values to autoUpdateInterval and dailyUpdates: 
ca.crl.MasterCRL.enableDailyUpdates=true
ca.crl.MasterCRL.enableUpdateInterval=true
ca.crl.MasterCRL.autoUpdateInterval=240
ca.crl.MasterCRL.dailyUpdates=1:00
Copy to Clipboard
Only one dailyUpdates value will be accepted when updating CRLs by interval.
The interval updates will resynchronize with the dailyUpdates value every 24 hours preventing schedule drift.

13.2.3.13. Changing the Access Control Settings for the Subsystem

By default, access control rules are applied by evaluating deny rules first and then by evaluating allow rules. To change the order, change the authz.evaluateOrder parameter in the CS.cfg. 
authz.evaluateOrder=deny,allow
Copy to Clipboard
Additionally, access control rules can be evaluated from the local web.xml file (basic ACLs) or more complex ACLs can be accessed by checking the LDAP database. The authz.sourceType parameter identifies what type of authorization to use. 
authz.sourceType=web.xml
Copy to Clipboard

Note

Always restart the subsystem after editing the CS.cfg file to load the updated settings.

13.2.3.14. Configuring Ranges for Requests and Serial Numbers

When random serial numbers are not used, in case of cloned systems, administrators could specify the ranges Certificate System will use for requests and serial numbers in the /etc/pki/instance_name/subsystem/CS.cfg file: 
dbs.beginRequestNumber=1001001007001
			dbs.endRequestNumber=11001001007000
			dbs.requestIncrement=10000000000000
			dbs.requestLowWaterMark=2000000000000
			dbs.requestCloneTransferNumber=10000
			dbs.requestDN=ou=ca, ou=requests
			dbs.requestRangeDN=ou=requests, ou=ranges
			dbs.beginSerialNumber=1001001007001
			dbs.endSerialNumber=11001001007000
			dbs.serialIncrement=10000000000000
			dbs.serialLowWaterMark=2000000000000
			dbs.serialCloneTransferNumber=10000
			dbs.serialDN=ou=certificateRepository, ou=ca
			dbs.serialRangeDN=ou=certificateRepository, ou=ranges
			dbs.beginReplicaNumber=1
			dbs.endReplicaNumber=100
			dbs.replicaIncrement=100
			dbs.replicaLowWaterMark=20
			dbs.replicaCloneTransferNumber=5
			dbs.replicaDN=ou=replica
			dbs.replicaRangeDN=ou=replica, ou=ranges
			dbs.ldap=internaldb
			dbs.newSchemaEntryAdded=true
Copy to Clipboard

Note

Certificate System supports BigInteger values for the ranges.

13.2.3.15. Setting Requirement for pkiconsole to use TLS Client Certificate Authentication

Edit the CS.cfg file of each subsystem, search for the authType parameter and set it as follows: 
authType=sslclientauth
Copy to Clipboard
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

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

Making open source more inclusive

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

About Red Hat

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

Theme

© 2025 Red Hat