From: Daniel Stenberg <daniel@haxx.se>
Date: Tue, 3 Sep 2024 14:09:40 +0000 (+0200)
Subject: docs: document the (weak) random value situation in rustls builds
X-Git-Tag: curl-8_10_0~49
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9e629a1484e64ac2569ee5f28eebd0b96f5fcba5;p=thirdparty%2Fcurl.git

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

Closes #14770
---

diff --git a/docs/EXPERIMENTAL.md b/docs/EXPERIMENTAL.md
index 670e19156c..b1e3710ed7 100644
--- 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 a4196410c6..893fd21348 100644
--- 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.