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
For example:
/var/lib/pki/instance_name/ca/conf
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:
- Stop the subsystem instance.
# systemctl stop pki-tomcatd@instance_name.service
OR (if usingnuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
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. - Open the
/var/lib/pki/instance_name/subsystem_type/conf
directory. - Open the
CS.cfg
file in a text editor. - Edit the parameters in the file, and save the changes.
- Start the subsystem instance.
# systemctl start pki-tomcatd@instance_name.service
OR (if usingnuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@instance_name.service
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
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
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
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
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
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
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
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
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
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
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
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
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](https://access.redhat.com/webassets/avalon/d/Red_Hat_Certificate_System-9-Planning_Installation_and_Deployment_Guide-en-US/images/871a5273bad79f837699deda3e546344/publishing-queue.png)
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.
- Stop the CA server, so that you can edit the configuration files.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the CA's
CS.cfg
file.# vim /var/lib/pki/instance_name/ca/conf/CS.cfg
- 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
- 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) to2
(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
Note
Settingca.publish.queue.enable
to false andca.publish.queue.maxNumberOfThreads
to 0 disables both the publishing queue and using separate threads for publishing issued certificates. - Restart the CA server.
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
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
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.
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
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 aPrintableString
value. The string must have only printable characters.netscape.security.x509.IA5StringConverter
converts a string to anIA5String
value. The string must have only IA5String characters.netscape.security.x509.DirStrConverter
converts a string to aDirectoryString
. The string is expected to be inDirectoryString
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
13.2.3.9.1. Adding New or Custom Attributes
- Stop the Certificate Manager.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the
/var/lib/pki/cs_instance/conf/
directory. - Open the configuration file,
CS.cfg
. - Add the new attributes to the configuration file.For example, to add three proprietary attributes,
MYATTR1
that is aDirectoryString
,MYATTR2
that is anIA5String
, andMYATTR3
that is aPrintableString
, 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
- Save the changes, and close the file.
- Restart the Certificate Manager.
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
- Reload the enrollment page and verify the changes; the new attributes should show up in the form.
- 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
- Open the agent services page, and approve the request.
- 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
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
To change the
DirectoryString
encoding, do the following:
- Stop the Certificate Manager.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the
/var/lib/pki/cs_instance/conf/
directory. - Open the
CS.cfg
configuration file. - Add the encoding order to the configuration file.For example, to specify two encoding values,
PrintableString
andUniversalString
, and the encoding order isPrintableString
first andUniversalString
next, add the following line at the end of the configuration file:X500Name.directoryStringEncodingOrder=PrintableString,UniversalString
- Save the changes, and close the file.
- Start the Certificate Manager.
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
- To verify that the encoding orders are in effect, enroll for a certificate using the manual enrollment form. Use
John_Doe
for thecn
. - Open the agent services page, and approve the request.
- When the certificate is issued, use the
dumpasn1
tool to examine the encoding of the certificate.Thecn
component of the subject name should be encoded as aUniversalString
. - Create and submit a new request using
John Smith
for thecn
.Thecn
component of the subject name should be encoded as aPrintableString
.
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:
- 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 thecertutil
tool, see http://www.mozilla.org/projects/security/pki/nss/tools/. - 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
- After the request is submitted, log into the agent services page.
- Check the request for required extensions. The CRL signing certificate must contain the
Key Usage
extension with thecrlSigning
bit set. - Approve the request.
- After the CRL signing certificate is generated, install the certificate in the Certificate Manager's database through System Keys and Certificates in the console.
- Stop the Certificate Manager.
# systemctl stop pki-tomcatd@instance_name.service
- Update the Certificate Manager's configuration to recognize the new key pair and certificate.
- Change to the Certificate Manager instance configuration directory.
# cd
/var/lib/pki/instance-name/ca/conf/
- 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
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 beSHA256withRSA
,SHA384withRSA
, orSHA512withRSA
. If the installed CA is an EC-based CA, signing_algorithm can beSHA256withEC
,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, useInternal 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
- Save the changes, and close the file.
- Restart the Certificate Manager.
# systemctl restart pki-tomcatd@instance_name.service
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.
- Stop the CA server.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the CA configuration directory.
# cd /var/lib/instance_name/conf/
- Edit the
CS.cfg
file, setting theenableCRLCache
andenableCacheRecovery
parameters to true:ca.crl.MasterCRL.enableCRLCache=true ca.crl.MasterCRL.enableCacheRecovery=true
- Start the CA server.
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
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
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.
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
- Stop the CA server.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Change to the CA configuration directory.
# cd /var/lib/instance_name/conf/
- Edit the
CS.cfg
file, and add the following line to set the update interval:ca.crl.MasterCRL.updateSchema=3
The default interval is 1, meaning a full CRL is generated every time a CRL is generated. TheupdateSchema
interval can be set to any integer. - 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 thedailyUpdates
parameter:ca.crl.MasterCRL.enableDailyUpdates=true ca.crl.MasterCRL.enableUpdateInterval=false ca.crl.MasterCRL.dailyUpdates=0:50,04:55,06:55
This field sets a daily time when the CRL should be updated. To specify multiple times, enter a comma-separated list of times, such as01: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, set01: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 theenableUpdateInterval
parameter, and add the required interval in minutes to theautoUpdateInterval
parameter:ca.crl.MasterCRL.enableDailyUpdates=false ca.crl.MasterCRL.enableUpdateInterval=true ca.crl.MasterCRL.autoUpdateInterval=240
- Set the following parameters depending on your environment:
- If you run a CA without an OCSP subsystem, set:
ca.crl.MasterCRL.nextUpdateGracePeriod=0
- If you run a CA with an OCSP subsystem, set:
ca.crl.MasterCRL.nextUpdateGracePeriod=time_in_minutes
Theca.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
Theocsp.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. - Restart the CA server.
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
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
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
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
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
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