9.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.

9.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.

9.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, “Allowed TLS Cipher Suites”.
  • 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

9.4.1.2. Enabling Certificate Revocation Checking for Subsystems

The Certificate System subsystems do not have OCSP checking enabled by default. OCSP checking can be enabled for all subsystems by editing the server.xml file.
There is one allowed method to configure OCSP checking:
In the following sections, the configuration of the allowed OCSP checking method will be discussed, where various OCSP parameters in the server.xml file might be used.
The following table provides information on each parameter relevant to OCSP in the server.xml file.

Table 9.10. OCSP Parameters for server.xml

Parameter Description
enableOCSP Enables (or disables) OCSP checking for the subsystem.
ocspResponderURL N/A
ocspResponderCertNickname N/A
ocspCacheSize
Sets the maximum number of OCSP response cache entries kept by the Network Security Services (NSS).
There are two special values:
  • -1: Turns off the OCSP response cache.
  • 0: Allows an unlimited number of OCSP responses in the cache.
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.

Note

If a nextUpdate field is sent with the OCSP response, it can affect the next fetch time with ocspMinCacheEntryDuration and ocspMaxCacheEntryDuration like following:
  • If the value in nextUpdate has been reached before the value set in ocspMinCacheEntryDuration, the fetch will not be started until the value set in ocspMinCacheEntryDuration has been reached.
  • If ocspMinCacheEntryDuration has been reached, the server checks if the value in nextUpdate has been reached. If the value has been reached, the fetch will happen.
  • Regardless of the value in nextUpdate, if the setting in ocspMaxCacheEntryDuration has been reached, the fetch will happen.
9.4.1.2.1. Setting Trust of the OCSP Signing Certificate
Each OCSP signing certificate must chain up to a trusted root in the Certificate System's NSS database.
Once the OCSP signing certificate is imported and trusted in the subystem's NSS database, the following consideration is required. If the OCSP responder being used has been configured to provide the entire certificate chain of the OCSP signing certificate with each OCSP response, then no further action is required. NSS knows how to validate this chain from the request information. If on the other hand the OCSP is known to not return the full chain, the chain can be imported manually. For details, see the section called “Importing an OCSP Responder”. The Certificate System OCSP responder already includes the chain with every response. This includes the Certificate System outboard OCSP responder and the internal OCSP service that comes with each CA.
This behavior is by default and cannot be changed.
9.4.1.2.2. Enabling a Certificate System Subsystem to use the OCSP Responder URL Specified in the Peer Certificate's Authority Information Access (AIA) Extension
To configure that Certificate System uses the OCSP responder URL specified in the peer certificate's Authority Information Access (AIA) extension, edit the server.xml file and
  • Set the enableOCSP to true.
  • Remove the ocspResponderURL parameter.
  • Remove the ocspResponderCertNickname parameter.
For a full list of parameters you can set, see Table 9.10, “OCSP Parameters for server.xml”.

Important

In addition to these settings, all peer certificates must contain the AIA extension if the desired result is an OCSP verification for that particular certificate. Otherwise, if the extension is missing, the verification step will be skipped.
Also make sure that all included AIA extension URLs are correct and reachable. This is due to the fact that when the system tries to contact an unreachable OCSP server, the system will report back that the certificate in question has been rejected as a bad certificate.

Example 9.4. server.xml

<Connector name="Secure"
     enableOCSP="true"
     ocspCacheSize="1000"
     ocspMinCacheEntryDuration="60"
     ocspMaxCacheEntryDuration="120"
     ocspTimeout="10"
     ...
/>
Additionally, set the trust of the OCSP signing certificate. For details, see Section 9.4.1.2.1, “Setting Trust of the OCSP Signing Certificate”.
9.4.1.2.3. 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

9.4.1.3. 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.
9.4.1.3.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.
9.4.1.3.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 9.4.1.3.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.
9.4.1.3.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 9.4.1.3.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.
9.4.1.3.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 9.4.1.3.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.
9.4.1.3.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 9.4.1.3.1, “TLS Session Timeout” and Section 9.4.1.3.2, “HTTP Session Timeout” to accommodate the expected delay.

9.4.2. web.xml

9.4.2.1. Removing Unused Interfaces from web.xml (CA Only)

Several legacy interfaces (for features like bulk issuance or the policy framework) are still included in the CA's web.xml file. However, since these features are deprecated and no longer in use, then they can be removed from the CA configuration to increase security.
  1. Stop the CA. 
    systemctl stop pki-tomcatd@instance_name.service
    OR 
    systemctl stop pki-tomcatd-nuxwdog@instance_name.service (if using nuxwdog watchdog)
  2. Open the web files directory for the CA. For example: 
    cd /var/lib/pki/pki-tomcat/ca/webapps/ca/WEB-INF
  3. Back up the current web.xml file. 
    cp web.xml web.xml.servlets
  4. Edit the web.xml file and remove the entire <servlet> entries for each of the following deprecated servlets:
    • caadminEnroll
    • cabulkissuance
    • cacertbasedenrollment
    • caenrollment
    • caProxyBulkIssuance
    For example, remove the caadminEnroll servlet entry: 
    <servlet>
      <servlet-name>  caadminEnroll  </servlet-name>
      <servlet-class> com.netscape.cms.servlet.cert.EnrollServlet
</servlet-class>
             <init-param><param-name>  GetClientCert  </param-name>
                         <param-value> false       </param-value> </init-param>
             <init-param><param-name>  successTemplate  </param-name>
                         <param-value> /admin/ca/EnrollSuccess.template
</param-value> </init-param>
             <init-param><param-name>  AuthzMgr    </param-name>
                         <param-value> BasicAclAuthz </param-value>
</init-param>
             <init-param><param-name>  authority   </param-name>
                         <param-value> ca          </param-value> </init-param>
             <init-param><param-name>  interface   </param-name>
                         <param-value> admin          </param-value>
</init-param>
             <init-param><param-name>  ID          </param-name>
                         <param-value> caadminEnroll </param-value>
</init-param>
             <init-param><param-name>  resourceID  </param-name>
                         <param-value> certServer.admin.request.enrollment
</param-value> </init-param>
             <init-param><param-name>  AuthMgr     </param-name>
                         <param-value> passwdUserDBAuthMgr </param-value>
</init-param>
   </servlet>
  5. After removing the servlet entries, remove the corresponding <servlet-mapping> entries. 
    <servlet-mapping>
      <servlet-name>  caadminEnroll  </servlet-name>
      <url-pattern>   /admin/ca/adminEnroll  </url-pattern>
</servlet-mapping>
  6. Remove three <filter-mapping> entries for an end-entity request interface. 
       <filter-mapping>
      <filter-name>  EERequestFilter              </filter-name>
      <url-pattern>  /certbasedenrollment         </url-pattern>
   </filter-mapping>

   <filter-mapping>
      <filter-name>  EERequestFilter              </filter-name>
      <url-pattern>  /enrollment                  </url-pattern>
   </filter-mapping>

   <filter-mapping>
      <filter-name>  EERequestFilter              </filter-name>
      <url-pattern>  /profileSubmit               </url-pattern>
   </filter-mapping>
  7. Start the CA again. 
    systemctl start pki-tomcatd@instance_name.service
    OR 
    systemctl start pki-tomcatd-nuxwdog@instance_name.service (if using nuxwdog watchdog)

9.4.3. Customizing Web Services

All of the subsystems (with the exception of the TKS) have some kind of a web-based services page for agents and some for other roles, like administrators or end entities. These web-based services pages use basic HTML and JavaScript, which can be customized to use different colors, logos, and other design elements to fit in with an existing site or intranet.

9.4.3.1. Customizing Subsystem Web Applications

Each PKI subsystem has a corresponding web application, which contains:
  • HTML pages containing texts, JavaScript codes, page layout, CSS formatting, and so on
  • A web.xml file, which defines servlets, paths, security constraints, and other
  • Links to PKI libraries.
The subsystem web applications are deployed using context files located in the /var/lib/pki/pki-tomcat/conf/Catalina/localhost/ directory, for example, the ca.xml file: 
<Context docBase="/usr/share/pki/ca/webapps/ca" crossContext="true" allowLinking="true">
    ...
</Context>
The docBase points to the location of the default web application directory, /usr/share/pki/.
To customize the web application, copy the web application directory into the instance's webapps directory: 
$ cp -r /usr/share/pki/ca/webapps/ca /var/lib/pki/pki-tomcat/webapps
Then change the docBase to point to the custom web application directory relative from the webapps directory: 
<Context docBase="ca" crossContext="true" allowLinking="true">
    ...
</Context>
The change will be effective immediately without the need to restart the server.
To remove the custom web application, simply revert the docBase and delete the custom web application directory: 
$ rm -rf /var/lib/pki/pki-tomcat/webapps/ca

9.4.3.2. Customizing the Web UI Theme

The subsystem web applications in the same instance share the same theme, which contains:
  • CSS files, which determine the global appearance
  • Image files including logo, icons, and other
  • Branding properties, which determine the page title, logo link, title color, and other.
The Web UI theme is deployed using the pki.xml context file in the /var/lib/pki/pki-tomcat/conf/Catalina/localhost/ directory: 
<Context docBase="/usr/share/pki/common-ui" crossContext="true" allowLinking="true">
    ...
</Context>
The docBase points to the location of the default theme directory, /usr/share/pki/.
To customize the theme, copy the default theme directory into the pki directory in the instance's webapps directory: 
$ cp -r /usr/share/pki/common-ui /var/lib/pki/pki-tomcat/webapps/pki
Then change the docBase to point to the custom theme directory relative from the webapps directory: 
<Context docBase="pki" crossContext="true" allowLinking="true">
    ...
</Context>
The change will be effective immediately without the need to restart the server.
To remove the custom theme, simply revert the docBase and delete the custom theme directory: 
$ rm -rf /var/lib/pki/pki-tomcat/webapps/pki

9.4.3.3. Customizing TPS Token State Labels

The default token state labels are stored in the /usr/share/pki/tps/conf/token-states.properties file and described in Section 2.5.2.4.1.4, “Token State and Transition Labels”.
To customize the labels, copy the file into the instance directory: 
$ cp /usr/share/pki/tps/conf/token-states.properties /var/lib/pki/pki-tomcat/tps/conf
The change will be effective immediately without the need to restart the server.
To remove the customized labels, simply delete the customized file: 
$ rm /var/lib/pki/pki-tomcat/tps/conf/token-states.properties