From deaf9163783fcd276224ba4798bb81c058c9704e Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Thu, 27 Aug 2026 23:35:50 +0100 Subject: [PATCH] docs: correct the stale SHA1PRNG entropy note 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 7e718c67a16..04fe82e80b9 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 09f5c95c3cf..af952ce51ea 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 5f32f714b7f..dff6972bc2e 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)