Botan 3.14.1
Crypto and TLS for C&
Botan::Kyber_Modern_Symmetric_Primitives Class Referencefinal

#include <kyber_modern.h>

Inheritance diagram for Botan::Kyber_Modern_Symmetric_Primitives:
Botan::Kyber_Symmetric_Primitives

Public Member Functions

std::pair< KyberSharedSecret, KyberEncryptionRandomness > G (StrongSpan< const KyberMessage > msg, StrongSpan< const KyberHashedPublicKey > pubkey_hash) const
std::pair< KyberSeedRho, KyberSeedSigma > G (StrongSpan< const KyberSeedRandomness > seed, const KyberConstants &mode) const
KyberHashedCiphertext H (StrongSpan< const KyberCompressedCiphertext > r) const
KyberMessage H (StrongSpan< const KyberMessage > m) const
KyberHashedPublicKey H (StrongSpan< const KyberSerializedPublicKey > pk) const
KyberSharedSecret J (StrongSpan< const KyberImplicitRejectionValue > rejection_value, StrongSpan< const KyberCompressedCiphertext > ciphertext) const
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
void PRF_batch (std::span< const StrongSpan< KyberSamplingRandomness > > outputs, std::span< const uint8_t > seed, uint8_t first_nonce) 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.
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.

Protected Member Functions

std::unique_ptr< HashFunction > create_G () const override
std::unique_ptr< HashFunction > create_H () const override
std::unique_ptr< HashFunction > create_J () const override
std::unique_ptr< HashFunction > create_KDF () const override
std::unique_ptr< Botan::XOF > create_PRF (std::span< const uint8_t > seed, const uint8_t nonce) const override
std::unique_ptr< Botan::XOF > create_XOF (std::span< const uint8_t > seed, std::tuple< uint8_t, uint8_t > matrix_position) const override
void init_PRF (Botan::XOF &xof, std::span< const uint8_t > seed, const uint8_t nonce) const override
void init_XOF (Botan::XOF &xof, std::span< const uint8_t > seed, std::tuple< uint8_t, uint8_t > matrix_position) const override
std::optional< std::array< uint8_t, 1 > > seed_expansion_domain_separator (const KyberConstants &) const override
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 override

Static Protected Member Functions

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)

Detailed Description

Definition at line 22 of file kyber_modern.h.

Member Function Documentation

◆ create_G()

std::unique_ptr< HashFunction > Botan::Kyber_Modern_Symmetric_Primitives::create_G ( ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 29 of file kyber_modern.h.

29{ return HashFunction::create_or_throw("SHA-3(512)"); }
static std::unique_ptr< HashFunction > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:311

References Botan::HashFunction::create_or_throw().

◆ create_H()

std::unique_ptr< HashFunction > Botan::Kyber_Modern_Symmetric_Primitives::create_H ( ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 31 of file kyber_modern.h.

31{ return HashFunction::create_or_throw("SHA-3(256)"); }

References Botan::HashFunction::create_or_throw().

◆ create_J()

std::unique_ptr< HashFunction > Botan::Kyber_Modern_Symmetric_Primitives::create_J ( ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 33 of file kyber_modern.h.

33{ throw Invalid_State("Kyber-R3 does not support J()"); }

◆ create_KDF()

std::unique_ptr< HashFunction > Botan::Kyber_Modern_Symmetric_Primitives::create_KDF ( ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 35 of file kyber_modern.h.

35 {
36 return HashFunction::create_or_throw("SHAKE-256(256)");
37 }

References Botan::HashFunction::create_or_throw().

◆ create_PRF()

std::unique_ptr< Botan::XOF > Botan::Kyber_Modern_Symmetric_Primitives::create_PRF ( std::span< const uint8_t > seed,
const uint8_t nonce ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 39 of file kyber_modern.h.

39 {
40 auto xof = Botan::XOF::create_or_throw("SHAKE-256");
41 init_PRF(*xof, seed, nonce);
42 return xof;
43 }
void init_PRF(Botan::XOF &xof, std::span< const uint8_t > seed, const uint8_t nonce) const override
static std::unique_ptr< XOF > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition xof.cpp:52

References Botan::XOF::create_or_throw(), and init_PRF().

◆ create_XOF()

std::unique_ptr< Botan::XOF > Botan::Kyber_Modern_Symmetric_Primitives::create_XOF ( std::span< const uint8_t > seed,
std::tuple< uint8_t, uint8_t > matrix_position ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 51 of file kyber_modern.h.

52 {
53 auto xof = Botan::XOF::create_or_throw("SHAKE-128");
54 init_XOF(*xof, seed, matrix_position);
55 return xof;
56 }
void init_XOF(Botan::XOF &xof, std::span< const uint8_t > seed, std::tuple< uint8_t, uint8_t > matrix_position) const override

References Botan::XOF::create_or_throw(), and init_XOF().

◆ G() [1/2]

std::pair< KyberSharedSecret, KyberEncryptionRandomness > Botan::Kyber_Symmetric_Primitives::G ( StrongSpan< const KyberMessage > msg,
StrongSpan< const KyberHashedPublicKey > pubkey_hash ) const
inlineinherited

Definition at line 55 of file kyber_symmetric_primitives.h.

56 {
57 return G_split<KyberSharedSecret, KyberEncryptionRandomness>(msg, pubkey_hash);
58 }

◆ G() [2/2]

std::pair< KyberSeedRho, KyberSeedSigma > Botan::Kyber_Symmetric_Primitives::G ( StrongSpan< const KyberSeedRandomness > seed,
const KyberConstants & mode ) const
inlineinherited

Definition at line 46 of file kyber_symmetric_primitives.h.

47 {
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 }
virtual std::optional< std::array< uint8_t, 1 > > seed_expansion_domain_separator(const KyberConstants &mode) const =0

References seed_expansion_domain_separator().

Referenced by Botan::Kyber_KEM_Decryptor::decapsulate(), Botan::ML_KEM_Decryptor::decapsulate(), and Botan::Kyber_Algos::expand_keypair().

◆ H() [1/3]

KyberHashedCiphertext Botan::Kyber_Symmetric_Primitives::H ( StrongSpan< const KyberCompressedCiphertext > r) const
inlineinherited

Definition at line 38 of file kyber_symmetric_primitives.h.

38 {
39 return create_H()->process<KyberHashedCiphertext>(r);
40 }
virtual std::unique_ptr< HashFunction > create_H() const =0
Strong< std::vector< uint8_t >, struct KyberHashedCiphertext_ > KyberHashedCiphertext
Definition kyber_types.h:67

References create_H().

◆ H() [2/3]

KyberMessage Botan::Kyber_Symmetric_Primitives::H ( StrongSpan< const KyberMessage > m) const
inlineinherited

Definition at line 35 of file kyber_symmetric_primitives.h.

35{ return create_H()->process<KyberMessage>(m); }
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

References create_H().

◆ H() [3/3]

KyberHashedPublicKey Botan::Kyber_Symmetric_Primitives::H ( StrongSpan< const KyberSerializedPublicKey > pk) const
inlineinherited

Definition at line 42 of file kyber_symmetric_primitives.h.

42 {
43 return create_H()->process<KyberHashedPublicKey>(pk);
44 }
Strong< std::vector< uint8_t >, struct KyberHashedPublicKey_ > KyberHashedPublicKey
Hash value of the serialized public key.
Definition kyber_types.h:60

References create_H().

◆ init_PRF()

void Botan::Kyber_Modern_Symmetric_Primitives::init_PRF ( Botan::XOF & xof,
std::span< const uint8_t > seed,
const uint8_t nonce ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 45 of file kyber_modern.h.

45 {
46 xof.clear();
47 xof.update(seed);
48 xof.update({&nonce, 1});
49 }
void clear()
Definition xof.h:66
void update(std::span< const uint8_t > input)
Definition xof.h:147

References Botan::XOF::clear(), and Botan::XOF::update().

Referenced by create_PRF().

◆ init_XOF()

void Botan::Kyber_Modern_Symmetric_Primitives::init_XOF ( Botan::XOF & xof,
std::span< const uint8_t > seed,
std::tuple< uint8_t, uint8_t > matrix_position ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 58 of file kyber_modern.h.

60 {
61 xof.clear();
62 xof.update(seed);
63
64 const std::array<uint8_t, 2> pos = {std::get<0>(matrix_position), std::get<1>(matrix_position)};
65 xof.update(pos);
66 }

References Botan::XOF::clear(), and Botan::XOF::update().

Referenced by create_XOF().

◆ J()

KyberSharedSecret Botan::Kyber_Symmetric_Primitives::J ( StrongSpan< const KyberImplicitRejectionValue > rejection_value,
StrongSpan< const KyberCompressedCiphertext > ciphertext ) const
inlineinherited

Definition at line 60 of file kyber_symmetric_primitives.h.

61 {
62 auto j = create_J();
63 j->update(rejection_value);
64 j->update(ciphertext);
65 return j->final<KyberSharedSecret>();
66 }
virtual std::unique_ptr< HashFunction > create_J() const =0
Strong< secure_vector< uint8_t >, struct KyberSharedSecret_ > KyberSharedSecret
Shared secret value generated during encapsulation and recovered during decapsulation.
Definition kyber_types.h:54

References create_J().

◆ KDF()

void Botan::Kyber_Symmetric_Primitives::KDF ( StrongSpan< KyberSharedSecret > out,
StrongSpan< const KyberSharedSecret > shared_secret,
StrongSpan< const KyberHashedCiphertext > hashed_ciphertext ) const
inlineinherited

Definition at line 69 of file kyber_symmetric_primitives.h.

71 {
72 auto kdf = create_KDF();
73 kdf->update(shared_secret);
74 kdf->update(hashed_ciphertext);
75 kdf->final(out);
76 }
virtual std::unique_ptr< HashFunction > create_KDF() const =0

References create_KDF().

◆ PRF()

KyberSamplingRandomness Botan::Kyber_Symmetric_Primitives::PRF ( KyberSigmaOrEncryptionRandomness seed,
const uint8_t nonce,
const size_t outlen ) const
inlineinherited

Definition at line 78 of file kyber_symmetric_primitives.h.

80 {
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 }
virtual std::unique_ptr< Botan::XOF > create_PRF(std::span< const uint8_t > seed, uint8_t nonce) const =0
Strong< secure_vector< uint8_t >, struct KyberSamplingRandomness_ > KyberSamplingRandomness
PRF value used for sampling of error polynomials.
Definition kyber_types.h:51

References create_PRF().

◆ PRF_batch()

void Botan::Kyber_Symmetric_Primitives::PRF_batch ( std::span< const StrongSpan< KyberSamplingRandomness > > outputs,
std::span< const uint8_t > seed,
uint8_t first_nonce ) const
inlineinherited

Batched variant of setup_PRF + output using consecutive nonces. All outputs are equally sized.

Each PRF output fits in a single Keccak block, so a multi-buffer hash engine (whose setup is bound to the per-operation seed) cannot amortize its creation cost here and scalar XOFs are used.

Definition at line 125 of file kyber_symmetric_primitives.h.

127 {
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 }
#define BOTAN_DEBUG_ASSERT(expr)
Definition assert.h:136
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.

References BOTAN_DEBUG_ASSERT, and setup_PRF().

◆ seed_expansion_domain_separator()

std::optional< std::array< uint8_t, 1 > > Botan::Kyber_Modern_Symmetric_Primitives::seed_expansion_domain_separator ( const KyberConstants & ) const
inlineoverrideprotectedvirtual

Implements Botan::Kyber_Symmetric_Primitives.

Definition at line 24 of file kyber_modern.h.

25 {
26 return {};
27 }

◆ setup_PRF()

void Botan::Kyber_Symmetric_Primitives::setup_PRF ( std::unique_ptr< Botan::XOF > & xof,
std::span< const uint8_t > seed,
uint8_t nonce ) const
inlineinherited

Setup a seeded PRF XOF for polynomial sampling.

Definition at line 97 of file kyber_symmetric_primitives.h.

97 {
98 if(!xof) {
99 xof = create_PRF(seed, nonce);
100 } else {
101 init_PRF(*xof, seed, nonce);
102 }
103 }
virtual void init_PRF(Botan::XOF &xof, std::span< const uint8_t > seed, uint8_t nonce) const =0

References create_PRF(), and init_PRF().

Referenced by PRF_batch().

◆ setup_XOF()

void Botan::Kyber_Symmetric_Primitives::setup_XOF ( std::unique_ptr< Botan::XOF > & xof,
StrongSpan< const KyberSeedRho > seed,
std::tuple< uint8_t, uint8_t > matrix_position ) const
inlineinherited

Setup an XOF object for matrix sampling.

Definition at line 86 of file kyber_symmetric_primitives.h.

88 {
89 if(!xof) {
90 xof = create_XOF(seed, matrix_position);
91 } else {
92 init_XOF(*xof, seed, matrix_position);
93 }
94 }
virtual void init_XOF(Botan::XOF &xof, std::span< const uint8_t > seed, std::tuple< uint8_t, uint8_t > matrix_position) const =0
virtual std::unique_ptr< Botan::XOF > create_XOF(std::span< const uint8_t > seed, std::tuple< uint8_t, uint8_t > matrix_position) const =0

References create_XOF(), and init_XOF().

Referenced by XOF_batch().

◆ shake_XOF_batch()

void Botan::Kyber_Symmetric_Primitives::shake_XOF_batch ( std::span< std::span< uint8_t > > outputs,
StrongSpan< const KyberSeedRho > seed,
std::span< const std::tuple< uint8_t, uint8_t > > positions )
inlinestaticprotectedinherited

Batch implementations for the SHAKE-based instantiations (used by the ML-KEM and Kyber round 3 specializations)

Definition at line 156 of file kyber_symmetric_primitives.h.

158 {
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 }
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
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="")
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References BOTAN_ASSERT_NOMSG, BOTAN_DEBUG_ASSERT, Botan::Hash_Engine::create_or_throw(), and Botan::fmt().

Referenced by Botan::Kyber_Modern_Symmetric_Primitives::XOF_batch(), and Botan::ML_KEM_Symmetric_Primitives::XOF_batch().

◆ XOF_batch()

void Botan::Kyber_Modern_Symmetric_Primitives::XOF_batch ( std::span< std::span< uint8_t > > outputs,
StrongSpan< const KyberSeedRho > seed,
std::span< const std::tuple< uint8_t, uint8_t > > positions ) const
inlineoverrideprotectedvirtual

Batched variant of setup_XOF + output: outputs[i] receives the leading XOF output for positions[i]. All outputs are equally sized.

Reimplemented from Botan::Kyber_Symmetric_Primitives.

Definition at line 68 of file kyber_modern.h.

70 {
71 shake_XOF_batch(outputs, seed, positions);
72 }
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)

References Botan::Kyber_Symmetric_Primitives::shake_XOF_batch().


The documentation for this class was generated from the following file: