This is an automated email from the ASF dual-hosted git repository. markt-asf pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit bb4e829af088a2afa2352c3a00aa76b086ed2e87 Author: Mark Thomas <[email protected]> AuthorDate: Thu Sep 24 14:55:00 2026 +0100 Update docs to recommend TLS rather than EncryptInterceptor Also deprecates the EncryptInterceptor --- .../group/interceptors/EncryptInterceptor.java | 3 + webapps/docs/cluster-howto.xml | 45 +++++++---- webapps/docs/config/cluster-channel.xml | 9 ++- webapps/docs/config/cluster-interceptor.xml | 91 ++-------------------- webapps/docs/config/cluster-membership.xml | 6 +- webapps/docs/config/cluster-receiver.xml | 13 ++-- webapps/docs/config/cluster.xml | 47 +++++++---- webapps/docs/security-howto.xml | 19 +++-- 8 files changed, 92 insertions(+), 141 deletions(-) diff --git a/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java b/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java index 0e48975fe4..6775db7c56 100644 --- a/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java +++ b/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java @@ -53,7 +53,10 @@ import org.apache.juli.logging.LogFactory; * algorithm being used. For example, for AES, you must use a key of either 16 bytes (128 bits), 24 bytes (192 bits), * or 32 bytes (256 bits). You can supply the raw key bytes by calling {@link #setEncryptionKey(byte[])} or the * hex-encoded binary bytes by calling {@link #setEncryptionKey(String)}. + * + * @deprecated Configure the cluster to use TLS instead. This interceptor will be removed in Tomcat 12. */ +@Deprecated public class EncryptInterceptor extends ChannelInterceptorBase implements EncryptInterceptorMBean { private static final Log log = LogFactory.getLog(EncryptInterceptor.class); diff --git a/webapps/docs/cluster-howto.xml b/webapps/docs/cluster-howto.xml index bc7d3acf80..92dad0fd46 100644 --- a/webapps/docs/cluster-howto.xml +++ b/webapps/docs/cluster-howto.xml @@ -114,25 +114,36 @@ </section> <section name="Security"> + <p> + Tomcat clustering is typically used over a secure, trusted network. If a trusted network is not + available then a cluster may be configured to use TLS. To configure a cluster to use TLS the + following changes/additions to a working non-TLS cluster configuration are required: + </p> + <ul> + <li>OpenSSL-FFM support (Java 22+ and OpenSSL library) or Tomact Native 1.2.17+ must be available to provide the TLS + support.</li> + <li>The cluster must be configured to use static membership.</li> + <li>The <code>pskKey</code> and <code>pskIdentity</code> attributes of the <code>Channel</code> must be set to the + same values on each cluster node.</li> + <li>The <code>secure</code> attribute of the <code>Channel</code> must be set to <code>true</code> on each cluster + node.</li> + <li>The <code>securePort</code> attribute of the <code>Receiver</code> must be set.</li> + <li>The <code>securePort</code> attribute of each <code>Member</code> must be set to match the associated + <code>Receiver</code>.</li> + </ul> -<p>The cluster implementation is written on the basis that a secure, trusted -network is used for all of the cluster related network traffic. It is not safe -to run a cluster on a insecure, untrusted network.</p> - -<p>There are many options for providing a secure, trusted network for use by a -Tomcat cluster. These include:</p> -<ul> - <li>private LAN</li> - <li>a Virtual Private Network (VPN)</li> - <li>IPSEC</li> -</ul> - -<p>When correctly configured, the <a -href="config/cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">EncryptInterceptor</a> -provides confidentiality and integrity protection but it does not protect -against all risks associated with running a Tomcat cluster on an untrusted -network, particularly DoS attacks.</p> + <p> + The <code>EncryptInterceptor</code> is deprecated and should no longer be used to secure cluster traffic. + </p> + <p> + Other options for providing a secure, trusted network for use by a Tomcat cluster include: + </p> + <ul> + <li>private LAN</li> + <li>a Virtual Private Network (VPN)</li> + <li>IPSEC</li> + </ul> </section> <section name="Cluster Basics"> diff --git a/webapps/docs/config/cluster-channel.xml b/webapps/docs/config/cluster-channel.xml index fb682cc211..146e123e4b 100644 --- a/webapps/docs/config/cluster-channel.xml +++ b/webapps/docs/config/cluster-channel.xml @@ -123,9 +123,10 @@ </attribute> <attribute name="secure" required="false"> - If <code>true</code>, the <code>SEND_OPTIONS_SECURE</code> flag is - added to every message. Channel startup fails if TLS is unavailable. - The default is <code>false</code>. + If <code>true</code>, the <code>SEND_OPTIONS_SECURE</code> flag is added + to every message. Both <code>pskIdentity</code> and <code>pskKey</code> + must also be configued for TLS to be enabled. Channel startup fails if + TLS is unavailable. The default is <code>false</code>. </attribute> <attribute name="pskIdentity" required="false"> @@ -137,6 +138,8 @@ The TLS pre-shared key encoded as hexadecimal characters. This must be configured together with <code>pskIdentity</code>. The key is not exposed through JMX. It should be no longer than 512 bytes for TLS 1.2. + If the value is truely random then 32 bytes are sufficient for a 256-bit + cipher suite. </attribute> <attribute name="jmxEnabled" required="false"> diff --git a/webapps/docs/config/cluster-interceptor.xml b/webapps/docs/config/cluster-interceptor.xml index f3bbd22504..266496d993 100644 --- a/webapps/docs/config/cluster-interceptor.xml +++ b/webapps/docs/config/cluster-interceptor.xml @@ -59,7 +59,6 @@ </p> <ul> <li><code>org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor</code></li> - <li><code>org.apache.catalina.tribes.group.interceptors.EncryptInterceptor</code></li> <li><code>org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor</code></li> <li><code>org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor</code></li> <li><code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code></li> @@ -176,7 +175,9 @@ to the suspect node. Default is 1000. </attribute> <attribute name="performSendTest" required="false"> - If true is set, send a test message to the suspect node. Default is true. + If true is set, send a test message to the suspect node. Default is true + unless the channel is secure in which case test messages will never be + sent. </attribute> <attribute name="performReadTest" required="false"> If true is set, read the response of the test message that sent. Default is false. @@ -219,86 +220,6 @@ </attribute> </attributes> </subsection> - <subsection name="org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes"> - <p> - The EncryptInterceptor adds encryption to the channel messages carrying - session data between nodes. For the EncryptInterceptor to be effective it - <strong>MUST</strong> be the final interceptor (ignoring the - TcpFailureDetector - see below) in the set of interceptors for any given - channel. - </p> - <p> - If using the <code>TcpFailureDetector</code>, the <code>EncryptInterceptor</code> - <i>must</i> be inserted into the interceptor chain <i>before</i> the - <code>TcpFailureDetector</code>. This is because when validating cluster - members, <code>TcpFailureDetector</code> writes channel data directly - to the other members without using the remainder of the interceptor chain, - but on the receiving side, the message still goes through the chain (in reverse). - Because of this asymmetry, the <code>EncryptInterceptor</code> must execute - <i>before</i> the <code>TcpFailureDetector</code> on the sender and <i>after</i> - it on the receiver, otherwise message corruption will occur. - </p> - <p> - The EncryptInterceptor uses the timestamp of the message to provide replay - protection. For this to be effective, clock skew between cluster nodes - should be minimised. If the clock skew is not minimised, it is likely that - a high proportion of valid messages will be rejected. - </p> - <p> - The replay protection is only effective if the configured encryption - algorithm is not malleable. The default algorithm - (<code>AES/GCM/NoPadding</code>) is not malleable and replay protection - will be effective in the default configuration. Some supported algorithms - - such as <code>AES/CBC/PKCS5Padding</code> - are malleable and the replay - protection will not be effective with such algoriths. - </p> - <attributes> - <attribute name="encryptionAlgorithm" required="false"> - <p>The encryption algorithm to be used, including the mode and padding. - Please see - <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html";>https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html</a> - for the standard JCA names that can be used. Algorithms from other JCA - providers are also supported.</p> - - <p>The EncryptInterceptor currently supports the following standard - <a href="https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation";>block-cipher modes</a>: - CBC, CFB, OFB and GCM. Of these, it is recommended that GCM is always - used due to security weaknesses with the other block-cipher modes.</p> - - <p>The length of the key will specify the flavor of the encryption - algorithm to be used, if applicable (e.g. AES-128 versus AES-256).</p> - - <p>The default algorithm is <code>AES/GCM/NoPadding</code>.</p> - </attribute> - <attribute name="encryptionKey" required="true"> - <p>The key to be used with the encryption algorithm.</p> - - <p>The key should be specified as hex-encoded bytes of the appropriate - length for the algorithm (e.g. 16 bytes / 32 characters / 128 bits for - AES-128, 32 bytes / 64 characters / 256 bits for AES-256, etc.).</p> - </attribute> - <attribute name="replayWindowTime" required="false"> - <p>Messages with a timestamp before the current time less this window or - after the current time plus this window will be rejected. This window - needs to account for clock skew across the cluster as well as the - expected maximum delay between messages being sent and received. - Specified in milliseconds. If not specified, the default value of 10000 - (10 seconds) will be used.</p> - </attribute> - <attribute name="replayWindowMessageCount" required="false"> - <p>The number of past messages for which the nonces will be tracked to - prevent replay attacks. Messages with a nonce that has already been - tracked will be rejected. If not specified, the default value of 8192 - will be used.</p> - - <p>If messages are received at a high rate, it is possible that a nonce - will be removed from the list of tracked nonces before - <code>replayWindowTime</code> milliseconds have elapsed. If that happens, - any message with a timestamp older than the last nonce evicted from the - list of tracked nonces will also be rejected.</p> - </attribute> - </attributes> - </subsection> </section> <section name="Nested Components"> @@ -345,11 +266,11 @@ Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code> </attribute> <attribute name="port" required="true"> - The port that this static member listens to for cluster messages + The port that this static member listens to for non-secure cluster messages. </attribute> <attribute name="securePort" required="false"> - The secure port this static member listens to for encrypted cluster messages - default value is <code>-1</code>, this value means the member is not listening on a secure port + The port this static member listens to for TLS protected cluster messages. The default value is + <code>-1</code>, meaning the member is not listening on a secure port. </attribute> <attribute name="host" required="true"> The host (or network interface) that this static member listens for cluster messages. diff --git a/webapps/docs/config/cluster-membership.xml b/webapps/docs/config/cluster-membership.xml index 6ea935bc66..6ead7f6ea0 100644 --- a/webapps/docs/config/cluster-membership.xml +++ b/webapps/docs/config/cluster-membership.xml @@ -277,11 +277,11 @@ Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code> </attribute> <attribute name="port" required="true"> - The port that this static member listens to for cluster messages + The port that this static member listens to for non-secure cluster messages. </attribute> <attribute name="securePort" required="false"> - The secure port this static member listens to for encrypted cluster messages - default value is <code>-1</code>, this value means the member is not listening on a secure port + The port this static member listens to for TLS protected cluster messages. The default value is + <code>-1</code>, meaning the member is not listening on a secure port. </attribute> <attribute name="host" required="true"> The host (or network interface) that this static member listens for cluster messages. diff --git a/webapps/docs/config/cluster-receiver.xml b/webapps/docs/config/cluster-receiver.xml index 2472e65493..8dd89bc201 100644 --- a/webapps/docs/config/cluster-receiver.xml +++ b/webapps/docs/config/cluster-receiver.xml @@ -73,9 +73,10 @@ from the sockets. </attribute> <attribute name="port" required="false"> - The listen port for incoming data. The default value is <code>4000</code>. - To avoid port conflicts the receiver will automatically bind to a free port within the range of - <code> port <= bindPort < port+autoBind</code> + The listen port for incoming data. The default value is <code>4000</code> unless the channel is + secure in which case this attribute will be forced to <code>-1</code> to disable the non-secure + port. If enabled, to avoid port conflicts the receiver will automatically bind to a free port + within the range of <code>port <= bindPort < port+autoBind</code> So for example, if port is 4000, and autoBind is set to 10, then the receiver will open up a server socket on the first available port in the range 4000-4009. </attribute> @@ -85,12 +86,12 @@ server socket on the <code>port</code> attribute port, and then work up <code>autoBind</code> number of times. </attribute> <attribute name="securePort" required="false"> - The secure listen port. This port is SSL enabled. If this attribute is omitted no SSL port is opened up. - There default value is unset, meaning there is no SSL socket available. + The secure listen port. This port is TLS enabled. If this attribute is omitted no TLS port is opened up. + The default value is unset, meaning there is no TLS socket available. </attribute> <attribute name="udpPort" required="false"> The UDP listen port. If this attribute is omitted no UDP port is opened up. - There default value is unset, meaning there is no UDP listener available. + The default value is unset, meaning there is no UDP listener available. </attribute> <attribute name="selectorTimeout" required="false"> The value in milliseconds for the polling timeout in the <code>NioReceiver</code>. On older versions of the JDK diff --git a/webapps/docs/config/cluster.xml b/webapps/docs/config/cluster.xml index bfaae11edf..c40aff008e 100644 --- a/webapps/docs/config/cluster.xml +++ b/webapps/docs/config/cluster.xml @@ -42,27 +42,40 @@ making the configuration seem like a lot, but don't lose faith, instead you have a tremendous control over what is going on.</p> </section> -<section name="Security"> - -<p>The cluster implementation is written on the basis that a secure, trusted -network is used for all of the cluster related network traffic. It is not safe -to run a cluster on a insecure, untrusted network.</p> -<p>There are many options for providing a secure, trusted network for use by a -Tomcat cluster. These include:</p> -<ul> - <li>private LAN</li> - <li>a Virtual Private Network (VPN)</li> - <li>IPSEC</li> -</ul> +<section name="Security"> + <p> + Tomcat clustering is typically used over a secure, trusted network. If a trusted network is not + available then a cluster may be configured to use TLS. To configure a cluster to use TLS the + following changes/additions to a working non-TLS cluster configuration are required: + </p> + <ul> + <li>OpenSSL-FFM support (Java 22+ and OpenSSL library) or Tomact Native 1.2.17+ must be available to provide the TLS + support.</li> + <li>The cluster must be configured to use static membership.</li> + <li>The <code>pskKey</code> and <code>pskIdentity</code> attributes of the <code>Channel</code> must be set to the + same values on each cluster node.</li> + <li>The <code>secure</code> attribute of the <code>Channel</code> must be set to <code>true</code> on each cluster + node.</li> + <li>The <code>securePort</code> attribute of the <code>Receiver</code> must be set.</li> + <li>The <code>securePort</code> attribute of each <code>Member</code> must be set to match the associated + <code>Receiver</code>.</li> + </ul> -<p>When correctly configured, the <a -href="cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">EncryptInterceptor</a> -provides confidentiality and integrity protection but it does not protect -against all risks associated with running a Tomcat cluster on an untrusted -network, particularly DoS attacks.</p> + <p> + The <code>EncryptInterceptor</code> is deprecated and should no longer be used to secure cluster traffic. + </p> + <p> + Other options for providing a secure, trusted network for use by a Tomcat cluster include: + </p> + <ul> + <li>private LAN</li> + <li>a Virtual Private Network (VPN)</li> + <li>IPSEC</li> + </ul> </section> + <section name="Engine vs Host placement"> <p> You can place the <code><Cluster></code> element inside either the <code><Engine></code> diff --git a/webapps/docs/security-howto.xml b/webapps/docs/security-howto.xml index acd15059b4..ec8e5039b9 100644 --- a/webapps/docs/security-howto.xml +++ b/webapps/docs/security-howto.xml @@ -510,16 +510,15 @@ </subsection> <subsection name="Cluster"> - <p>The cluster implementation is written on the basis that a secure, - trusted network is used for all of the cluster related network traffic. It - is not safe to run a cluster on a insecure, untrusted network.</p> - - <p>If you require confidentiality and/or integrity protection then you can - use the - <a href="config/cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">EncryptInterceptor</a> - to encrypt traffic between nodes. This interceptor does not protect - against all the risks of running on an untrusted network, particularly - DoS attacks.</p> + <p>Tomcat clustering is typically used over a secure, trusted network. If a trusted network is not available then + a cluster may be configured to use TLS. The <code>EncryptInterceptor</code> is deprecated and should no longer be + used to secure cluster traffic. Other options for providing a secure, trusted network for use by a Tomcat cluster + include:</p> + <ul> + <li>private LAN</li> + <li>a Virtual Private Network (VPN)</li> + <li>IPSEC</li> + </ul> </subsection> </section> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
