From 45d621a5e67e3e7057a8c46d893fc8cd9ca6905d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Meusel?= <rene.meusel@rohde-schwarz.com>
Date: Fri, 25 Oct 2024 17:03:38 +0200
Subject: [PATCH] Add jitter_rng module to crypto documentation

---
 docs/cryptodoc/src/07_rng.rst           | 42 +++++++++++++++++++++++++
 docs/cryptodoc/src/90_bibliographie.rst |  5 +++
 2 files changed, 47 insertions(+)

diff --git a/docs/cryptodoc/src/07_rng.rst b/docs/cryptodoc/src/07_rng.rst
index bef6d930..dd7eeb98 100644
--- a/docs/cryptodoc/src/07_rng.rst
+++ b/docs/cryptodoc/src/07_rng.rst
@@ -849,6 +849,48 @@ getrandom
       4. ``buf += got``
       5. ``len = len - got``
 
+External RNG Providers
+----------------------
+
+.. _rng/jitter_rng:
+
+JitterEntropy Library
+---------------------
+
+JitterEntropy is a library that provides a random number generator based on the
+jitter of a CPU's execution time. For a detailed explanation of the RNG, its
+claimed security strength and assumptions, see the JitterEntropy documentation
+[JitterEntropy]_.
+
+Botan provides a convenient wrapper that exposes the JitterEntropy library as
+both a ``Botan::RandomNumberGenerator`` and a ``Botan::EntropySource``.
+
+.. admonition:: Construction
+
+   **Steps:**
+
+   1. Initialize the JitterEntropy library via ``jent_entropy_init()``
+   2. Instantiate a ``rand_data`` structure via ``jent_entropy_collector_alloc()``
+      with default flags and a default oversampling rate
+
+.. admonition:: Randomize
+
+   **Input:**
+
+   1. ``output``: The buffer receiving the true random bytes.
+
+   **Output:**
+
+   1. ``output``: The true random bytes to be returned
+
+   **Steps:**
+
+   1. ``jent_read_entropy_safe(rand_data, output.data(), output.size())``
+   2. If the call to ``jent_read_entropy_safe()`` fails, throw an ``Internal_Error``
+      exception, containing an error message derived from the JitterEntropy-library's
+      error code.
+
+
 Hardware Generators
 -------------------
 
diff --git a/docs/cryptodoc/src/90_bibliographie.rst b/docs/cryptodoc/src/90_bibliographie.rst
index c072e2f7..1e82e0a3 100644
--- a/docs/cryptodoc/src/90_bibliographie.rst
+++ b/docs/cryptodoc/src/90_bibliographie.rst
@@ -106,6 +106,11 @@
    Information technology -- Security techniques -- Encryption algorithms -- Part 2:
    Asymmetric ciphers (2006)
 
+.. [JitterEntropy] Stephan Müller:
+   CPU Time Jitter Based Non-Physical True Random Number Generator
+   July 2022
+   https://www.chronox.de/jent/CPU-Jitter-NPTRNG.pdf
+
 .. [KaesperSchwabe09] Käsper, E., Schwabe, P.
    Faster and Timing-Attack Resistant AES-GCM.
    Cryptographic Hardware and Embedded Systems - CHES 2009