13.4. 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 user types, 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.

13.4.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/ direcotry, 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

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

13.4.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 the Red Hat Certificate System Planning, Installation, and Deployment Guide.
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

13.4.4. Setting Limits on Searches through the CA End-Entities Pages

Large PKIs can have tens of thousands, even millions, of certificates, keys, and requests maintained in its databases. When users search for their certificates or agents list requests, then, it is possible for thousands or millions of entries to be returned. Large search results can significantly affect CA performance, so it is possible to limit the number of results returned for a search or the amount of time that searches can take.
There are two files that can manage search limits for the CA end-entities pages:
  • The CS.cfg file in the /var/lib/pki/instance_name/conf/ca directory
  • The web.xml file in the /usr/share/pki/ca/webapps/ca/WEB-INF/ directory (default), or if configured, the customized one under /var/lib/pki/instance-name/webapps/.
The CS.cfg file has a single parameter which can set the maximum number of returned results for all user interfaces for all search types. To set this value:
  1. Stop the CA instance. For example: 
    systemctl stop pki-tomcatd@instance_name.service
  2. Open the CS.cfg file. 
    vim /var/lib/pki/instance_name/conf/ca/CS.cfg
  3. Change the ca.maxSearchReturns line to set the number of entries to return. The default is 1000. 
    # maxSearchReturns - limits number of search results returned by SearchReqs and SrchCerts

ca.maxSearchReturns=1000
  4. Start the CA instance. For example: 
    systemctl start pki-tomcatd@instance_name.service
The web.xml file provides more control over the results settings:
  • For one thing, both the number of results and the time limit for searches can be set, as opposed to
  • Additionally, each interface — admin, agents, and end-entities — can be configured with a different result limit and time limit.
  • Each operation can be configured with a different result limit and time limit. This means that searching for certificate requests can have different search limits than searching for certificates or CRLs.
The two parameters in the web.xml file which set the search limits are maxResults and timeLimits. These parameters are added as <param-value> lines to a servlet entry. Either one or both can be set for each entry.
Each servlet entry is identified in <servlet-name> tags and the interface (web services pages) that the servlet is used for is identified in the <param-name>interface</param-name> parameter.
Example 13.1, “web.xml Search Limit Settings” shows the setting for a time limit for searching for requests in the agent interface and the setting for a maximum number of results limit for the listing certificates search in the end-entities interface.

Example 13.1. web.xml Search Limit Settings

     <servlet-name>  casearchReqs  </servlet-name>
...
             <init-param><param-name>  interface  </param-name>
                         <param-value> agent      </param-value> </init-param>
...
             <init-param><param-name>  timeLimits  </param-name>
                         <param-value> 10 </param-value> </init-param>


     <servlet-name>  caListCerts  </servlet-name>
...
             <init-param><param-name>  interface   </param-name>
                         <param-value> ee          </param-value> </init-param>
             <init-param><param-name>  maxResults  </param-name>
                         <param-value> 1000 </param-value> </init-param>

13.4.5. Setting SSL Session Timeouts

All of the PKI subsystem instances have a default SSL session timeout period of 30 minutes. This timeout removes data from the session cache when the timeout period (meaning, the inactive period) is reached, which decreases the ability of unauthorized users to access that information.
Each CA, KRA, OCSP, TKS, and TPS instance has its own Tomcat service which powers its web services pages. The configuration for the web services is in the /usr/share/pki/subsystem_type/webapps/subsystem_type/WEB-INF/web.xml file in the <session-timeout> tag.
To change the session timeout for a particular instance, follow the instructions in Section 13.4.1, “Customizing Subsystem Web Applications”, stop the instance, edit the appropriate web.xml file(s), and restart the instance.