Configuring the RunMyJobs HTTP or HTTPS Interface

on-site-related topic

You can tailor RunMyJobs 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 RunMyJobs, 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"/>

Change the default port 10180 to a port that suits your needs. For example, to 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, RunMyJobs accessible.

If you disable the Connector with the licensed port, however, RunMyJobs will require a new license. To avoid this issue, Redwood recommends staying with the licensed port number. If you disable the HTTP Connector in favor of an HTTPS Connector, make sure the HTTPS Connector uses the licensed port.

Alternatively, you can use a redirectPort on the HTTP Connector to redirect to the HTTPS Connector, and create a server.properties file in the conf directory to set the port for the system ID (which is 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

Encrypting the RunMyJobs Connection

To encrypt the connection to RunMyJobs, you need a Certificate for RunMyJobs, which you can purchase from a Certificate Authority or create yourself. If RunMyJobs is going to be accessible internally only, then a self-signed certificate will work.

RunMyJobs 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. The NIO Connector is the default. It uses the JSSE libraries, so you must keep your JVM up-to-date, because an outdated JVM could expose your central RunMyJobs 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 RunMyJobs, in case it ships with an updated version of Apache Tomcat (compile time is negligible, and compilation can be automated with a shell script).

Depending on how and where you retrieve your JVM from, you might have to install the Unlimited strength Java Cryptography Extension (JCE), because 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 this extension, 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

To test the Java cryptographic extension, issue the following code in the Shell screen (Configure > Automate > Scripting Tools > 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 RunMyJobs command line system tools support the following cipher suites, grouped by Connector. Note that the syntax for specifying cipher suite names and lists depends on your Connector. 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.

The OpenSSL naming convention for use with the APR Connector is:

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

The IANA Transport Layer Security naming convention for use with the NIO Connector (JSSE) is:

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

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 can 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 that of the main Connector, for licensing reasons.

Hardening

Protecting Cookies

You can 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>

Forced Encryption

You can force connections to use the encrypted Connector by setting the redirectPort attribute on the Connector in j2ee/cluster/server1/conf/server.xml and adding 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 can 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

Do one of the following things:

  1. Use a Certificate signed by a trusted CA.
  2. Create a local keystore.
  3. Create a Certificate Signing Request (CSR).
  4. Request your purchased Certificate.
  5. Import the Certificate.
  6. Create a keystore with a self-signed Certificate.
  7. Configure Redwood Platform for Encryption.
  8. 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 if you purchase a Certificate)
  • Installed and configured Java Development Kit (JDK), which should ideally be the latest version shipped by the platform vendor.

Procedure

Troubleshooting the APR Connector

The Library is Incompatible

If the library is not compatible with your version of RunMyJobs, 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 because 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 because 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