Botan 3.14.1
Crypto and TLS for C&
stateful_key_index_registry.h
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#ifndef BOTAN_STATEFUL_KEY_INDEX_REGISTRY_H_
9#define BOTAN_STATEFUL_KEY_INDEX_REGISTRY_H_
10
11#include <botan/mutex.h>
12#include <botan/types.h>
13#include <botan/internal/os_utils.h>
14#include <array>
15#include <map>
16#include <optional>
17#include <span>
18#include <string_view>
19
20namespace Botan {
21
22/**
23 * A process-wide registry mapping stateful key identity to a shared
24 * monotonic counter. Ensures that independent copies of the same key
25 * material (e.g. deserialized separately) share a single leaf index,
26 * preventing catastrophic one-time signature reuse.
27 *
28 * The same key material used with different algorithm parameters is
29 * tracked independently, since the parameters are part of the key
30 * identity. The maximum operation count is a function of the identity.
31 *
32 * Used by XMSS and HSS-LMS.
33 *
34 * If this registry or a key identity is inherited across fork(), it fails
35 * closed and refuses to issue further indices in the child process.
36 */
38 public:
39 class KeyId final {
40 public:
41 /**
42 * Create a KeyId for some kind of key material
43 *
44 * @param algo_name Algorithm name (ex "XMSS", "HSS-LMS")
45 * @param algo_params Encoding of the algorithm parameters
46 * @param max_operations Maximum number of operations the key supports.
47 * This must be derived from algo_params; equal
48 * identities must have equal maximums.
49 * @param key_material_1 First part of key identifying material
50 * @param key_material_2 Second part of key identifying material (can be omitted)
51 */
52 KeyId(std::string_view algo_name,
53 std::span<const uint8_t> algo_params,
54 uint64_t max_operations,
55 std::span<const uint8_t> key_material_1,
56 std::span<const uint8_t> key_material_2);
57
58 // A default constructed KeyId permits no operations
59 KeyId() = default;
60
61 uint64_t max_operations() const { return m_max_operations; }
62
63 // Identity is the hash; the maximum is not hashed in, since an
64 // inconsistent maximum forking the counter would be worse than
65 // the error the registry raises for it.
66 auto operator<=>(const KeyId& other) const { return m_val <=> other.m_val; }
67
68 bool operator==(const KeyId& other) const { return m_val == other.m_val; }
69
70 private:
71 std::array<uint8_t, 32> m_val{};
72 OS::Fork_Detector m_fork_detector;
73 uint64_t m_max_operations = 0;
74
76 };
77
83
84 /**
85 * Retrieve the process-wide instance
86 */
88
89 /**
90 * Return the current counter
91 */
92 uint64_t current_index(const KeyId& key_id);
93
94 /**
95 * Reserve and return the next counter value, or nullopt if the counter
96 * has already reached the key's maximum. The counter never increments
97 * past the maximum, so it cannot wrap, and an exhausted key remains
98 * exhausted.
99 */
100 std::optional<uint64_t> reserve_next_index(const KeyId& key_id);
101
102 /**
103 * Set the counter to at least min (but if already higher it will retain its current value)
104 */
105 void set_index_lower_bound(const KeyId& key_id, uint64_t min);
106
107 /**
108 * If the current counter is >= the key's maximum returns 0, otherwise maximum - counter
109 */
110 uint64_t remaining_operations(const KeyId& key_id);
111
112 private:
113 typedef std::map<KeyId, uint64_t> RegistryMap;
114
115 RegistryMap::iterator lookup(const KeyId& key_id);
116 bool fork_detected(const KeyId& key_id);
117
119
120 mutex_type m_mutex;
121 RegistryMap m_registry;
122 OS::Fork_Detector m_fork_detector;
123 bool m_fork_detected = false;
124};
125
126} // namespace Botan
127
128#endif
KeyId(std::string_view algo_name, std::span< const uint8_t > algo_params, uint64_t max_operations, std::span< const uint8_t > key_material_1, std::span< const uint8_t > key_material_2)
Stateful_Key_Index_Registry & operator=(Stateful_Key_Index_Registry &&)=delete
uint64_t remaining_operations(const KeyId &key_id)
std::optional< uint64_t > reserve_next_index(const KeyId &key_id)
Stateful_Key_Index_Registry & operator=(const Stateful_Key_Index_Registry &)=delete
Stateful_Key_Index_Registry(Stateful_Key_Index_Registry &&)=delete
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
noop_mutex mutex_type
Definition mutex.h:40