Skip to content

Configuring Tomcat JSS 7.3

Jump to bottom
Endi S. Dewata edited this page Feb 14, 2022 · 2 revisions

Overview

This document describes JSS Connector configuration.

Configuration Parameters

NSS Configuration

JSS Connector supports the following NSS configuration parameters:

  • certdbDir

  • passwordFile

  • passwordClass

SSL Configuration

JSS Connector supports the following SSL configuration parameters:

  • serverCertNickFile

    • This parameter specifies the path of a file that contains the SSL server certificate nickname.

  • sslVersionRangeStream

    • Format: <min>:<max>

    • This parameter specifies the range of allowed SSL versions for stream.

    • Valid values for <min> and <max>: ssl3, tls1_0, tls1_1, tls1_2

  • sslVersionRangeDatagram

    • Format: <min>:<max>

    • This parameter specifies the range of allowed SSL versions for datagram.

    • Valid values for <min> and <max>: ssl3, tls1_0, tls1_1, tls1_2

  • sslRangeCiphers

    • This parameter specifies the SSL ciphers to be enabled. Known ciphers are defined in SSLCipher.java.

  • strictCiphers

    • This parameter determines whether to disable the NSS default ciphers. If it’s set to true, the NSS default ciphers will be disabled, and only the ciphers specified in sslRangeCiphers will be enabled. If it’s set to false, the NSS default ciphers will remain enabled in addition to the ciphers specified in sslRangeCiphers. By default it’s false.

Deprecated parameters:

  • sslOptions

  • ssl2Ciphers

  • ssl3Ciphers

  • tlsCiphers

Note: The SSL_OptionSet-based API in NSS for controlling the enabled protocol versions are obsolete and replaced by the setSSLVersionRange calls. Therefore, if the "range" parameters are present in the attributes then the sslOptions parameter is ignored. Using the new version range API in conjunction with the older SSL_OptionSet-based API for controlling the enabled protocol versions may cause unexpected results.

OCSP Configuration

JSS Connector supports the following OCSP configuration parameters:

  • enableOCSP: boolean (default: false)

  • ocspResponderURL

  • ocspResponderCertNickname

  • ocspCacheSize

  • ocspMinCacheEntryDuration

  • ocspMaxCacheEntryDuration

  • ocspTimeout

Configuration File

server.xml

Normally, the configuration is stored in the instance’s server.xml (e.g. /var/lib/pki/pki-tomcat/conf/server.xml), mixed with other Tomcat settings:

<Connector name="Secure"
       port="8443"
       protocol="org.apache.coyote.http11.Http11Protocol"
       SSLEnabled="true"
       sslProtocol="SSL"
       scheme="https"
       secure="true"
       maxHttpHeaderSize="8192"
       acceptCount="100"
       maxThreads="150"
       minSpareThreads="25"
       enableLookups="false"
       disableUploadTimeout="true"
       sslImplementationName="org.apache.tomcat.util.net.jss.JSSImplementation"
       enableOCSP="false"
       ocspResponderURL="http://server.example.com:9080/ca/ocsp"
       ocspResponderCertNickname="ocspSigningCert cert-pki-ca"
       ocspCacheSize="1000"
       ocspMinCacheEntryDuration="60"
       ocspMaxCacheEntryDuration="120"
       ocspTimeout="10"
       strictCiphers="true"
       clientAuth="want"
       sslOptions="ssl2=false,ssl3=false,tls=true"
       ssl2Ciphers="-SSL2_RC4_128_WITH_MD5,-SSL2_RC4_128_EXPORT40_WITH_MD5,-SSL2
_RC2_128_CBC_WITH_MD5,-SSL2_RC2_128_CBC_EXPORT40_WITH_MD5,-SSL2_DES_64_CBC_WITH_
MD5,-SSL2_DES_192_EDE3_CBC_WITH_MD5"
       ssl3Ciphers="-SSL3_FORTEZZA_DMS_WITH_NULL_SHA,-SSL3_FORTEZZA_DMS_WITH_RC4
_128_SHA,+SSL3_RSA_WITH_RC4_128_SHA,-SSL3_RSA_EXPORT_WITH_RC4_40_MD5,+SSL3_RSA_W
ITH_3DES_EDE_CBC_SHA,-SSL3_RSA_WITH_DES_CBC_SHA,-SSL3_RSA_EXPORT_WITH_RC2_CBC_40
_MD5,-SSL3_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA,-SSL_RSA_FIPS_WITH_DES_CBC_SHA,+SS
L_RSA_FIPS_WITH_3DES_EDE_CBC_SHA,-SSL3_RSA_WITH_NULL_MD5,-TLS_RSA_EXPORT1024_WIT
H_RC4_56_SHA,-TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,+TLS_ECDHE_ECDSA_WITH_AES_256_
CBC_SHA"
       tlsCiphers="-TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,-TLS_ECDH_ECDSA_WITH_3DE
S_EDE_CBC_SHA,+TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,+TLS_ECDH_RSA_WITH_AES_128_CBC
_SHA,+TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,-TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,+TL
S_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,+TLS_RSA_WITH_3DES_EDE_CBC_SHA,+TLS_RSA_WITH_
AES_128_CBC_SHA,+TLS_RSA_WITH_AES_256_CBC_SHA,+TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC
_SHA,+TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,-TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
-TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,-TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE
_DSS_WITH_3DES_EDE_CBC_SHA,+TLS_DHE_DSS_WITH_AES_128_CBC_SHA,+TLS_DHE_DSS_WITH_A
ES_256_CBC_SHA,+TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_
SHA,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA"
       sslVersionRangeStream="tls1_0:tls1_2"
       sslVersionRangeDatagram="tls1_1:tls1_2"
       sslRangeCiphers="-TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,-TLS_ECDH_ECDSA_WIT
H_3DES_EDE_CBC_SHA,-TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,-TLS_ECDH_RSA_WITH_AES_12
8_CBC_SHA,-TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,-TLS_ECDH_ECDSA_WITH_AES_256_CBC_SH
A,-TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256,-TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256,
-TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,-TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,-TL
S_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,-TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,-TLS_ECD
HE_RSA_WITH_AES_128_CBC_SHA,-TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,-TLS_DHE_DSS_WIT
H_3DES_EDE_CBC_SHA,-TLS_DHE_DSS_WITH_AES_128_CBC_SHA,-TLS_DHE_DSS_WITH_AES_256_C
BC_SHA,-TLS_DHE_RSA_WITH_3DES_EDE_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_DHE_RSA_WITH_AES_128_GCM_SHA256,-TLS_DHE_DSS_WITH_A
ES_128_GCM_SHA256,-TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,-TLS_ECDHE_RSA_WITH_A
ES_128_CBC_SHA256,-TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,-TLS_ECDHE_RSA_WITH_A
ES_128_GCM_SHA256,-TLS_RSA_WITH_AES_128_CBC_SHA256,-TLS_RSA_WITH_AES_256_CBC_SHA
256,-TLS_RSA_WITH_AES_128_GCM_SHA256,+TLS_RSA_WITH_3DES_EDE_CBC_SHA,+TLS_RSA_WIT
H_AES_128_CBC_SHA,+TLS_RSA_WITH_AES_256_CBC_SHA"
       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"
       />

tomcatjss.conf (Under development)

Since version 7.2 or newer TomcatJSS supports a separate configuration file located at /etc/pki/pki-tomcat/tomcatjss.conf. The JSS Connector configuration parameters can be moved to tomcatjss.conf, leaving server.xml with just the normal Tomcat configuration:

<Connector name="Secure"
       port="8443"
       protocol="org.apache.coyote.http11.Http11Protocol"
       SSLEnabled="true"
       sslProtocol="SSL"
       scheme="https"
       secure="true"
       maxHttpHeaderSize="8192"
       acceptCount="100"
       maxThreads="150"
       minSpareThreads="25"
       enableLookups="false"
       disableUploadTimeout="true"
       sslImplementationName="org.apache.tomcat.util.net.jss.JSSImplementation"
       clientAuth="want"
       />

The customized JSS Connector settings will be stored in the instance’s tomcatjss.conf (e.g. /var/lib/pki/pki-tomcat/conf/tomcatjss.conf):

ocspResponderURL=http://server.example.com:9080/ca/ocsp
ocspResponderCertNickname=ocspSigningCert cert-pki-ca
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

The default JSS Connector settings will be stored in the default tomcatjss.conf (i.e. /usr/share/pki/server/conf/tomcatjss.conf):

enableOCSP=false
ocspCacheSize=1000
ocspMinCacheEntryDuration=60
ocspMaxCacheEntryDuration=120
ocspTimeout=10
strictCiphers=true
sslOptions=ssl2=false,ssl3=false,tls=true
ssl2Ciphers=\
 -SSL2_RC4_128_WITH_MD5,\
 -SSL2_RC4_128_EXPORT40_WITH_MD5,\
 -SSL2_RC2_128_CBC_WITH_MD5,\
 -SSL2_RC2_128_CBC_EXPORT40_WITH_MD5,\
 -SSL2_DES_64_CBC_WITH_MD5,\
 -SSL2_DES_192_EDE3_CBC_WITH_MD5
ssl3Ciphers=\
 -SSL3_FORTEZZA_DMS_WITH_NULL_SHA,\
 -SSL3_FORTEZZA_DMS_WITH_RC4_128_SHA,\
 +SSL3_RSA_WITH_RC4_128_SHA,\
 -SSL3_RSA_EXPORT_WITH_RC4_40_MD5,\
 +SSL3_RSA_WITH_3DES_EDE_CBC_SHA,\
 -SSL3_RSA_WITH_DES_CBC_SHA,\
 -SSL3_RSA_EXPORT_WITH_RC2_CBC_40_MD5,\
 -SSL3_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA,\
 -SSL_RSA_FIPS_WITH_DES_CBC_SHA,\
 +SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA,\
 -SSL3_RSA_WITH_NULL_MD5,\
 -TLS_RSA_EXPORT1024_WITH_RC4_56_SHA,\
 -TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,\
 +TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
tlsCiphers=\
 -TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,\
 -TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,\
 +TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,\
 +TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,\
 +TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,\
 -TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,\
 +TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,\
 +TLS_RSA_WITH_3DES_EDE_CBC_SHA,\
 +TLS_RSA_WITH_AES_128_CBC_SHA,\
 +TLS_RSA_WITH_AES_256_CBC_SHA,\
 +TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,\
 +TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,\
 -TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,\
 -TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,\
 -TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,\
 +TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA,\
 +TLS_DHE_DSS_WITH_AES_128_CBC_SHA,\
 +TLS_DHE_DSS_WITH_AES_256_CBC_SHA,\
 +TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA,\
 +TLS_DHE_RSA_WITH_AES_128_CBC_SHA,\
 +TLS_DHE_RSA_WITH_AES_256_CBC_SHA
sslVersionRangeStream=tls1_0:tls1_2
sslVersionRangeDatagram=tls1_1:tls1_2
sslRangeCiphers=\
 -TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,\
 -TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,\
 -TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,\
 -TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,\
 -TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,\
 -TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,\
 -TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256,\
 -TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256,\
 -TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,\
 -TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,\
 -TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,\
 -TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,\
 -TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,\
 -TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,\
 -TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA,\
 -TLS_DHE_DSS_WITH_AES_128_CBC_SHA,\
 -TLS_DHE_DSS_WITH_AES_256_CBC_SHA,\
 -TLS_DHE_RSA_WITH_3DES_EDE_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_DHE_RSA_WITH_AES_128_GCM_SHA256,\
 -TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,\
 -TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,\
 -TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,\
 -TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,\
 -TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,\
 -TLS_RSA_WITH_AES_128_CBC_SHA256,\
 -TLS_RSA_WITH_AES_256_CBC_SHA256,\
 -TLS_RSA_WITH_AES_128_GCM_SHA256,\
 +TLS_RSA_WITH_3DES_EDE_CBC_SHA,\
 +TLS_RSA_WITH_AES_128_CBC_SHA,\
 +TLS_RSA_WITH_AES_256_CBC_SHA

The default values can be overwritten by specifying the customized values in the instance’s tomcatjss.conf, for example:

# enable OCSP
enableOCSP=true

# change OCSP cache size
ocspCacheSize=1000

# set SSL version range
sslVersionRangeStream=tls1_0:tls1_2
sslVersionRangeDatagram=tls1_1:tls1_2

# configure SSL ciphers
sslRangeCiphers=\
 +TLS_RSA_WITH_AES_128_CBC_SHA

Configuration Upgrade

When a PKI server that uses JSS Connector 7.1 or older is upgraded, a script will move the current TomcatJSS settings into the instance’s tomcatjss.conf. All current settings will be considered as customized settings. If necessary, some the customized settings can be removed manually after upgrade so that it will use the default values.

When a PKI server that uses JSS Connector 7.2 or newer is upgraded, the default tomcatjss.conf may be changed, but the customized settings in instance’s tomcatjss.conf will not be changed.

Clone this wiki locally