Botan 3.14.1
Crypto and TLS for C&
stateful_key_index_registry.cpp
Go to the documentation of this file.
1/*
2 * (C) 2016 Matthias Gierlings
3 * 2026 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7
8#include <botan/internal/stateful_key_index_registry.h>
9
10#include <botan/assert.h>
11#include <botan/exceptn.h>
12#include <botan/hash.h>
13#include <algorithm>
14
15namespace Botan {
16
21
23
25
27 std::span<const uint8_t> algo_params,
28 uint64_t max_operations,
29 std::span<const uint8_t> key_material_1,
30 std::span<const uint8_t> key_material_2) :
31 m_max_operations(max_operations) {
32 auto hash = HashFunction::create_or_throw("SHA-256");
33
34 hash->update("Botan Stateful_Key_Index_Registry KeyID");
35 hash->update_be(static_cast<uint64_t>(algo_name.size()));
36 hash->update(algo_name);
37 hash->update_be(static_cast<uint64_t>(algo_params.size()));
38 hash->update(algo_params);
39 hash->update_be(static_cast<uint64_t>(key_material_1.size()));
40 hash->update(key_material_1);
41 hash->update_be(static_cast<uint64_t>(key_material_2.size()));
42 hash->update(key_material_2);
43
44 BOTAN_ASSERT_NOMSG(hash->output_length() == m_val.size());
45
46 hash->final(m_val);
47}
48
49// Lock must be held while this function is called
50Stateful_Key_Index_Registry::RegistryMap::iterator Stateful_Key_Index_Registry::lookup(const KeyId& key_id) {
51 if(this->fork_detected(key_id)) {
52 throw Invalid_State("Stateful key index registry cannot be used after fork");
53 }
54
55 auto [i, inserted] = m_registry.emplace(key_id, 0);
56
57 if(!inserted && i->first.max_operations() != key_id.max_operations()) {
58 throw Internal_Error("Stateful key was already registered with a different maximum operation count");
59 }
60
61 return i;
62}
63
64/*
65* Fork detection for the process-wide one-time signature counters.
66*
67* Reusing a stateful signature leaf index is catastrophic (signing two messages
68* under the same index compromises the key), and after fork() both processes
69* hold copy-on-write duplicates of the counters. The registry fails closed
70* rather than risk index reuse.
71*
72* There are two fork detectors, one in the registry and one in each KeyId,
73* because there are two possible cases where reuse might occur after a fork:
74*
75* - If the registry was used before the fork, then its detector will report
76* the fork, in which case the latch closes.
77*
78* - KeyId's detector catches the rarer case where a key was created prior to
79* the fork, but not used. In that case the registry has not yet been created
80* in either process, and it would be possible to use the same key (with the
81* same starting-from-0 index) in both processes.
82*
83* Fork detection is a one way latch, and intentionally coarse. Once any fork is
84* seen, the whole registry is disabled for the rest of this process, including
85* for keys that were freshly loaded in the child. This could be loosened
86* (allowing newly loaded keys to be used in the child process) but the
87* combination of stateful signature schemes plus fork() is a hazardous scenario
88* and seems best to prohibit it entirely.
89*
90* lookup() runs this on every access, so read-only queries (current_index,
91* remaining_operations, and to_bytes which serializes the current index) also
92* throw in a forked child rather than returning a possibly-unsafe value.
93*/
94bool Stateful_Key_Index_Registry::fork_detected(const KeyId& key_id) {
95 if(m_fork_detected) {
96 return true;
97 }
98
99 /*
100 * If either the registry or the KeyId was created in a different process,
101 * assume a fork occurred and latch closed.
102 */
103 if(m_fork_detector.fork_detected() || key_id.m_fork_detector.fork_detected()) {
104 m_fork_detected = true;
105 }
106
107 return m_fork_detected;
108}
109
111 const lock_guard_type<mutex_type> lock(m_mutex);
112 const auto idx = this->lookup(key_id);
113 return idx->second;
114}
115
116std::optional<uint64_t> Stateful_Key_Index_Registry::reserve_next_index(const KeyId& key_id) {
117 const lock_guard_type<mutex_type> lock(m_mutex);
118 const auto idx = this->lookup(key_id);
119 const uint64_t cur = idx->second;
120 if(cur >= key_id.max_operations()) {
121 return std::nullopt;
122 }
123 idx->second = cur + 1;
124 return cur;
125}
126
128 BOTAN_ARG_CHECK(min <= key_id.max_operations(), "Index lower bound exceeds maximum operation count");
129 const lock_guard_type<mutex_type> lock(m_mutex);
130 const auto idx = this->lookup(key_id);
131 idx->second = std::max(idx->second, min);
132}
133
135 const lock_guard_type<mutex_type> lock(m_mutex);
136 const uint64_t idx = this->lookup(key_id)->second;
137 const uint64_t max = key_id.max_operations();
138
139 if(idx >= max) {
140 return 0;
141 } else {
142 return max - idx;
143 }
144}
145
146} // namespace Botan
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311
uint64_t remaining_operations(const KeyId &key_id)
std::optional< uint64_t > reserve_next_index(const KeyId &key_id)
void set_index_lower_bound(const KeyId &key_id, uint64_t min)
static Stateful_Key_Index_Registry & global()
Stateful_Key_Index_Registry(const Stateful_Key_Index_Registry &)=delete
secure_vector< T > lock(const std::vector< T > &in)
Definition secmem.h:145
lock_guard< T > lock_guard_type
Definition mutex.h:58