Botan 3.14.1
Crypto and TLS for C&
kyber_symmetric_primitives.h
Go to the documentation of this file.
1/*
2 * Symmetric primitives for Kyber (modern)
3 * (C) 2022 Jack Lloyd
4 * (C) 2022 Hannes Rantzsch, René Meusel, neXenio GmbH
5 * (C) 2024 René Meusel, Rohde & Schwarz Cybersecurity
6 *
7 * Botan is released under the Simplified BSD License (see license.txt)
8 */
9
10#ifndef BOTAN_KYBER_SYMMETRIC_PRIMITIVES_H_
11#define BOTAN_KYBER_SYMMETRIC_PRIMITIVES_H_
12
13#include <botan/hash.h>
14#include <botan/xof.h>
15#include <botan/internal/buffer_slicer.h>
16#include <botan/internal/fmt.h>
17#include <botan/internal/hash_engine.h>
18#include <botan/internal/kyber_constants.h>
19#include <botan/internal/kyber_types.h>
20
21#include <span>
22#include <tuple>
23
24namespace Botan {
25
26/**
27 * Adapter class that uses polymorphy to distinguish
28 * Kyber "modern" from Kyber "90s" modes.
29 */
30class Kyber_Symmetric_Primitives /* NOLINT(*-special-member-functions) */ {
31 public:
32 virtual ~Kyber_Symmetric_Primitives() = default;
33
34 // TODO: remove this once Kyber-R3 is removed
36
37 // TODO: remove this once Kyber-R3 is removed
41
45
46 std::pair<KyberSeedRho, KyberSeedSigma> G(StrongSpan<const KyberSeedRandomness> seed,
47 const KyberConstants& mode) const {
48 if(auto domsep = seed_expansion_domain_separator(mode)) {
49 return G_split<KyberSeedRho, KyberSeedSigma>(seed, *domsep);
50 } else {
51 return G_split<KyberSeedRho, KyberSeedSigma>(seed);
52 }
53 }
54
55 std::pair<KyberSharedSecret, KyberEncryptionRandomness> G(
57 return G_split<KyberSharedSecret, KyberEncryptionRandomness>(msg, pubkey_hash);
58 }
59
62 auto j = create_J();
63 j->update(rejection_value);
64 j->update(ciphertext);
65 return j->final<KyberSharedSecret>();
66 }
67
68 // TODO: remove this once Kyber-R3 is removed
71 StrongSpan<const KyberHashedCiphertext> hashed_ciphertext) const {
72 auto kdf = create_KDF();
73 kdf->update(shared_secret);
74 kdf->update(hashed_ciphertext);
75 kdf->final(out);
76 }
77
79 const uint8_t nonce,
80 const size_t outlen) const {
81 const auto bare_seed_span = std::visit([&](const auto s) { return s.get(); }, seed);
82 return create_PRF(bare_seed_span, nonce)->output<KyberSamplingRandomness>(outlen);
83 }
84
85 /// Setup an XOF object for matrix sampling
86 void setup_XOF(std::unique_ptr<Botan::XOF>& xof,
88 std::tuple<uint8_t, uint8_t> matrix_position) const {
89 if(!xof) {
90 xof = create_XOF(seed, matrix_position);
91 } else {
92 init_XOF(*xof, seed, matrix_position);
93 }
94 }
95
96 /// Setup a seeded PRF XOF for polynomial sampling
97 void setup_PRF(std::unique_ptr<Botan::XOF>& xof, std::span<const uint8_t> seed, uint8_t nonce) const {
98 if(!xof) {
99 xof = create_PRF(seed, nonce);
100 } else {
101 init_PRF(*xof, seed, nonce);
102 }
103 }
104
105 /// Batched variant of setup_XOF + output: outputs[i] receives the
106 /// leading XOF output for positions[i]. All outputs are equally sized.
107 virtual void XOF_batch(std::span<std::span<uint8_t>> outputs,
109 std::span<const std::tuple<uint8_t, uint8_t>> positions) const {
110 BOTAN_ASSERT_NOMSG(outputs.size() == positions.size());
111 std::unique_ptr<Botan::XOF> xof;
112 for(size_t i = 0; i < outputs.size(); ++i) {
113 BOTAN_DEBUG_ASSERT(outputs[i].size() == outputs[0].size());
114 setup_XOF(xof, seed, positions[i]);
115 xof->output(outputs[i]);
116 }
117 }
118
119 /// Batched variant of setup_PRF + output using consecutive nonces.
120 /// All outputs are equally sized.
121 ///
122 /// Each PRF output fits in a single Keccak block, so a multi-buffer
123 /// hash engine (whose setup is bound to the per-operation seed)
124 /// cannot amortize its creation cost here and scalar XOFs are used.
125 void PRF_batch(std::span<const StrongSpan<KyberSamplingRandomness>> outputs,
126 std::span<const uint8_t> seed,
127 uint8_t first_nonce) const {
128 std::unique_ptr<Botan::XOF> xof;
129 for(size_t i = 0; i < outputs.size(); ++i) {
130 BOTAN_DEBUG_ASSERT(outputs[i].size() == outputs[0].size());
131 setup_PRF(xof, seed, static_cast<uint8_t>(first_nonce + i));
132 xof->output(outputs[i]);
133 }
134 }
135
136 private:
139 ranges::contiguous_range... InputTs>
140 std::pair<T1, T2> G_split(const InputTs&... inputs) const {
141 auto g = create_G();
142 (g->update(inputs), ...);
143 const auto s = g->final();
144
145 BufferSlicer bs(s);
146 std::pair<T1, T2> result;
147 result.first = bs.copy<T1>(KyberConstants::SEED_BYTES);
148 result.second = bs.copy<T2>(KyberConstants::SEED_BYTES);
149 BOTAN_ASSERT_NOMSG(bs.empty());
150 return result;
151 }
152
153 protected:
154 /// Batch implementations for the SHAKE-based instantiations (used by
155 /// the ML-KEM and Kyber round 3 specializations)
156 static void shake_XOF_batch(std::span<std::span<uint8_t>> outputs,
158 std::span<const std::tuple<uint8_t, uint8_t>> positions) {
159 BOTAN_ASSERT_NOMSG(outputs.size() == positions.size());
160 if(outputs.empty()) {
161 return;
162 }
163
164 auto engine = Hash_Engine::create_or_throw(fmt("SHAKE-128({})", 8 * outputs[0].size()), seed);
165
166 std::vector<uint8_t> pos_bytes(2 * positions.size());
167 std::vector<std::span<const uint8_t>> inputs(positions.size());
168 for(size_t i = 0; i < positions.size(); ++i) {
169 BOTAN_DEBUG_ASSERT(outputs[i].size() == outputs[0].size());
170 pos_bytes[2 * i] = std::get<0>(positions[i]);
171 pos_bytes[2 * i + 1] = std::get<1>(positions[i]);
172 inputs[i] = std::span(pos_bytes).subspan(2 * i, 2);
173 }
174
175 engine->batch_hash(outputs, inputs);
176 }
177
178 virtual std::optional<std::array<uint8_t, 1>> seed_expansion_domain_separator(
179 const KyberConstants& mode) const = 0;
180
181 virtual std::unique_ptr<HashFunction> create_G() const = 0;
182 virtual std::unique_ptr<HashFunction> create_H() const = 0;
183 virtual std::unique_ptr<HashFunction> create_J() const = 0;
184 virtual std::unique_ptr<HashFunction> create_KDF() const = 0;
185
186 virtual std::unique_ptr<Botan::XOF> create_PRF(std::span<const uint8_t> seed, uint8_t nonce) const = 0;
187 virtual void init_PRF(Botan::XOF& xof, std::span<const uint8_t> seed, uint8_t nonce) const = 0;
188
189 virtual std::unique_ptr<Botan::XOF> create_XOF(std::span<const uint8_t> seed,
190 std::tuple<uint8_t, uint8_t> matrix_position) const = 0;
191 virtual void init_XOF(Botan::XOF& xof,
192 std::span<const uint8_t> seed,
193 std::tuple<uint8_t, uint8_t> matrix_position) const = 0;
194};
195
196} // namespace Botan
197
198#endif
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
#define BOTAN_DEBUG_ASSERT(expr)
Definition assert.h:136
static std::unique_ptr< Hash_Engine > create_or_throw(std::string_view hash_fn, std::span< const uint8_t > common_prefix={}, std::string_view provider="")
static constexpr size_t SEED_BYTES
static void shake_XOF_batch(std::span< std::span< uint8_t > > outputs, StrongSpan< const KyberSeedRho > seed, std::span< const std::tuple< uint8_t, uint8_t > > positions)
virtual ~Kyber_Symmetric_Primitives()=default
KyberMessage H(StrongSpan< const KyberMessage > m) const
void setup_XOF(std::unique_ptr< Botan::XOF > &xof, StrongSpan< const KyberSeedRho > seed, std::tuple< uint8_t, uint8_t > matrix_position) const
Setup an XOF object for matrix sampling.
virtual void init_XOF(Botan::XOF &xof, std::span< const uint8_t > seed, std::tuple< uint8_t, uint8_t > matrix_position) const =0
KyberHashedCiphertext H(StrongSpan< const KyberCompressedCiphertext > r) const
void setup_PRF(std::unique_ptr< Botan::XOF > &xof, std::span< const uint8_t > seed, uint8_t nonce) const
Setup a seeded PRF XOF for polynomial sampling.
virtual std::unique_ptr< Botan::XOF > create_XOF(std::span< const uint8_t > seed, std::tuple< uint8_t, uint8_t > matrix_position) const =0
void KDF(StrongSpan< KyberSharedSecret > out, StrongSpan< const KyberSharedSecret > shared_secret, StrongSpan< const KyberHashedCiphertext > hashed_ciphertext) const
KyberSamplingRandomness PRF(KyberSigmaOrEncryptionRandomness seed, const uint8_t nonce, const size_t outlen) const
virtual std::unique_ptr< Botan::XOF > create_PRF(std::span< const uint8_t > seed, uint8_t nonce) const =0
virtual std::unique_ptr< HashFunction > create_G() const =0
virtual std::unique_ptr< HashFunction > create_H() const =0
std::pair< KyberSharedSecret, KyberEncryptionRandomness > G(StrongSpan< const KyberMessage > msg, StrongSpan< const KyberHashedPublicKey > pubkey_hash) const
void PRF_batch(std::span< const StrongSpan< KyberSamplingRandomness > > outputs, std::span< const uint8_t > seed, uint8_t first_nonce) const
KyberSharedSecret J(StrongSpan< const KyberImplicitRejectionValue > rejection_value, StrongSpan< const KyberCompressedCiphertext > ciphertext) const
virtual std::unique_ptr< HashFunction > create_J() const =0
virtual void XOF_batch(std::span< std::span< uint8_t > > outputs, StrongSpan< const KyberSeedRho > seed, std::span< const std::tuple< uint8_t, uint8_t > > positions) const
std::pair< KyberSeedRho, KyberSeedSigma > G(StrongSpan< const KyberSeedRandomness > seed, const KyberConstants &mode) const
virtual void init_PRF(Botan::XOF &xof, std::span< const uint8_t > seed, uint8_t nonce) const =0
KyberHashedPublicKey H(StrongSpan< const KyberSerializedPublicKey > pk) const
virtual std::unique_ptr< HashFunction > create_KDF() const =0
virtual std::optional< std::array< uint8_t, 1 > > seed_expansion_domain_separator(const KyberConstants &mode) const =0
Strong< secure_vector< uint8_t >, struct KyberMessage_ > KyberMessage
Random message value to be encrypted by the CPA-secure Kyber encryption scheme.
Definition kyber_types.h:45
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
Strong< secure_vector< uint8_t >, struct KyberSamplingRandomness_ > KyberSamplingRandomness
PRF value used for sampling of error polynomials.
Definition kyber_types.h:51
Strong< std::vector< uint8_t >, struct KyberHashedCiphertext_ > KyberHashedCiphertext
Definition kyber_types.h:67
std::variant< StrongSpan< const KyberSeedSigma >, StrongSpan< const KyberEncryptionRandomness > > KyberSigmaOrEncryptionRandomness
Variant value of either a KyberSeedSigma or a KyberEncryptionRandomness.
Definition kyber_types.h:70
Strong< secure_vector< uint8_t >, struct KyberSharedSecret_ > KyberSharedSecret
Shared secret value generated during encapsulation and recovered during decapsulation.
Definition kyber_types.h:54
Strong< std::vector< uint8_t >, struct KyberHashedPublicKey_ > KyberHashedPublicKey
Hash value of the serialized public key.
Definition kyber_types.h:60