Botan 3.14.1
Crypto and TLS for C&
jitter_rng.h
Go to the documentation of this file.
1/*
2* CPU Jitter Random Number Generator
3* (C) 2024 Planck Security S.A.
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_JITTER_RNG_H_
9#define BOTAN_JITTER_RNG_H_
10
11#include <botan/rng.h>
12#include <memory>
13#include <string>
14
15namespace Botan {
16
17class Jitter_RNG_Internal;
18
19/**
20* RNG using jitterentropy (https://github.com/smuellerDD/jitterentropy-library)
21*/
23 public:
24 /**
25 * The compliance mode requested from the underlying jitterentropy library
26 */
27 enum class Mode : uint8_t {
28 /**
29 * Leave the library at its defaults. The SP800-90B health tests are
30 * then only enforced if the system itself runs in FIPS mode.
31 */
32 Default,
33
34 /**
35 * Force full SP800-90B compliance, including the online health tests,
36 * regardless of the state of the system (``JENT_FORCE_FIPS``).
37 */
38 FIPS,
39
40 /**
41 * Request AIS 20/31 NTG.1 compliance (``JENT_NTG1``). This implies
42 * FIPS mode and additionally disables the internal timer, so it is not
43 * available on platforms which have no usable high resolution timer.
44 *
45 * Requires jitterentropy 3.7.0 or later, both at build and at run
46 * time; the constructor throws Not_Implemented otherwise. See
47 * ntg1_supported().
48 */
49 NTG1,
50 };
51
52 /**
53 * Let jitterentropy pick the oversampling rate
54 */
55 static constexpr size_t default_osr = 0;
56
57 /**
58 * @return true if the linked jitterentropy supports Mode::NTG1
59 */
60 static bool ntg1_supported();
61
62 /**
63 * Create a Jitter_RNG, throwing if jitterentropy cannot be initialized
64 *
65 * @param mode the compliance mode to request from jitterentropy
66 * @param osr the oversampling rate to use. Higher values collect more
67 * timing samples per output bit, which is slower but more conservative.
68 * The default lets the library apply its own (minimal) rate. Values the
69 * library considers out of range cause the constructor to throw.
70 */
71 explicit Jitter_RNG(Mode mode = Mode::Default, size_t osr = default_osr);
72
73 ~Jitter_RNG() override;
74
75 Jitter_RNG(const Jitter_RNG& other) = delete;
76 /**
77 * Move constructor
78 */
79 Jitter_RNG(Jitter_RNG&& other) = default;
80 Jitter_RNG& operator=(const Jitter_RNG& other) = delete;
81 Jitter_RNG& operator=(Jitter_RNG&& other) = delete;
82
83 /**
84 * Return the name of this RNG type
85 * @return the name of this RNG type
86 */
87 std::string name() const override { return "JitterRNG"; }
88
89 /**
90 * Test whether this RNG has been seeded
91 * @return true if this RNG is seeded and ready for use
92 */
93 bool is_seeded() const override { return true; }
94
95 /**
96 * Test whether this RNG accepts externally provided input
97 * @return false if this RNG is known to ignore provided inputs
98 */
99 bool accepts_input() const override { return false; }
100
101 /**
102 * Clear all internally held values of this RNG
103 */
104 void clear() override;
105
106 private:
107 void fill_bytes_with_input(std::span<uint8_t> out, std::span<const uint8_t> in) override;
108
109 std::unique_ptr<Jitter_RNG_Internal> m_jitter;
110};
111
112} // namespace Botan
113
114#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
std::string name() const override
Definition jitter_rng.h:87
static bool ntg1_supported()
static constexpr size_t default_osr
Definition jitter_rng.h:55
Jitter_RNG & operator=(const Jitter_RNG &other)=delete
Jitter_RNG(Jitter_RNG &&other)=default
bool is_seeded() const override
Definition jitter_rng.h:93
Jitter_RNG(Mode mode=Mode::Default, size_t osr=default_osr)
~Jitter_RNG() override
bool accepts_input() const override
Definition jitter_rng.h:99
Jitter_RNG(const Jitter_RNG &other)=delete
Jitter_RNG & operator=(Jitter_RNG &&other)=delete