This is an automated email from the ASF dual-hosted git repository.
pjfanning 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 cd5aff211b docs: correct the stale SHA1PRNG entropy note (#3481)
cd5aff211b is described below
commit cd5aff211bf50514b6d0c46d39986d92098cc900
Author: PJ Fanning <[email protected]>
AuthorDate: Fri Aug 28 07:29:03 2026 +0100
docs: correct the stale SHA1PRNG entropy note (#3481)
Motivation:
The TLS docs told users that on Linux with SHA1PRNG they should set
-Djava.security.egd=file:/dev/urandom "to prevent blocking", and that doing
so "is NOT as secure because it reuses the seed". Both halves are wrong on
any JDK Pekko supports.
Nothing about /dev/urandom reuses a seed: since Linux 4.8 both devices draw
from the same CSPRNG, and since 5.6 /dev/random no longer blocks once the
pool is seeded at boot. The note's instinct is sound but attached to the
wrong cause. The real caveat belongs to the algorithm: in
sun.security.provider.SecureRandom, SHA1PRNG seeds `state` once when it is
null and then runs a deterministic SHA-1 chain forever, whereas the platform
default NativePRNG mixes fresh kernel randomness into every request. That
holds whatever java.security.egd is set to.
The blocking advice is also close to inert. In SeedGenerator, `file:/dev/
urandom` selects NativeSeedGenerator, which on Unix is just URLSeedGenerator
reading that path; the special case only means something on Windows.
The same stale rationale is repeated in the reference.conf comments, which
justify avoiding SHA1PRNG on grounds of "blocking issues on Linux".
Modification:
Rewrite the note in remote-security.md (artery) and remoting.md (classic) to
lead with the recommendation to keep the platform default, give the
no-reseeding property as the reason to avoid SHA1PRNG, and describe the
entropy source accurately with the blocking concern marked as historical.
Fix the missing "to" in the classic copy. Update the three reference.conf
comments to match.
Result:
The note states a caveat that is true and actionable, and no longer advises
a JVM flag on grounds that have not applied for several kernel releases.
Comment-only change to reference.conf; no default or behaviour changes.
Tests:
- Not run - docs only
References:
None - follow-up from threat model review discussion
---
docs/src/main/paradox/remote-security.md | 11 +++++++++--
docs/src/main/paradox/remoting.md | 11 +++++++++--
remote/src/main/resources/reference.conf | 9 ++++++---
3 files changed, 24 insertions(+), 7 deletions(-)
diff --git a/docs/src/main/paradox/remote-security.md
b/docs/src/main/paradox/remote-security.md
index 7e718c67a1..04fe82e80b 100644
--- a/docs/src/main/paradox/remote-security.md
+++ b/docs/src/main/paradox/remote-security.md
@@ -126,8 +126,15 @@ section.
@@@ note
-When using SHA1PRNG on Linux it's recommended to specify
`-Djava.security.egd=file:/dev/urandom` as argument
-to the JVM to prevent blocking. It is NOT as secure because it reuses the seed.
+`random-number-generator` defaults to the platform `SecureRandom`, which is
the recommended
+setting. `SHA1PRNG` is a legacy algorithm: it draws a single seed at startup
and never reseeds,
+where the platform default mixes fresh kernel randomness into every request.
+
+On Linux the seed comes from `securerandom.source` (`file:/dev/random` by
default), overridable
+with `-Djava.security.egd`. On older kernels `/dev/random` could block on
hosts with little
+entropy, which is the origin of the frequently suggested
+`-Djava.security.egd=file:/dev/urandom`; current kernels do not block once the
pool is seeded
+at boot.
@@@
diff --git a/docs/src/main/paradox/remoting.md
b/docs/src/main/paradox/remoting.md
index 09f5c95c3c..af952ce51e 100644
--- a/docs/src/main/paradox/remoting.md
+++ b/docs/src/main/paradox/remoting.md
@@ -510,8 +510,15 @@ See also a description of the settings in the @ref:[Remote
Configuration](remoti
@@@ note
-When using SHA1PRNG on Linux it's recommended specify
`-Djava.security.egd=file:/dev/urandom` as argument
-to the JVM to prevent blocking. It is NOT as secure because it reuses the seed.
+`random-number-generator` defaults to the platform `SecureRandom`, which is
the recommended
+setting. `SHA1PRNG` is a legacy algorithm: it draws a single seed at startup
and never reseeds,
+where the platform default mixes fresh kernel randomness into every request.
+
+On Linux the seed comes from `securerandom.source` (`file:/dev/random` by
default), overridable
+with `-Djava.security.egd`. On older kernels `/dev/random` could block on
hosts with little
+entropy, which is the origin of the frequently suggested
+`-Djava.security.egd=file:/dev/urandom`; current kernels do not block once the
pool is seeded
+at boot.
@@@
diff --git a/remote/src/main/resources/reference.conf
b/remote/src/main/resources/reference.conf
index 5f32f714b7..dff6972bc2 100644
--- a/remote/src/main/resources/reference.conf
+++ b/remote/src/main/resources/reference.conf
@@ -725,7 +725,8 @@ pekko {
# There are two options, and the default SecureRandom is recommended:
# "" or "SecureRandom" => (default)
- # "SHA1PRNG" => Can be slow because of blocking issues on Linux
+ # "SHA1PRNG" => Legacy algorithm, seeded once at startup and never
+ # reseeded. The default is preferred.
#
# Setting a value here may require you to supply the appropriate
cipher
# suite (see enabled-algorithms section above)
@@ -1233,7 +1234,8 @@ pekko {
# There are two options, and the default SecureRandom is recommended:
# "" or "SecureRandom" => (default)
- # "SHA1PRNG" => Can be slow because of blocking issues on Linux
+ # "SHA1PRNG" => Legacy algorithm, seeded once at startup and never
+ # reseeded. The default is preferred.
#
# Setting a value here may require you to supply the appropriate
cipher
# suite (see enabled-algorithms section above)
@@ -1290,7 +1292,8 @@ pekko {
# There are two options, and the default SecureRandom is recommended:
# "" or "SecureRandom" => (default)
- # "SHA1PRNG" => Can be slow because of blocking issues on Linux
+ # "SHA1PRNG" => Legacy algorithm, seeded once at startup and never
+ # reseeded. The default is preferred.
#
# Setting a value here may require you to supply the appropriate
cipher
# suite (see enabled-algorithms section)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
