Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add jitter_rng module to crypto documentation #251

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions docs/cryptodoc/src/07_rng.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------------

Expand Down
5 changes: 5 additions & 0 deletions docs/cryptodoc/src/90_bibliographie.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading