Skip to content

Commit d0048e4

Browse files
authored
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.
1 parent 80477d3 commit d0048e4

2 files changed

Lines changed: 14 additions & 5 deletions

File tree

docs/src/main/paradox/remote-security.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,8 @@ pekko.remote.artery {
5353
Always use [substitution from environment variables](https://github.com/lightbend/config#optional-system-or-env-variable-overrides)
5454
for passwords. Don't define real passwords in config files.
5555

56-
According to [RFC 7525](https://www.rfc-editor.org/rfc/rfc7525.html), the recommended algorithms to use with TLS 1.2
57-
are:
56+
According to [RFC 9325](https://www.rfc-editor.org/rfc/rfc9325.html) (which obsoletes RFC 7525), the recommended
57+
algorithms to use with TLS 1.2 are:
5858

5959
* TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
6060
* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
@@ -73,7 +73,7 @@ system.
7373
Since Pekko remoting is inherently @ref:[peer-to-peer](general/remoting.md#symmetric-communication), both the key-store
7474
and trust-store need to be configured on each remoting node participating in the cluster.
7575

76-
The official [Java Secure Socket Extension documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html)
76+
The official [Java Secure Socket Extension documentation](https://docs.oracle.com/en/java/javase/25/security/java-secure-socket-extension-jsse-reference-guide.html)
7777
as well as the [Oracle documentation on creating KeyStore and TrustStores](https://docs.oracle.com/cd/E19509-01/820-3503/6nf1il6er/index.html)
7878
are both great resources to research when setting up security on the JVM. Please consult those resources when
7979
troubleshooting and configuring SSL.

docs/src/main/paradox/remoting.md

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -479,7 +479,7 @@ pekko {
479479
Always use [substitution from environment variables](https://github.com/lightbend/config#optional-system-or-env-variable-overrides)
480480
for passwords. Don't define real passwords in config files.
481481

482-
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:
482+
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:
483483

484484
* TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
485485
* 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
488488

489489
You should always check the latest information about security and algorithm recommendations though before you configure your system.
490490

491+
@@@ note
492+
493+
Classic remoting is deprecated in favor of @ref:[Artery Remoting](remoting-artery.md). The
494+
@ref:[Remote Security](remote-security.md) page covers additional current TLS guidance for Artery that is not
495+
duplicated here, including the TLS 1.3 cipher-suite list, custom post-handshake session verification, the
496+
`random-number-generator` recommendation, and mTLS with rotated certificates in Kubernetes.
497+
498+
@@@
499+
491500
Since a Pekko remoting is inherently @ref:[peer-to-peer](general/remoting.md#symmetric-communication) both the key-store as well as trust-store
492501
need to be configured on each remoting node participating in the cluster.
493502

494-
The official [Java Secure Socket Extension documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html)
503+
The official [Java Secure Socket Extension documentation](https://docs.oracle.com/en/java/javase/25/security/java-secure-socket-extension-jsse-reference-guide.html)
495504
as well as the [Oracle documentation on creating KeyStore and TrustStores](https://docs.oracle.com/cd/E19509-01/820-3503/6nf1il6er/index.html)
496505
are both great resources to research when setting up security on the JVM. Please consult those resources when troubleshooting
497506
and configuring SSL.

0 commit comments

Comments
 (0)