Botan 3.14.1
Crypto and TLS for C&
xmss_address.h
Go to the documentation of this file.
1/*
2 * XMSS Address
3 * (C) 2016 Matthias Gierlings
4 * 2026 Jack Lloyd
5 *
6 * Botan is released under the Simplified BSD License (see license.txt)
7 **/
8
9#ifndef BOTAN_XMSS_ADDRESS_H_
10#define BOTAN_XMSS_ADDRESS_H_
11
12#include <botan/assert.h>
13#include <botan/types.h>
14#include <array>
15#include <span>
16
17namespace Botan {
18
19/**
20 * Generic XMSS Address type holding 256 Bits of data. Properties
21 * of all three address formats L-Tree-Address, Hash-Tree-Address,
22 * OTS-Hash-Address can be called depending on the type currently
23 * assigned to the XMSS address using set_type().
24 **/
25class XMSS_Address final {
26 public:
27 /**
28 * Distinct types an XMSS_Address can represent. The available types
29 * are specified in [1] - 2.5 Hash Function Address Scheme.
30 **/
31 enum class Type : uint8_t { None = 255, OTS_Hash_Address = 0, LTree_Address = 1, Hash_Tree_Address = 2 };
32
33 /**
34 * The available modes for an XMSS Address:
35 * - Key_Mode: Used to generate the key.
36 * - Mask_Mode: Sets the n-byte bitmask (OTS-Hash-Address)
37 * - Mask_MSB_Mode: Used to generate the b most significant bytes of
38 * the 2n-byte bitmask (LTree Address and Hash Tree Address).
39 * - Mask_LSB_Mode: Used to generated the b least significant bytes
40 * of the 2n-byte bitmask. (LTree Address and Hash Tree Address).
41 **/
42 enum class Key_Mask : uint8_t { Key_Mode = 0, Mask_Mode = 1, Mask_MSB_Mode = 1, Mask_LSB_Mode = 2 };
43
44 /**
45 * retrieves the Layer Address. A call to this method is only required by XMSS_MT.
46 * The Layer Address is constantly zero for XMSS.
47 * For XMSS_MT it describes the height of the tree in the multi-tree structure.
48 *
49 * @return Layer address.
50 **/
51 uint32_t get_layer_addr() const { return get_hi32(0); }
52
53 /**
54 * sets the Layer Address. A call to this method is only required by XMSS_MT.
55 * The Layer Address is constantly zero for XMSS.
56 * For XMSS_MT it describes the height of the tree in the multi-tree structure.
57 **/
58 void set_layer_addr(uint32_t value) { set_hi32(0, value); }
59
60 /**
61 * retrieves the Tree Address. A call to this method is only required by XMSS_MT.
62 * The Tree Address is constantly zero for XMSS.
63 * For XMSS_MT it describes the position of the tree within its layer.
64 *
65 * @return Tree address.
66 **/
67 uint64_t get_tree_addr() const {
68 const uint64_t high = static_cast<uint64_t>(get_lo32(0));
69 const uint64_t low = static_cast<uint64_t>(get_hi32(1));
70 return (high << 32) | low;
71 }
72
73 /**
74 * sets the Tree Address. A call to this method is only required by XMSS_MT.
75 * The Tree Address is constantly zero for XMSS.
76 * For XMSS_MT it describes the position of the tree within its layer.
77 *
78 **/
79 void set_tree_addr(uint64_t value) {
80 set_lo32(0, static_cast<uint32_t>(value >> 32));
81 set_hi32(1, static_cast<uint32_t>(value));
82 }
83
84 /**
85 * retrieves the logical type currently assigned to the XMSS Address
86 * instance.
87 *
88 * @return Type of the address (OTS_Hash_Address, LTree_Address or
89 * Hash_Tree_Address)
90 **/
91 Type get_type() const { return static_cast<Type>(m_data[15]); }
92
93 /**
94 * Changes the logical type currently assigned to the XMSS Address
95 * instance. Please note that changing the type will automatically
96 * reset the 128 LSBs of the Address to zero. This affects the
97 * key_mask_mode property as well as all properties identified by
98 * XMSS_Address::Property.
99 *
100 * @param type Type that shall be assigned to the address
101 * (OTS_Hash_Address, LTree_Address or Hash_Tree_Address)
102 **/
103 void set_type(Type type) {
104 m_data[15] = static_cast<uint8_t>(type);
105 for(size_t i = 16; i != m_data.size(); ++i) {
106 m_data[i] = 0;
107 }
108 }
109
110 /**
111 * Retrieves the mode the address is currently set to. (See
112 * XMSS_Address::Key_Mask for details.)
113 *
114 * @return currently active mode
115 **/
116 Key_Mask get_key_mask_mode() const { return Key_Mask(m_data[31]); }
117
118 /**
119 * Changes the mode the address currently used address mode.
120 * (XMSS_Address::Key_Mask for details.)
121 *
122 * @param value Target mode.
123 **/
126 "Invalid Key_Mask for current XMSS_Address::Type.");
127 m_data[31] = static_cast<uint8_t>(value);
128 }
129
130 /**
131 * Retrieve the index of the OTS key pair within the tree. A call to
132 * this method is only valid, if the address type is set to
133 * Type::OTS_Hash_Address.
134 *
135 * @return index of OTS key pair.
136 **/
137 uint32_t get_ots_address() const {
139 "get_ots_address() requires XMSS_Address::Type::"
140 "OTS_Hash_Address.");
141 return get_hi32(2);
142 }
143
144 /**
145 * Sets the index of the OTS key pair within the tree. A call to this
146 * method is only valid, if the address type is set to
147 * Type::OTS_Hash_Address.
148 *
149 * @param value index of OTS key pair.
150 **/
151 void set_ots_address(uint32_t value) {
153 "set_ots_address() requires XMSS_Address::Type::"
154 "OTS_Hash_Address.");
155 set_hi32(2, value);
156 }
157
158 /**
159 * Retrieves the index of the leaf computed with this LTree. A call to
160 * this method is only valid, if the address type is set to
161 * Type::LTree_Address.
162 *
163 * @return index of the leaf.
164 **/
165 uint32_t get_ltree_address() const {
167 "set_ltree_address() requires XMSS_Address::Type::"
168 "LTree_Address.");
169 return get_hi32(2);
170 }
171
172 /**
173 * Sets the index of the leaf computed with this LTree. A call to this
174 * method is only valid, if the address type is set to
175 * Type::LTree_Address.
176 *
177 * @param value index of the leaf.
178 **/
179 void set_ltree_address(uint32_t value) {
181 "set_ltree_address() requires XMSS_Address::Type::"
182 "LTree_Address.");
183 set_hi32(2, value);
184 }
185
186 /**
187 * Retrieve the chain address. A call to this method is only valid, if
188 * the address type is set to Type::OTS_Hash_Address.
189 *
190 * @return chain address.
191 **/
192 uint32_t get_chain_address() const {
194 "get_chain_address() requires XMSS_Address::Type::"
195 "OTS_Hash_Address.");
196 return get_lo32(2);
197 }
198
199 /**
200 * Set the chain address. A call to this method is only valid, if
201 * the address type is set to Type::OTS_Hash_Address.
202 **/
203 void set_chain_address(uint32_t value) {
205 "set_chain_address() requires XMSS_Address::Type::"
206 "OTS_Hash_Address.");
207 set_lo32(2, value);
208 }
209
210 /**
211 * Retrieves the height of the tree node to be computed within the
212 * tree. A call to this method is only valid, if the address type is
213 * set to Type::LTree_Address or Type::Hash_Tree_Address.
214 *
215 * @return height of the tree node.
216 **/
217 uint32_t get_tree_height() const {
219 "get_tree_height() requires XMSS_Address::Type::"
220 "LTree_Address or XMSS_Address::Type::Hash_Tree_Address.");
221 return get_lo32(2);
222 }
223
224 /**
225 * Sets the height of the tree node to be computed within the
226 * tree. A call to this method is only valid, if the address type is
227 * set to Type::LTree_Address or Type::Hash_Tree_Address.
228 *
229 * @param value height of the tree node.
230 **/
231 void set_tree_height(uint32_t value) {
233 "set_tree_height() requires XMSS_Address::Type::"
234 "LTree_Address or XMSS_Address::Type::Hash_Tree_Address.");
235 set_lo32(2, value);
236 }
237
238 /**
239 * Retrieves the address of the hash function call within the chain.
240 * A call to this method is only valid, if the address type is
241 * set to Type::OTS_Hash_Address.
242 *
243 * @return address of the hash function call within chain.
244 **/
245 uint32_t get_hash_address() const {
247 "get_hash_address() requires XMSS_Address::Type::"
248 "OTS_Hash_Address.");
249 return get_hi32(3);
250 }
251
252 /**
253 * Sets the address of the hash function call within the chain.
254 * A call to this method is only valid, if the address type is
255 * set to Type::OTS_Hash_Address.
256 *
257 * @param value address of the hash function call within chain.
258 **/
259 void set_hash_address(uint32_t value) {
261 "set_hash_address() requires XMSS_Address::Type::"
262 "OTS_Hash_Address.");
263 set_hi32(3, value);
264 }
265
266 /**
267 * Retrieves the index of the tree node at current tree height in the
268 * tree. A call to this method is only valid, if the address type is
269 * set to Type::LTree_Address or Type::Hash_Tree_Address.
270 *
271 * @return index of the tree node at current height.
272 **/
273 uint32_t get_tree_index() const {
275 "get_tree_index() requires XMSS_Address::Type::"
276 "LTree_Address or XMSS_Address::Type::Hash_Tree_Address.");
277 return get_hi32(3);
278 }
279
280 /**
281 * Sets the index of the tree node at current tree height in the
282 * tree. A call to this method is only valid, if the address type is
283 * set to Type::LTree_Address or Type::Hash_Tree_Address.
284 *
285 * @param value index of the tree node at current height.
286 **/
287 void set_tree_index(uint32_t value) {
289 "set_tree_index() requires XMSS_Address::Type::"
290 "LTree_Address or XMSS_Address::Type::Hash_Tree_Address.");
291 set_hi32(3, value);
292 }
293
294 std::span<const uint8_t> bytes() const { return std::span{m_data}; }
295
296 /**
297 * @return the size of an XMSS_Address
298 **/
299 size_t size() const { return m_data.size(); }
300
302
303 ~XMSS_Address() = default;
304 XMSS_Address(const XMSS_Address& other) = default;
305 XMSS_Address(XMSS_Address&& other) = default;
306
307 XMSS_Address& operator=(const XMSS_Address& other) = default;
309
310 explicit XMSS_Address(Type type) : m_data() { set_type(type); }
311
312 private:
313 inline uint32_t get_hi32(size_t offset) const {
314 return ((0x000000FF & m_data[8 * offset + 3]) | (0x000000FF & m_data[8 * offset + 2]) << 8 |
315 (0x000000FF & m_data[8 * offset + 1]) << 16 | (0x000000FF & m_data[8 * offset]) << 24);
316 }
317
318 inline void set_hi32(size_t offset, uint32_t value) {
319 m_data[offset * 8] = ((value >> 24) & 0xFF);
320 m_data[offset * 8 + 1] = ((value >> 16) & 0xFF);
321 m_data[offset * 8 + 2] = ((value >> 8) & 0xFF);
322 m_data[offset * 8 + 3] = ((value) & 0xFF);
323 }
324
325 inline uint32_t get_lo32(size_t offset) const {
326 return ((0x000000FF & m_data[8 * offset + 7]) | (0x000000FF & m_data[8 * offset + 6]) << 8 |
327 (0x000000FF & m_data[8 * offset + 5]) << 16 | (0x000000FF & m_data[8 * offset + 4]) << 24);
328 }
329
330 inline void set_lo32(size_t offset, uint32_t value) {
331 m_data[offset * 8 + 4] = ((value >> 24) & 0xFF);
332 m_data[offset * 8 + 5] = ((value >> 16) & 0xFF);
333 m_data[offset * 8 + 6] = ((value >> 8) & 0xFF);
334 m_data[offset * 8 + 7] = ((value) & 0xFF);
335 }
336
337 std::array<uint8_t, 32> m_data; // NOLINT(*non-private-member-variable*)
338};
339
340} // namespace Botan
341
342#endif
#define BOTAN_ASSERT(expr, assertion_made)
Definition assert.h:69
void set_hash_address(uint32_t value)
void set_key_mask_mode(Key_Mask value)
XMSS_Address(XMSS_Address &&other)=default
void set_ots_address(uint32_t value)
Type get_type() const
size_t size() const
uint32_t get_tree_index() const
XMSS_Address & operator=(XMSS_Address &&other)=default
XMSS_Address & operator=(const XMSS_Address &other)=default
uint32_t get_ots_address() const
void set_type(Type type)
uint32_t get_ltree_address() const
void set_chain_address(uint32_t value)
uint32_t get_tree_height() const
void set_tree_height(uint32_t value)
void set_tree_index(uint32_t value)
void set_layer_addr(uint32_t value)
std::span< const uint8_t > bytes() const
void set_tree_addr(uint64_t value)
uint32_t get_layer_addr() const
uint64_t get_tree_addr() const
XMSS_Address(Type type)
XMSS_Address(const XMSS_Address &other)=default
uint32_t get_chain_address() const
~XMSS_Address()=default
void set_ltree_address(uint32_t value)
uint32_t get_hash_address() const
Key_Mask get_key_mask_mode() const