This is an automated email from the ASF dual-hosted git repository.
samueleresca pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new d0048e448e docs: refresh stale TLS security recommendations in
remoting docs (#3489)
d0048e448e is described below
commit d0048e448e74deb02611c2f8ceab094a64880300
Author: Samuele Resca <[email protected]>
AuthorDate: Sun Aug 30 14:06:23 2026 +0100
docs: refresh stale TLS security recommendations in remoting docs (#3489)
Motivation:
remote-security.md and remoting.md both cited RFC 7525 (2015) as the
current source for recommended TLS cipher suites, but RFC 7525 was
obsoleted by RFC 9325 (Nov 2022). Both docs also linked to the Java
8-specific JSSE Reference Guide as "the official" documentation, even
though Pekko 2.0.x requires JDK 17+ as a minimum. remote-security.md
additionally carried a dead caveat about Java 8 runtime support for a
TLS 1.3 cipher suite. The classic (legacy) remoting.md TLS section had
also drifted out of sync with remote-security.md, which recently
gained TLS 1.3 cipher guidance, post-handshake session verification,
a random-number-generator recommendation, and mTLS-rotation-in-
Kubernetes guidance that remoting.md never received.
Modification:
- remote-security.md, remoting.md: cite RFC 9325 instead of the
obsoleted RFC 7525, noting that it obsoletes RFC 7525.
- remote-security.md, remoting.md: point the JSSE documentation link
at the current (Java SE 25) JSSE Reference Guide instead of the
Java 8 version.
- remote-security.md: drop the "(may not be supported on Java 8
runtimes)" caveat on TLS_CHACHA20_POLY1305_SHA256, which no longer
applies now that Java 8 isn't a supported runtime.
- remoting.md: add a note pointing to remote-security.md for the
additional current TLS guidance that isn't duplicated into the
deprecated classic-remoting doc, instead of letting the two pages
keep drifting out of sync.
Result:
The remoting security docs cite current IETF guidance and JDK
documentation instead of a decade-old RFC and Java 8-era links, and
classic remoting users are pointed at the fuller, current guidance
instead of being left with silently weaker advice.
Tests:
- Not run - docs only.
References:
None - identified while auditing docs/src/main/paradox for content
out of date relative to the current Pekko version and JDK support.
---
docs/src/main/paradox/remote-security.md | 6 +++---
docs/src/main/paradox/remoting.md | 13 +++++++++++--
2 files changed, 14 insertions(+), 5 deletions(-)
diff --git a/docs/src/main/paradox/remote-security.md
b/docs/src/main/paradox/remote-security.md
index 1d99c182e6..83d2b9889a 100644
--- a/docs/src/main/paradox/remote-security.md
+++ b/docs/src/main/paradox/remote-security.md
@@ -53,8 +53,8 @@ pekko.remote.artery {
Always use [substitution from environment
variables](https://github.com/lightbend/config#optional-system-or-env-variable-overrides)
for passwords. Don't define real passwords in config files.
-According to [RFC 7525](https://www.rfc-editor.org/rfc/rfc7525.html), the
recommended algorithms to use with TLS 1.2
-are:
+According to [RFC 9325](https://www.rfc-editor.org/rfc/rfc9325.html) (which
obsoletes RFC 7525), the recommended
+algorithms to use with TLS 1.2 are:
* TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
@@ -73,7 +73,7 @@ system.
Since Pekko remoting is inherently
@ref:[peer-to-peer](general/remoting.md#symmetric-communication), both the
key-store
and trust-store need to be configured on each remoting node participating in
the cluster.
-The official [Java Secure Socket Extension
documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html)
+The official [Java Secure Socket Extension
documentation](https://docs.oracle.com/en/java/javase/25/security/java-secure-socket-extension-jsse-reference-guide.html)
as well as the [Oracle documentation on creating KeyStore and
TrustStores](https://docs.oracle.com/cd/E19509-01/820-3503/6nf1il6er/index.html)
are both great resources to research when setting up security on the JVM.
Please consult those resources when
troubleshooting and configuring SSL.
diff --git a/docs/src/main/paradox/remoting.md
b/docs/src/main/paradox/remoting.md
index af952ce51e..bcf69665de 100644
--- a/docs/src/main/paradox/remoting.md
+++ b/docs/src/main/paradox/remoting.md
@@ -479,7 +479,7 @@ pekko {
Always use [substitution from environment
variables](https://github.com/lightbend/config#optional-system-or-env-variable-overrides)
for passwords. Don't define real passwords in config files.
-According to [RFC 7525](https://www.rfc-editor.org/rfc/rfc7525.html) the
recommended algorithms to use with TLS 1.2 (as of writing this document) are:
+According to [RFC 9325](https://www.rfc-editor.org/rfc/rfc9325.html) (which
obsoletes RFC 7525) the recommended algorithms to use with TLS 1.2 are:
* TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
@@ -488,10 +488,19 @@ According to [RFC
7525](https://www.rfc-editor.org/rfc/rfc7525.html) the recomme
You should always check the latest information about security and algorithm
recommendations though before you configure your system.
+@@@ note
+
+Classic remoting is deprecated in favor of @ref:[Artery
Remoting](remoting-artery.md). The
+@ref:[Remote Security](remote-security.md) page covers additional current TLS
guidance for Artery that is not
+duplicated here, including the TLS 1.3 cipher-suite list, custom
post-handshake session verification, the
+`random-number-generator` recommendation, and mTLS with rotated certificates
in Kubernetes.
+
+@@@
+
Since a Pekko remoting is inherently
@ref:[peer-to-peer](general/remoting.md#symmetric-communication) both the
key-store as well as trust-store
need to be configured on each remoting node participating in the cluster.
-The official [Java Secure Socket Extension
documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html)
+The official [Java Secure Socket Extension
documentation](https://docs.oracle.com/en/java/javase/25/security/java-secure-socket-extension-jsse-reference-guide.html)
as well as the [Oracle documentation on creating KeyStore and
TrustStores](https://docs.oracle.com/cd/E19509-01/820-3503/6nf1il6er/index.html)
are both great resources to research when setting up security on the JVM.
Please consult those resources when troubleshooting
and configuring SSL.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
