Botan 3.14.1
Crypto and TLS for C&
sp_hash.h
Go to the documentation of this file.
1/*
2 * SLH-DSA Hash Function Interface
3 * (C) 2023 Jack Lloyd
4 * 2023 Fabian Albert, René Meusel, Amos Treiber - Rohde & Schwarz Cybersecurity
5 *
6 * Botan is released under the Simplified BSD License (see license.txt)
7 **/
8
9#ifndef BOTAN_SP_HASH_H_
10#define BOTAN_SP_HASH_H_
11
12#include <botan/hash.h>
13#include <botan/sp_parameters.h>
14#include <botan/internal/sp_address.h>
15#include <botan/internal/sp_types.h>
16
17namespace Botan {
18
19class Hash_Engine;
20
21/**
22 * A collection of pseudorandom hash functions required for SLH-DSA
23 * computations. See FIPS 205, Section 11.2.1 and 11.2.2.
24 **/
25class BOTAN_TEST_API Sphincs_Hash_Functions /* NOLINT(*-special-member-functions) */ {
26 public:
27 virtual ~Sphincs_Hash_Functions() = default;
28
29 /**
30 * Creates a Sphincs_Hash_Functions object instantiating the hash
31 * functions used for the specified @p sphincs_params. The @p pub_seed is
32 * used to seed the hash functions (possibly padded). This is pre-computed
33 * and the respective state is copied on the further calls on H(seed) with
34 * tweak_hash, i.e., T and PRF.
35 */
36 static std::unique_ptr<Sphincs_Hash_Functions> create(const Sphincs_Parameters& sphincs_params,
37 const SphincsPublicSeed& pub_seed);
38
39 std::tuple<SphincsHashedMessage, XmssTreeIndexInLayer, TreeNodeIndex> H_msg(
41 const SphincsTreeNode& root,
42 const SphincsMessageInternal& message);
43
44 /**
45 * Using SK.PRF, the optional randomness, and a message, computes the message random R,
46 * and the tree and leaf indices.
47 *
48 * @param out output location for the message hash
49 * @param sk_prf SK.PRF
50 * @param opt_rand optional randomness
51 * @param msg message
52 */
56 const SphincsMessageInternal& msg) = 0;
57
58 template <typename... BufferTs>
59 void T(std::span<uint8_t> out, const Sphincs_Address& address, const BufferTs&... in) {
60 auto& hash = tweak_hash(address, (in.size() + ...));
61 (hash.update(in), ...);
62 hash.final(out);
63 }
64
65 template <typename OutT = std::vector<uint8_t>, typename... BufferTs>
66 OutT T(const Sphincs_Address& address, const BufferTs&... in) {
67 OutT t(m_sphincs_params.n());
68 T(t, address, in...);
69 return t;
70 }
71
72 void PRF(StrongSpan<ForsLeafSecret> out, const SphincsSecretSeed& sk_seed, const Sphincs_Address& address) {
73 T(out, address, sk_seed);
74 }
75
76 void PRF(StrongSpan<WotsNode> out, const SphincsSecretSeed& sk_seed, const Sphincs_Address& address) {
77 T(out, address, sk_seed);
78 }
79
80 /**
81 * Batched variant of T with a single input buffer per lane
82 *
83 * Computes outputs[i] = T(addresses[i], inputs[i]). All inputs must
84 * have identical length. outputs[i] may alias inputs[i], as used for
85 * stepping WOTS+ chains in place.
86 */
87 void T_batch(std::span<std::span<uint8_t>> outputs,
88 std::span<const Sphincs_Address> addresses,
89 std::span<std::span<const uint8_t>> inputs);
90
91 /**
92 * Batched variant of PRF: outputs[i] = PRF(sk_seed, addresses[i])
93 */
94 void PRF_batch(std::span<std::span<uint8_t>> outputs,
95 const SphincsSecretSeed& sk_seed,
96 std::span<const Sphincs_Address> addresses);
97
98 virtual std::string msg_hash_function_name() const = 0;
99
100 protected:
101 Sphincs_Hash_Functions(const Sphincs_Parameters& sphincs_params, const SphincsPublicSeed& pub_seed);
102
103 /**
104 * Prepare the underlying hash function for hashing any given input
105 * depending on the expected input length.
106 *
107 * @param address the SLH-DSA address of the hash to be tweaked
108 * @param input_length the input buffer length that will be processed
109 * with the tweaked hash (typically N or 2*N)
110 * @returns a reference to a Botan::HashFunction that is preconditioned
111 * with the given tweaking parameters.
112 *
113 * @note Callers are expected to finalize (i.e. reset) the returned
114 * HashFunction after use.
115 */
116 virtual HashFunction& tweak_hash(const Sphincs_Address& address, size_t input_length) = 0;
117
118 /**
119 * @return engine for batched tweaked hashing of inputs of the given length
120 */
121 virtual Hash_Engine& tweak_hash_engine(size_t input_length) = 0;
122
123 /**
124 * @return byte length of the address encoding used for tweaked hashing
125 */
126 virtual size_t address_encoding_len() const = 0;
127
128 /**
129 * Write the encoding of @p address used for tweaked hashing to @p out
130 */
131 virtual void encode_address(std::span<uint8_t> out, const Sphincs_Address& address) const = 0;
132
134 const SphincsTreeNode& root,
135 const SphincsMessageInternal& message) = 0;
136
137 const Sphincs_Parameters& m_sphincs_params; // NOLINT(*non-private-member-variable*)
138 const SphincsPublicSeed& m_pub_seed; // NOLINT(*non-private-member-variable*)
139
140 private:
141 // Scratch space for batched hashing
142 std::vector<uint8_t> m_adrs_buf;
143 std::vector<std::span<const uint8_t>> m_adrs_spans;
144 std::vector<std::span<const uint8_t>> m_prf_inputs;
145};
146
147} // namespace Botan
148
149#endif
#define BOTAN_TEST_API
Definition api.h:41
const SphincsPublicSeed & m_pub_seed
Definition sp_hash.h:138
virtual HashFunction & tweak_hash(const Sphincs_Address &address, size_t input_length)=0
const Sphincs_Parameters & m_sphincs_params
Definition sp_hash.h:137
Sphincs_Hash_Functions(const Sphincs_Parameters &sphincs_params, const SphincsPublicSeed &pub_seed)
Definition sp_hash.cpp:28
OutT T(const Sphincs_Address &address, const BufferTs &... in)
Definition sp_hash.h:66
virtual size_t address_encoding_len() const =0
virtual void encode_address(std::span< uint8_t > out, const Sphincs_Address &address) const =0
virtual Hash_Engine & tweak_hash_engine(size_t input_length)=0
void T(std::span< uint8_t > out, const Sphincs_Address &address, const BufferTs &... in)
Definition sp_hash.h:59
virtual void PRF_msg(StrongSpan< SphincsMessageRandomness > out, StrongSpan< const SphincsSecretPRF > sk_prf, StrongSpan< const SphincsOptionalRandomness > opt_rand, const SphincsMessageInternal &msg)=0
std::tuple< SphincsHashedMessage, XmssTreeIndexInLayer, TreeNodeIndex > H_msg(StrongSpan< const SphincsMessageRandomness > r, const SphincsTreeNode &root, const SphincsMessageInternal &message)
Definition sp_hash.cpp:107
virtual ~Sphincs_Hash_Functions()=default
static std::unique_ptr< Sphincs_Hash_Functions > create(const Sphincs_Parameters &sphincs_params, const SphincsPublicSeed &pub_seed)
Definition sp_hash.cpp:63
virtual std::vector< uint8_t > H_msg_digest(StrongSpan< const SphincsMessageRandomness > r, const SphincsTreeNode &root, const SphincsMessageInternal &message)=0
void PRF(StrongSpan< WotsNode > out, const SphincsSecretSeed &sk_seed, const Sphincs_Address &address)
Definition sp_hash.h:76
void PRF(StrongSpan< ForsLeafSecret > out, const SphincsSecretSeed &sk_seed, const Sphincs_Address &address)
Definition sp_hash.h:72
virtual std::string msg_hash_function_name() const =0
Gf448Elem root(const Gf448Elem &elem)
Compute the root of elem in the field.
Strong< std::vector< uint8_t >, struct SphincsTreeNode_ > SphincsTreeNode
Either an XMSS or FORS tree node or leaf.
Definition sp_types.h:70
Strong< std::vector< uint8_t >, struct SphincsPublicSeed_ > SphincsPublicSeed
Definition sp_types.h:60
Strong< secure_vector< uint8_t >, struct SphincsSecretSeed_ > SphincsSecretSeed
Definition sp_types.h:61
M' representation of FIPS 205 (the input to slh_sign_internal and slh_verify_internal).
Definition sp_types.h:52