Botan 3.14.1
Crypto and TLS for C&
jitter_rng.cpp
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#include <botan/jitter_rng.h>
9
10#include <botan/assert.h>
11#include <botan/exceptn.h>
12#include <botan/mutex.h>
13#include <botan/internal/int_utils.h>
14
15#include <jitterentropy.h>
16
17/*
18* BSI AIS 20/31 NTG.1 support (JENT_NTG1) was added in jitterentropy 3.7.0.
19* The version encoding used by JENT_VERSION and jent_version() is
20* major * 1000000 + minor * 10000 + patchlevel * 100.
21*/
22#define BOTAN_JITTER_RNG_NTG1_MIN_VERSION 3070000
23
24#if defined(JENT_NTG1) && JENT_VERSION >= BOTAN_JITTER_RNG_NTG1_MIN_VERSION
25 #define BOTAN_JITTER_RNG_HAS_NTG1
26#endif
27
28namespace Botan {
29
30class Jitter_RNG_Internal final {
31 public:
32 Jitter_RNG_Internal(Jitter_RNG::Mode mode, size_t osr);
33 ~Jitter_RNG_Internal();
34 void collect_into_buffer(std::span<uint8_t> buf);
35
36 Jitter_RNG_Internal(const Jitter_RNG_Internal& other) = delete;
37 Jitter_RNG_Internal(Jitter_RNG_Internal&& other) = delete;
38 Jitter_RNG_Internal& operator=(const Jitter_RNG_Internal& other) = delete;
39 Jitter_RNG_Internal& operator=(Jitter_RNG_Internal&& other) = delete;
40
41 private:
42 static unsigned int flags_for_mode(Jitter_RNG::Mode mode);
43
44 mutex_type m_mutex;
45 rand_data* m_rand_data;
46};
47
48unsigned int Jitter_RNG_Internal::flags_for_mode(Jitter_RNG::Mode mode) {
49 switch(mode) {
51 return 0;
53 // enable the SP800-90B health tests
54 return JENT_FORCE_FIPS;
56#if defined(BOTAN_JITTER_RNG_HAS_NTG1)
57 /*
58 * An older runtime library would silently ignore the unknown flag bit
59 * and hand out an entropy collector which is not NTG.1 compliant, so
60 * the version the headers were taken from is not sufficient here.
61 */
62 if(jent_version() < BOTAN_JITTER_RNG_NTG1_MIN_VERSION) {
63 throw Not_Implemented("The linked jitterentropy library is too old to support NTG.1");
64 }
65
66 /*
67 * Enable BSI AIS 20/31 3.0 NTG.1 mode
68 * NTG.1 implies FIPS mode within jitterentropy
69 */
70 return JENT_NTG1;
71#else
72 throw Not_Implemented("Botan was built against a jitterentropy version without NTG.1 support");
73#endif
74 }
75
77}
78
80#if defined(BOTAN_JITTER_RNG_HAS_NTG1)
81 return jent_version() >= BOTAN_JITTER_RNG_NTG1_MIN_VERSION;
82#else
83 return false;
84#endif
85}
86
87Jitter_RNG_Internal::Jitter_RNG_Internal(Jitter_RNG::Mode mode, size_t osr) {
88 const auto oversampling_rate =
89 checked_cast_to_or_throw<unsigned int, Invalid_Argument>(osr, "Jitter_RNG oversampling rate is too large");
90 const unsigned int flags = flags_for_mode(mode);
91
92 /*
93 * This performs new health checks for the chosen osr and flags.
94 * It is safe to do this multiple times, it will not alter existing
95 * instances.
96 *
97 * If flags and osr are used, use the same values for init and alloc.
98 */
99 const int result = jent_entropy_init_ex(oversampling_rate, flags);
100
101 // no further details documented regarding the return value
102 if(result != 0) {
103 throw Internal_Error("Jitter_RNG_Internal initialization failed");
104 }
105
106 m_rand_data = jent_entropy_collector_alloc(oversampling_rate, flags);
107 if(m_rand_data == nullptr) {
108 throw Internal_Error("Jitter_RNG_Internal collector allocation failed");
109 }
110}
111
112Jitter_RNG_Internal::~Jitter_RNG_Internal() {
113 const lock_guard_type<mutex_type> lock(m_mutex);
114 if(m_rand_data != nullptr) {
115 jent_entropy_collector_free(m_rand_data);
116 m_rand_data = nullptr;
117 }
118}
119
120void Jitter_RNG_Internal::collect_into_buffer(std::span<uint8_t> buf) {
121 if(buf.empty()) {
122 return;
123 }
124
125 const lock_guard_type<mutex_type> lock(m_mutex);
126 BOTAN_STATE_CHECK(m_rand_data != nullptr);
127
128 ssize_t num_bytes = jent_read_entropy_safe(&m_rand_data, reinterpret_cast<char*>(buf.data()), buf.size());
129 if(num_bytes < 0) {
130 const auto error_msg = [&]() -> std::string_view {
131 switch(num_bytes) {
132 case -1: // should never happen because of the check above
133 return "JitterRNG: Uninitialized";
134 case -2:
135 return "JitterRNG: SP800-90B repetition count online health test failed";
136 case -3:
137 return "JitterRNG: SP800-90B adaptive proportion online health test failed";
138 case -4:
139 return "JitterRNG: Internal timer generator could not be initialized";
140 case -5:
141 return "JitterRNG: LAG predictor health test failed";
142 case -6:
143 return "JitterRNG: Repetition count test (RCT) failed permanently";
144 case -7:
145 return "JitterRNG: Adaptive proportion test (APT) failed permanently";
146 case -8:
147 return "JitterRNG: LAG prediction test failed permanently";
148 // the following are only returned by jitterentropy 3.7.0 and newer
149 case -9:
150 return "JitterRNG: Repetition count test with memory failed";
151 case -10:
152 return "JitterRNG: Repetition count test with memory failed permanently";
153 default:
154 return "JitterRNG: Error reading entropy";
155 }
156 }();
157 throw Internal_Error(error_msg);
158 }
159
160 // According to the docs, `jent_read_entropy_safe` itself runs its logic as often
161 // as necessary to gather the requested number of bytes,
162 // so this should actually never happen.
163 BOTAN_ASSERT(static_cast<size_t>(num_bytes) == buf.size(), "JitterRNG produced the expected number of bytes");
164}
165
166Jitter_RNG::Jitter_RNG(Mode mode, size_t osr) : m_jitter{std::make_unique<Jitter_RNG_Internal>(mode, osr)} {}
167
168Jitter_RNG::~Jitter_RNG() = default;
169
171 /* ignored - jitterentropy library does not support this */
172}
173
174void Jitter_RNG::fill_bytes_with_input(std::span<uint8_t> out, std::span<const uint8_t> in) {
175 BOTAN_UNUSED(in);
176
177 m_jitter->collect_into_buffer(out);
178}
179
180} // namespace Botan
#define BOTAN_UNUSED
Definition assert.h:151
#define BOTAN_STATE_CHECK(expr)
Definition assert.h:49
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:69
#define BOTAN_ASSERT_UNREACHABLE()
Definition assert.h:173
static bool ntg1_supported()
Jitter_RNG(Mode mode=Mode::Default, size_t osr=default_osr)
~Jitter_RNG() override
void clear() override
#define BOTAN_JITTER_RNG_NTG1_MIN_VERSION
noop_mutex mutex_type
Definition mutex.h:40
secure_vector< T > lock(const std::vector< T > &in)
Definition secmem.h:145
constexpr RT checked_cast_to_or_throw(AT i, std::string_view error_msg_on_fail)
Definition int_utils.h:91
lock_guard< T > lock_guard_type
Definition mutex.h:58