Configuring the HTTP or HTTPS Interface of Redwood Platform

on-site-related topic

Redwood Platform can be tailored to your needs by editing the server.xml file located in the <install_dir>/j2ee/cluster/server<n>/conf directory, where <install_dir> is the directory where you unpacked Redwood Platform, and <n> the server number; usually 1. You can set the HTTP port and fine-tune the application server.

Changing the HTTP Port

You can change the HTTP port by editing the following section of the server.xml file:

Copy 
    <Connector port="10180" allowTrace="false" protocol="org.apache.coyote.http11.Http11Protocol"
      URIEncoding="UTF-8" compression="2048"
      compressableMimeType="text/html,text/xml,text/plain,text/javascript,text/css" maxThreads="150"
      connectionTimeout="20000" keepAliveTimeout="90000"/>

Simply change the default port 10180 to a port that suits your needs. For example, in order to not confuse users and because no other web server was running on the server, at Example Inc, we set the port to 80:

Copy 
    <Connector port="80" allowTrace="false" protocol="org.apache.coyote.http11.Http11Protocol"
      URIEncoding="UTF-8" compression="2048"
      compressableMimeType="text/html,text/xml,text/plain,text/javascript,text/css" maxThreads="150"
      connectionTimeout="20000" keepAliveTimeout="90000"/>

Licensing

Licenses take the port into account. As long as the highest port in use is licensed, Redwood Server will be accessible. As soon as you disable the connector with the licensed port, Redwood Server will require a new license. To avoid this issue, Redwood recommends sticking to the licensed port; that is, if you disable the HTTP connector in favor of an HTTPS connector, you should ensure the HTTPS connector uses the licensed port.

Alternatively, you can use a redirectPort on the HTTP connector redirecting to the HTTPS connector and create a server.properties file in the conf directory to set the port for the system ID, which will be used for licensing.

For example, to set the port for licensing to 12345, create a server.properties file in the conf directory containing the following:

Copy 
license.port=12345

Encrypted Redwood Platform

You can use encryption to secure the connection to Redwood Platform. You need a certificate for Redwood Platform which you can purchase from a Certificate Authority or create yourself. If Redwood Platform is going to be accessible internally only, then a self-signed certificate is all you need.

Redwood Platform is based on Apache Tomcat 9 and accepts the same HTTP/HTTPS connector configurations.

Redwood recommends you use either the NIO or the APR connector. Note that the NIO connector is used by default. The NIO connector uses the JSSE libraries, you therefore have to ensure that you keep your JVM up-to-date, as an outdated JVM could expose your central Redwood Server. If you choose the APR connector, you will need to keep your OpenSSL libraries up-to-date. You will also have to compile the library each time you upgrade Redwood Platform, in case it ships with an updated version of Apache Tomcat; note that compile time is negligible and can be automated with a shell script.

Note that depending on how and where you retrieve your JVM from, you might have to install the Unlimited strength Java Cryptography Extension (JCE), as this is required if you use the NIO connector with strong cryptographic ciphers or you want to access a secured central Redwood Server from a Java client. If you need the extension, please consult the documentation of your JVM vendor for information on how to obtain it; for Oracle, see the Readme. Eclipse Adoptium Temurin and IBM Semeru ship the Java Cryptographic Extension with the JDK.

Test Java Cryptographic Extension

You issue the following code in the web-based shell ( Scripting > Shell ):

Copy 
{
  int maxKeyLen = javax.crypto.Cipher.getMaxAllowedKeyLength("AES");
  //without JCE, maxKeyLen is 128, with JCE, it is Integer.MAX_VALUE
  if (maxKeyLen < 129)
  {
    jcsOut.println("No, you do not have the Java Cryptographic Extensions installed!\n Maximum key length is set to: " + maxKeyLen);
  }
  else
  {
    jcsOut.println("Yes, you have the Java Cryptographic Extensions installed!\n Maximum key length is set to: " + maxKeyLen);
  }
}

Cipher Suites

Supported Mozilla Firefox versions and the Redwood Server system tools ( jtool ) support the following cipher suites, grouped by connector. Note that the syntax for specifying cipher suite names and lists depends on your connector (NIO is the default); TLS 1.3 cipher suites TLS_AES_128_GCM_SHA256 and TLS_AES_256_GCM_SHA384 are for TLS 1.3 or higher and have unified names for both connectors.

OpenSSL naming convention for use with the APR connector:

Copy 
TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-DSS-AES128-GCM-SHA256:
ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:
ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA

IANA Transport Layer Security naming convention for use with the NIO connector (JSSE):

Copy 
TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_DHE_DSS_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256

And the following are inherently insecure and should not be used, hence the ! which disallows them (to use this list with the APR connector, ensure it is a colon ( : ) separated list):

Copy 
 !aNULL,!eNULL,!EXPORT,!DES,!RC4,!3DES,!MD5,!PSK

Redwood recommends you use these cipher suites (the list above and the list of exclusions) in your configuration.

If a client needs to connect to your central Redwood Server and does not support these strong ciphers, you add a second connector, specifically for your client. You configure your firewall to restrict connections to this connector to your client. The port number should be smaller than the main connector, for licensing reasons.

Hardening

Protecting Cookies

You add the secure flag to cookies by adding or amending the <cookie-config> in j2ee/cluster/server1/conf/web.xml:

Locate the <session-config> in web.xml:

Copy 
    <session-config>
        <session-timeout>30</session-timeout>
    </session-config>

The add or amend the <cookie-config> tag as follows:

Copy 
    <session-config>
        <session-timeout>30</session-timeout>
        <cookie-config>
            <secure>true</secure>
        </cookie-config>
    </session-config>

Force use of Encryption

You force connections to use the encrypted connector by setting the redirectPort attribute on the connector in j2ee/cluster/server1/conf/server.xml and add a filter in j2ee/cluster/server1/conf/web.xml:

Extract from j2ee/cluster/server1/conf/server.xml:

Copy 
<Connector port="10180"
           scheme="http"
           redirectPort="<port>"
[...]

Extract from j2ee/cluster/server1/conf/web.xml:

Copy 
[...]
<security-constraint>
  <web-resource-collection>
    <web-resource-name>redwood</web-resource-name>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>
[...]

HTTP Strict Transport Security (HSTS) Policy

You enforce the HSTS policy by adding a number of security filters to web.xml:

Copy 
<filter>
  <filter-name>httpHeaderSecurity</filter-name>
  <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
  <async-supported>true</async-supported>
  <init-param>
    <param-name>hstsEnabled</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>hstsMaxAgeSeconds</param-name>
    <param-value>31536000</param-value>
  </init-param>
  <init-param>
    <param-name>hstsIncludeSubDomains</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>antiClickJackingOption</param-name>
    <param-value>SAMEORIGIN</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>httpHeaderSecurity</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>

Process Flow

NIO Connector

  1. Perform one of the following:
  2. Use a certificate signed by a trusted CA.
  3. Create a local keystore.
  4. Create a Certificate Signing Request (CSR).
  5. Request your purchased certificate.
  6. Import the certificate.
  7. Create a keystore with a self-signed certificate.
  8. Configure Redwood Platform for Encryption.
  9. Update the ContextURL registry entry.

APR Connector

  1. Create a Certificate Signing Request (CSR).
  2. Perform one of the following:
  3. Request your purchased certificate.
  4. Create a private key and a self-signed certificate.
  5. Install the certificate.
  6. Configure Redwood Platform for Encryption.
  7. Update the ContextURL registry entry.

Prerequisites

  • OpenSSL for key creation and certificate signing (optional, not needed when you purchase a certificate)
  • Installed and configured Java Development Kit (JDK), which should ideally be the latest version shipped by the platform vendor (it must be supported).

Procedure

Troubleshooting the APR Connector

The Library is Incompatible

The library is not compatible with your version of Redwood Platform, please compile the library as instructed above.

Copy 
SEVERE: An incompatible version 1.1.27 of the APR based Apache Tomcat Native library is installed, while Tomcat requires version 1.1.32

A Certificate is not Encoded in PEM

The following error was encountered when the CA certificate was not encoded in PEM.

Copy 
SEVERE: Failed to initialize end point associated with ProtocolHandler ["http-apr-52900"]
java.lang.Exception: Unable to configure locations for client authentication (error:00000000:lib(0):func(0):reason(0))

Use the following command to encode the certificate in PEM:

Copy 
$ openssl x509 -inform DER -outform PEM -in <ca_cert_file> -out <ca_crt_file_pem>

Troubleshooting the NIO Connector

Missing Java Cryptographic Extension

The following exception was thrown in <install_dir>/j2ee/cluster/server<n>/logs/tomcat.log when the cipher names did not match the syntax of the connector.

Copy 
org.apache.tomcat.util.net.NioEndpoint setSocketOptions
SEVERE:
javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)
 at sun.security.ssl.Handshaker.activate(Handshaker.java:503)
 at sun.security.ssl.SSLEngineImpl.kickstartHandshake(SSLEngineImpl.java:729)
 at sun.security.ssl.SSLEngineImpl.beginHandshake(SSLEngineImpl.java:756)
 at org.apache.tomcat.util.net.SecureNioChannel.reset(SecureNioChannel.java:88)
 at org.apache.tomcat.util.net.SecureNioChannel.<init>(SecureNioChannel.java:70)
 at org.apache.tomcat.util.net.NioEndpoint.setSocketOptions(NioEndpoint.java:545)
 at org.apache.tomcat.util.net.NioEndpoint$Acceptor.run(NioEndpoint.java:703)
 at java.lang.Thread.run(Thread.java:745)

Troubleshooting with OpenSSL

The following command will print the TLS protocol as well as the cipher suite that has been chosen for the connection.

Copy 
openssl s_client -connect <server>:<port>

See Also