docs: document the (weak) random value situation in rustls builds

Closes #14770

diff --git a/docs/EXPERIMENTAL.md b/docs/EXPERIMENTAL.md
index 670e19156c84ad29f19b78e63dfe944512fcb86c..b1e3710ed7ed59ca3f5295cb73085d6271bf3076 100644 (file)
--- a/docs/EXPERIMENTAL.md
+++ b/docs/EXPERIMENTAL.md
@@ -40,6 +40,8 @@ Graduation requirements:
 
 - HTTP/1 and HTTP/2 support, including multiplexing
 
+(Hyper is marked for deprecation. It cannot graduate.)
+
 ###  HTTP/3 support (non-ngtcp2 backends)
 
 Graduation requirements:
@@ -54,6 +56,7 @@ Graduation requirements:
 Graduation requirements:
 
 - a reasonable expectation of a stable API going forward.
+- a sufficient approach to avoid using weak random numbers
 
 ### WebSocket
 

diff --git a/docs/RUSTLS.md b/docs/RUSTLS.md
index a4196410c65103123b93e10eecf153f6ba3432ec..893fd2134883fa968191b5469277972721a0db0c 100644 (file)
--- a/docs/RUSTLS.md
+++ b/docs/RUSTLS.md
@@ -29,3 +29,18 @@ Now configure and build curl with Rustls:
     % autoreconf -fi
     % ./configure --with-rustls=${HOME}/rustls-ffi-built
     % make
+
+## Randomness
+
+Every TLS libcurl curl supports - *except* Rustls - provides a function for
+curl to extract cryptographically safe random numbers with.
+
+When you build curl with Rustls, curl uses its own internal attempts to get a
+decent random value:
+
+1. Windows specific APIs
+2. arc4random
+
+If neither of those are present, then curl using Rustls falls back to **weak
+pseudo-random values**, and thus weakening several curl authentication
+implementations.