This is an automated email from the ASF dual-hosted git repository.
markt-asf pushed a commit to branch 11.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/11.0.x by this push:
new b9395dae3d Update docs to recommend TLS rather than EncryptInterceptor
b9395dae3d is described below
commit b9395dae3dad19a2791ed343bd3d6548b29d486e
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 | 14 ++++---
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, 95 insertions(+), 61 deletions(-)
diff --git
a/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java
b/java/org/apache/catalina/tribes/group/interceptors/EncryptInterceptor.java
index a5f8b08b52..d3e206635c 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 463ea477e5..c602e3e571 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.
@@ -220,6 +221,9 @@
</attributes>
</subsection>
<subsection
name="org.apache.catalina.tribes.group.interceptors.EncryptInterceptor
Attributes">
+ <p>
+ The <code>EncryptInterceptor</code> is deprecated and should no longer be
used to secure cluster traffic.
+ </p>
<p>
The EncryptInterceptor adds encryption to the channel messages carrying
session data between nodes. For the EncryptInterceptor to be effective it
@@ -346,11 +350,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 48e947ec3c..51a2bd38dc 100644
--- a/webapps/docs/security-howto.xml
+++ b/webapps/docs/security-howto.xml
@@ -520,16 +520,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]
