14.4. Configuration Files for the Tomcat Engine and Web Services

All of the user and administrative (administrators, agents, and auditors) services for the subsystems are accessed over web protocols.
This section discusses the two major sets of configuration files that apply to all Red Hat Certificate System subsystems (CA, KRA, OCSP, TKS, and TPS):
  • /var/lib/pki/instance_name/conf/server.xml provides the configuration for the Tomcat engine.
  • /usr/share/pki/subsystem_type/webapps/WEB-INF/web.xml provides the configuration for the web services offered by this instance.

14.4.1. Tomcatjss

Note

The later subsections include important configuration information on required changes to parameter values. Ensure they are followed for strict compliance.
The following configuration in the server.xml file found in the example pki-tomcat/conf directory can be used to explain how Tomcatjss fits into the entire Certificate System ecosystem. Portions of the Connector entry for the secret port are shown below. 
<Connector name="Secure"

# Info about the socket itself
port="8443"
protocol="org.apache.coyote.http11.Http11Protocol"
SSLEnabled="true"
sslProtocol="SSL"
scheme="https"
secure="true"
connectionTimeout="80000"
maxHttpHeaderSize="8192"
acceptCount="100" maxThreads="150" minSpareThreads="25"
enableLookups="false" disableUploadTimeout="true"
# Points to our tomcat jss implementation
sslImplementationName="org.apache.tomcat.util.net.jss.JSSImplementation"

# OCSP responder configuration can be enabled here
enableOCSP="true"
ocspCacheSize="1000"
ocspMinCacheEntryDuration="60"
ocspMaxCacheEntryDuration="120"
ocspTimeout="10"

# A collection of cipher related settings that make sure connections are secure.
strictCiphers="true"
# The "clientAuth" parameter configures the client authentication scheme
# for this server socket. If you set "clientAuth" to "want", the client
# authentication certificate is optional. Alternatively, set the
# parameter to "required" to configure that the certificate is is mandatory.
clientAuth="want"
sslVersionRangeStream="tls1_1:tls1_2"
sslVersionRangeDatagram="tls1_1:tls1_2"
sslRangeCiphers="+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_SHA,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,+TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
serverCertNickFile="/var/lib/pki/pki-tomcat/conf/serverCertNick.conf"
passwordFile="/var/lib/pki/pki-tomcat/conf/password.conf"
passwordClass="org.apache.tomcat.util.net.jss.PlainPasswordFile"
certdbDir="/var/lib/pki/pki-tomcat/alias"

/>
In the server.xml configuration file for the Tomcat engine, there is this Connector configuration element that contains the pointer to the tomcatjss implementation, which can be plugged into the sslImplementation property of this Connector object.
Each key parameter element is explained in the subsections below.

14.4.1.1. TLS Cipher Configuration

The TLS ciphers configured in the server.xml file provide system-wide defaults when Red Hat Certificate system is acting as a client and as a server. This includes when acting as a server (for example, when serving HTTPS connections from Tomcat) and as a client (for example, when communicating with the LDAP server or when communicating with another Certificate System instance).
The configuration for server TLS ciphers is in the Red Hat Certificate System instance-specific /var/lib/pki/instance_name/conf/server.xml file. The following parameters control the ciphers offered:
  • strictCiphers, when set to true, ensures that only ciphers with a + sign in the sslRangeCiphers are enabled. 
    strictCiphers="true"
    Do not change the default value (true).
  • sslVersionRangeStream and sslVersionRangeDatagram sets the TLS version the server supports. The following are the defaults of the parameters: 
    sslVersionRangeStream="tls1_1:tls1_2"
sslVersionRangeDatagram="tls1_1:tls1_2"
    Do not change the default value of the parameters.
  • sslRangeCiphers sets which ciphers are enabled and disabled. Ciphers with a + sign are enabled, ciphers with a - sign disabled.
    Set RSA ciphers as below: 
    sslRangeCiphers="+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_SHA,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,+TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    Set EC ciphers as below: 
    sslRangeCiphers="+TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,+TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,+TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    For a list of allowed ciphers, see Section 3.1, “TLS, ECC, and RSA”.
  • If you install Certificate System with either LunaSA or nCipher Hardware Security Module (HSM) on systems with FIPS mode enabled for RSA, disable the following ciphers, as they are unsupported on HSMs in FIPS mode:
    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
14.4.1.1.1. Client TLS cipher Configuration
The Red Hat Certificate System also allows for cipher configuration on a system when it is acting as a client to another CS system.
Ciphers in a list are separated by commas.
On CA (for the communication of the CA with the KRA): 
ca.connector.KRA.clientCiphers=your selected cipher list
For example: 
ca.connector.KRA.clientCiphers=TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA
On TPS (for communication with the CA, the KRA and the TKS): 
tps.connector.ca id.clientCiphers=your selected cipher list
tps.connector.kra id.clientCiphers=your selected cipher list
tps.connector.tks id.clientCiphers=your selected cipher list
For example: 
tps.connector.ca1.clientCiphers=TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA

14.4.1.2. Enabling Automatic Revocation Checking on the CA

The CA can be configured to check the revocation status of any certificate (including agent, administrator, and enrollment) the server receives during authentication of an SSL/TLS client. This means that when the CA receives any client authentication request, it automatically checks an OCSP. (For information about setting up an OCSP responder, see Using the Online Certificate Status Protocol (OCSP) Responder in the Red Hat Certificate System Administration Guide.)
As part of revocation checking, the CA has the ability to cache client authentication so that it keeps a list of verified certificates. This allows the CA to check its cached results before checking its internal database or an OCSP, which improves the overall operation performance. Automatic revocation checking is enabled in the revocationChecking.enabled parameter.
The revocation status results are only valid for a certain, specified period of time (revocationChecking.validityInterval). If the CA has no way to re-verify a certificate status that is in cache, then there is a grace interval (revocationChecking.unknownStateInterval) where the previously-cached status is still considered valid, even if it is outside the validity interval.

Note

The cached certificates are kept in a buffer (revocationChecking.bufferSize). If the buffer setting is missing or is set to zero, then no buffer is kept, which means that the results of revocation checks are not cached. In that case, all revocation checks are performed directly against the CA's internal database.

Note

The subsystem CS.cfg configuration file includes a parameter, jss.ocspcheck.enable, which sets whether a Certificate Manager should use an OCSP to verify the revocation status of the certificate it receives as a part of SSL/TLS client or server authentication. Changing the value of this parameter to true means the Certificate Manager reads the Authority Information Access extension in the certificate and verifies the revocation status of the certificate from the OCSP responder specified in the extension.
  1. Stop the subsystem instance. 
    # pki-server stop instance_name
  2. Open the CS.cfg file. 
    # vim /var/lib/pki/instance-name/ca/conf/CS.cfg
  3. Edit the revocation-related parameters. 
    auths.revocationChecking.bufferSize=50
auths.revocationChecking.ca=ca
auths.revocationChecking.enabled=true
auths.revocationChecking.unknownStateInterval=0
auths.revocationChecking.validityInterval=120
    • revocationChecking.ca. Sets which service is providing the OCSP respsonse, a CA or an OCSP responder.
    • revocationChecking.enabled. Sets revocation checking. true enables checking; false disables checking. By default, the feature is enabled.
    • revocationChecking.bufferSize. Sets the total number of last-checked certificates the server should maintain in its cache. For example, if the buffer size is 2, the server retains the last two certificates checked in its cache. By default, the server caches the last 50 certificates.
    • revocationChecking.unknownStateInterval. Sets how frequently the server checks the revocation status. The default interval is 0 seconds. unknownStateInterval is a grace period in which cache result will be assumed to be true if CA has no means (no access to information allowing) to verify certificate status
    • revocationChecking.validityInterval. Sets how long the cached certificates are considered valid. Be judicious when choosing the interval. For example, if the validity period is 60 seconds, the server discards the certificates in its cache every minute and attempts to retrieve them from their source. The Certificate Manager uses its internal database to retrieve and verify the revocation status of the certificates. The default validity period is 120 seconds (2 minutes).
  4. Start the Certificate System instance. 
    # pki-server start instance_name

14.4.1.3. Enabling Certificate Revocation Checking for Subsystems

The Certificate System subsystems do not have OCSP checking enabled, by default, to validate subsystem certificates. This means it is possible for someone to log into the administrative or agent interfaces with a revoked certificate.
OCSP checking can be enabled for all subsystems by editing the server.xml file. The agent interface and the admin interface are configured separately, so both sections in the configuration should be edited.

Note

If the subsystem has been configured to use an SSL/TLS connection with its internal database, then the SSL/TLS server certificate of the LDAP internal database must be recognized by the OCSP responder. If the OCSP responder does not recognize the LDAP server certificate, then the subsystem will not start properly. This configuration is covered in the Red Hat Certificate System 10 Planning, Installation, and Deployment Guide, since subsystem-LDAP SSL/TLS server connections are configured as part of the subsystem setup.
  1. Get the name of the OCSP signing certificate for the OCSP or CA which will be used to check certificate status. For example: 
    # certutil -L -d /etc/pki/instance-name/alias
Certificate Nickname                                         Trust Attributes
															 SSL,S/MIME,JAR/XPI
Certificate Authority - Example Domain                       CT,c,
ocspSigningCert cert-pki-ocsp CTu,Cu,Cu
subsystemCert cert-pki-ocsp                                  u,u,u
Server-Cert cert-pki-ocsp                                    u,u,u
auditSigningCert cert-pki-ocsp                               u,u,Pu
  2. Open the server.xml file for the subsystem. For example: 
    # vim /etc/pki/instance-name/server.xml
  3. If the OCSP signing certificate is not present in the instance's security database, import it: 
    # certutil -d /etc/pki/instance-name/alias -A -n "ocspSigningCert cert-pki-ca" -t "C,," -a -i ocspCert.b64
  4. There are three critical parameters to enable OCSP checking:
    • enableOCSP, which must be set to true to enable OCSP checking.
      This is a global setting; if it is set for one interface, then it applies to every interface for the instance. However, it must be set on the first interface listed in the server.xml file, which is usually the agent interface. Any setting on another interface is ignored.
    • ocspResponderURL, which gives the URL of the OCSP responder to send the OCSP requests.
      For an OCSP Manager, this can be another OCSP service in another OCSP or in a CA. For other subsystems, this always points to an external OCSP service in an OCSP or a CA.
    • ocspResponderCertNickname, which gives the signing certificate to use to sign the response; for a CA OCSP service, this is the CA's OCSP signing certificate, and for an OCSP responder, it is an OCSP signing certificate.
    Other parameters can be used to define the OCSP communication. All of the OCSP checking parameters are listed in Table 14.10, “OCSP Parameters for server.xml”.
    There are two different sections in the file for the agent and administrator interfaces. The OCSP parameters need to be added to both sections to enable and configure OCSP checking. For example:

    Example 14.3. OCSP Settings for an Agent Interface

    <Connector name="Agent" port="8443" maxHttpHeaderSize="8192"
					maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
					enableLookups="false" disableUploadTimeout="true"
					acceptCount="100" scheme="https" secure="true"
					clientAuth="true" sslProtocol="SSL"
					sslOptions="ssl2=true,ssl3=true,tls=true"

		ssl3Ciphers="-SSL3_FORTEZZA_DMS_WITH_NULL_SHA, ..."

		tls3Ciphers="-SSL3_FORTEZZA_DMS_WITH_NULL_SHA, ..."
					SSLImplementation="org.apache.tomcat.util.net.jss.JSSImplementation"
					enableOCSP="true"  
					ocspResponderURL="http://server.example.com:8443/ca/ocsp"  
					ocspResponderCertNickname="ocspSigningCert cert-pki-ca 102409a"  
					ocspCacheSize="1000"  
					ocspMinCacheEntryDuration="60"  
					ocspMaxCacheEntryDuration="120"  
					ocspTimeout="10"  
					debug="true"
					serverCertNickFile="/etc/pki/instance-name/serverCertNick.conf"
					passwordFile="/etc/pki/instance-name/password.conf"
					passwordClass="org.apache.tomcat.util.net.jss.PlainPasswordFile"
					certdbDir="/etc/pki/instance-name/alias"/>
  5. If the given OCSP service is not the CA, then the OCSP service's signing certificate must be imported into the subsystem's NSS database. This can be done in the console or using certutil; both options are covered in Installing Certificates in the Certificate System Database in the Red Hat Certificate System Administration Guide.
  6. Restart the subsystem. 
    # pki-server restart instance_name

Table 14.10. OCSP Parameters for server.xml

Parameter Description
enableOCSP Enables (or disables) OCSP checking for the subsystem.
ocspResponderURL Sets the URL where the OCSP requests are sent.
For an OCSP Manager, this can be another OCSP service in another OCSP or in a CA. For a TKS or KRA, this always points to an external OCSP service in an OCSP or a CA.
ocspResponderCertNickname Sets the nickname of the signing certificate for the responder, either the OCSP signing certificate or the CA's OCSP signing certificate. The certificate must be imported into the subsystem's NSS database and have the appropriate trust settings set.
ocspCacheSize Sets the maximum number of cache entries.
ocspMinCacheEntryDuration Sets minimum seconds before another fetch attempt can be made. For example, if this is set to 120, then the validity of a certificate cannot be checked again until at least 2 minutes after the last validity check.
ocspMaxCacheEntryDuration Sets the maximum number of seconds to wait before making the next fetch attempt. This prevents having too large a window between validity checks.
ocspTimeout Sets the timeout period, in seconds, for the OCSP request.

14.4.1.4. Adding an AIA Extension to an Enrollment Profile

To set the AIA URL in the profile when using an external OCSP, add the correct URL to the certificate profile. For example: 
policyset.cmcUserCertSet.5.default.params.authInfoAccessADLocation_0=http://example.com:8080/ocsp/ee/ocsp

14.4.2. Session Timeout

When a user connects to PKI server through a client application, the server will create a session to keep track of the user. As long as the user remains active, the user can execute multiple operations over the same session without having to re-authenticate.
Session timeout determines how long the server will wait since the last operation before terminating the session due to inactivity. Once the session is terminated, the user will be required to re-authenticate to continue accessing the server, and the server will create a new session.
There are two types of timeouts:
  • TLS session timeout
  • HTTP session timeout
Due to differences in the way clients work, the clients will be affected differently by these timeouts.

Note

Certain clients have their own timeout configuration. For example, Firefox has a keep-alive timeout setting. For details, see http://kb.mozillazine.org/Network.http.keep-alive.timeout. If the value is different from the server's setting for TLS Session Timeout or HTTP Session Timeout, different behavior can be observed.

14.4.2.1. TLS Session Timeout

A TLS session is a secure communication channel over a TLS connection established through TLS handshake protocol.
PKI server generates audit events for TLS session activities. The server generates an ACCESS_SESSION_ESTABLISH audit event with Outcome=Success when the connection is created. If the connection fails to be created, the server will generate an ACCESS_SESSION_ESTABLISH audit event with Outcome=Failure. When the connection is closed, the server will generate an ACCESS_SESSION_TERMINATED audit event.
TLS session timeout (that is TLS connection timeout) is configured in the keepAliveTimeout parameter in the Secure <Connector> element in the /etc/pki/<instance>/server.xml file: 
...
<Server>
	<Service>
		<Connector name="Secure"
			...
			keepAliveTimeout="300000"
			...
			/>
	</Service>
</Server>
...
By default the timeout value is set to 300000 milliseconds (that is 5 minutes). To change this value, edit the /etc/pki/<instance>/server.xml file and then restart the server.

Note

Note that this value will affect all TLS connections to the server. A large value may improve the efficiency of the clients since they can reuse existing connections that have not expired. However, it may also increase the number of connections that the server has to support simultaneously since it takes longer for abandoned connections to expire.

14.4.2.2. HTTP Session Timeout

An HTTP session is a mechanism to track a user across multiple HTTP requests using HTTP cookies. PKI server does not generate audit events for the HTTP sessions.

Note

For the purpose of auditing consistency, set the <session-timeout> value in this section to match the keepAliveTimeout value in Section 14.4.2.1, “TLS Session Timeout”. For example if keepAliveTimeout was set to 300000 (5 minutes), then set <session-timeout> to 30.
The HTTP session timeout can be configured in the <session-timeout> element in the /etc/pki/<instance>/web.xml file: 
...
<web-app>
	<session-config>
		<session-timeout>30</session-timeout>
	</session-config>
</web-app>
...
By default the timeout value is set to 30 minutes. To change the value, edit the /etc/pki/<instance>/web.xml file and then restart the server.

Note

Note that this value affects all sessions in all web applications on the server. A large value may improve the experience of the users since they will not be required to re-authenticate or view the access banner again so often. However, it may also increase the security risk since it takes longer for abandoned HTTP sessions to expire.

14.4.2.3. Session Timeout for PKI Web UI

PKI Web UI is an interactive web-based client that runs in a browser. Currently it only supports client certificate authentication.
When the Web UI is opened, the browser may create multiple TLS connections to a server. These connections are associated to a single HTTP session.
To configure a timeout for the Web UI, see Section 14.4.2.2, “HTTP Session Timeout”. The TLS session timeout is normally irrelevant since the browser caches the client certificate so it can recreate the TLS session automatically.
When the HTTP session expires, the Web UI does not provide any immediate indication. However, the Web UI will display an access banner (if enabled) before a user executes an operation.

14.4.2.4. Session Timeout for PKI Console

PKI Console is an interactive standalone graphical UI client. It supports username/password and client certificate authentication.
When the console is started, it will create a single TLS connection to the server. The console will display an access banner (if enabled) before opening the graphical interface. Unlike the Web UI, the console does not maintain an HTTP session with the server.
To configure a timeout for the console, see Section 14.4.2.1, “TLS Session Timeout”. The HTTP session timeout is irrelevant since the console does not use HTTP session.
When the TLS session expires, the TLS connection will close, and the console will exit immediately to the system. If the user wants to continue, the user will need to restart the console.

14.4.2.5. Session Timeout for PKI CLI

PKI CLI is a command-line client that executes a series of operations. It supports username/password and client certificate authentication.
When the CLI is started, it will create a single TLS connection to the server and an HTTP session. The CLI will display an access banner (if enabled) before executing operations.
Both timeouts are generally irrelevant to PKI CLI since the operations are executed in sequence without delay and the CLI exits immediately upon completion. However, if the CLI waits for user inputs, is slow, or becomes unresponsive, the TLS session or the HTTP session may expire and the remaining operations fail. If such delay is expected, see Section 14.4.2.1, “TLS Session Timeout” and Section 14.4.2.2, “HTTP Session Timeout” to accommodate the expected delay.