Botan 3.8.1
Crypto and TLS for C&
kyber.h
Go to the documentation of this file.
1/*
2 * Crystals Kyber key encapsulation mechanism
3 * Based on the public domain reference implementation by the
4 * designers (https://github.com/pq-crystals/kyber)
5 *
6 * Further changes
7 * (C) 2021-2022 Jack Lloyd
8 * (C) 2021-2022 Manuel Glaser and Michael Boric, Rohde & Schwarz Cybersecurity
9 * (C) 2021-2022 René Meusel and Hannes Rantzsch, neXenio GmbH
10 *
11 * Botan is released under the Simplified BSD License (see license.txt)
12 */
13
14#ifndef BOTAN_KYBER_COMMON_H_
15#define BOTAN_KYBER_COMMON_H_
16
17#include <botan/exceptn.h>
18#include <botan/pk_keys.h>
19
20#include <span>
21
22#if !defined(BOTAN_HAS_KYBER_90S) && !defined(BOTAN_HAS_KYBER) && !defined(BOTAN_HAS_ML_KEM)
23static_assert(
24 false,
25 "botan module 'kyber_common' is useful only when enabling at least one of those modules: 'kyber', 'kyber_90s', 'ml_kem'");
26#endif
27
28namespace Botan {
29
31 public:
32 enum Mode {
33 // Kyber512 as proposed in round 3 of the NIST competition
35 // Kyber768 as proposed in round 3 of the NIST competition
37 // Kyber1024 as proposed in round 3 of the NIST competition
39
43
47
48 Kyber512_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated"),
49 Kyber768_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated"),
50 Kyber1024_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated"),
51 };
52
53 KyberMode(Mode mode);
54 explicit KyberMode(const OID& oid);
55 explicit KyberMode(std::string_view str);
56
57 OID object_identifier() const;
58 std::string to_string() const;
59
60 Mode mode() const { return m_mode; }
61
62 BOTAN_DEPRECATED("Kyber 90s mode is deprecated") bool is_90s() const;
63
64 BOTAN_DEPRECATED("Kyber 90s mode is deprecated") bool is_modern() const;
65
66 bool is_ml_kem() const;
67
68 bool is_kyber_round3() const;
69
70 bool is_available() const;
71
72 bool operator==(const KyberMode& other) const { return m_mode == other.m_mode; }
73
74 bool operator!=(const KyberMode& other) const { return !(*this == other); }
75
76 private:
77 Mode m_mode;
78};
79
80/// Byte encoding format of ML-KEM and ML-DSA the private key
82 /// Only supported for ML-KEM/ML-DSA keys:
83 /// - ML-KEM: 64-byte seed: d || z
84 /// - ML-DSA: 32-byte seed: xi (private_key_bits_with_format not yet
85 /// yet supported for ML-DSA)
87 /// The expanded format, i.e., the format specified in FIPS-203/204.
89};
90
91class Kyber_PublicKeyInternal;
92class Kyber_PrivateKeyInternal;
93
94class BOTAN_PUBLIC_API(3, 0) Kyber_PublicKey : public virtual Public_Key {
95 public:
96 Kyber_PublicKey(std::span<const uint8_t> pub_key, KyberMode mode);
97
98 Kyber_PublicKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits);
99
100 Kyber_PublicKey(const Kyber_PublicKey& other);
101
102 Kyber_PublicKey& operator=(const Kyber_PublicKey& other) = default;
103
104 ~Kyber_PublicKey() override = default;
105
106 std::string algo_name() const override;
107
109
110 OID object_identifier() const override;
111
112 size_t key_length() const override;
113
114 size_t estimated_strength() const override;
115
116 std::vector<uint8_t> raw_public_key_bits() const override;
117
118 std::vector<uint8_t> public_key_bits() const override;
119
120 bool check_key(RandomNumberGenerator& rng, bool strong) const override;
121
122 std::unique_ptr<Private_Key> generate_another(RandomNumberGenerator& rng) const final;
123
124 bool supports_operation(PublicKeyOperation op) const override {
126 }
127
128 std::unique_ptr<PK_Ops::KEM_Encryption> create_kem_encryption_op(std::string_view params,
129 std::string_view provider) const override;
130
131 KyberMode mode() const;
132
133 protected:
134 Kyber_PublicKey() = default;
135
136 static std::shared_ptr<Kyber_PublicKeyInternal> initialize_from_encoding(std::span<const uint8_t> pub_key,
137 KyberMode m);
138
139 protected:
142
143 std::shared_ptr<Kyber_PublicKeyInternal> m_public;
144};
145
148
149class BOTAN_PUBLIC_API(3, 0) Kyber_PrivateKey final : public virtual Kyber_PublicKey,
150 public virtual Private_Key {
151 public:
152 /**
153 * Create a new private key. The private key will be encoded as the 64 byte
154 * seed.
155 */
157
158 /**
159 * Import a private key using its key bytes. Supported are key bytes as
160 * 64-byte seeds (not supported for Kyber Round 3 instances),
161 * as well as the expanded encoding specified by FIPS 203. Note that the
162 * encoding used in this constructor is reflected by the calls for
163 * private_key_bits, private_key_info, etc.
164 */
165 Kyber_PrivateKey(std::span<const uint8_t> sk, KyberMode mode);
166
167 /**
168 * Import a private key using its key bytes. Supported are key bytes as
169 * 64-byte seeds (not supported for Kyber Round 3 instances),
170 * as well as the expanded encoding specified by FIPS 203. Note that the
171 * encoding used in this constructor is reflected by the calls for
172 * private_key_bits, private_key_info, etc.
173 */
174 Kyber_PrivateKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits);
175
176 std::unique_ptr<Public_Key> public_key() const override;
177
179
181
182 bool check_key(RandomNumberGenerator& rng, bool strong) const override;
183
184 std::unique_ptr<PK_Ops::KEM_Decryption> create_kem_decryption_op(RandomNumberGenerator& rng,
185 std::string_view params,
186 std::string_view provider) const override;
187
188 /**
189 * The private key format from which the key was loaded. It is the format
190 * used for the private_key_bits(), raw_private_key_bits() andFIPS
191 * private_key_info() methods.
192 *
193 * Note that keys in Seed format can be serialized to Expanded format
194 * using the method private_key_bits_with_format but NOT the other way
195 * around.
196 */
198
199 /**
200 * Encode the private key in the specified format. Note that the seed
201 * format is only available for new ML-KEM keys and those loaded from
202 * seeds.
203 * @throws Encoding_Error if the private key cannot be encoded in the
204 * requested format.
205 */
207
208 private:
210
211 std::shared_ptr<Kyber_PrivateKeyInternal> m_private;
212};
213
215
216} // namespace Botan
217
218#endif
#define BOTAN_DIAGNOSTIC_POP
Definition api.h:108
#define BOTAN_DIAGNOSTIC_PUSH
Definition api.h:105
#define BOTAN_DIAGNOSTIC_IGNORE_INHERITED_VIA_DOMINANCE
Definition api.h:107
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:19
#define BOTAN_DEPRECATED(msg)
Definition api.h:59
bool operator!=(const KyberMode &other) const
Definition kyber.h:74
KyberMode(Mode mode)
Definition kyber.cpp:89
Mode mode() const
Definition kyber.h:60
MlPrivateKeyFormat private_key_format() const
Definition kyber.cpp:331
secure_vector< uint8_t > private_key_bits_with_format(MlPrivateKeyFormat format) const
Definition kyber.cpp:338
std::unique_ptr< PK_Ops::KEM_Decryption > create_kem_decryption_op(RandomNumberGenerator &rng, std::string_view params, std::string_view provider) const override
Definition kyber.cpp:309
std::unique_ptr< Public_Key > public_key() const override
Definition kyber.cpp:256
bool check_key(RandomNumberGenerator &rng, bool strong) const override
Definition kyber.cpp:268
Kyber_PrivateKey(RandomNumberGenerator &rng, KyberMode mode)
Definition kyber.cpp:232
secure_vector< uint8_t > raw_private_key_bits() const override
Definition kyber.cpp:260
friend class Kyber_KEM_Decryptor
Definition kyber.h:209
secure_vector< uint8_t > private_key_bits() const override
Definition kyber.cpp:264
Kyber_PublicKey & operator=(const Kyber_PublicKey &other)=default
std::vector< uint8_t > public_key_bits() const override
Definition kyber.cpp:202
std::vector< uint8_t > raw_public_key_bits() const override
Definition kyber.cpp:198
bool check_key(RandomNumberGenerator &rng, bool strong) const override
Definition kyber.cpp:212
std::string algo_name() const override
Definition kyber.cpp:167
std::shared_ptr< Kyber_PublicKeyInternal > m_public
Definition kyber.h:143
friend class Kyber_KEM_Encryptor
Definition kyber.h:140
size_t key_length() const override
Definition kyber.cpp:208
AlgorithmIdentifier algorithm_identifier() const override
Definition kyber.cpp:171
~Kyber_PublicKey() override=default
static std::shared_ptr< Kyber_PublicKeyInternal > initialize_from_encoding(std::span< const uint8_t > pub_key, KyberMode m)
bool supports_operation(PublicKeyOperation op) const override
Definition kyber.h:124
KyberMode mode() const
Definition kyber.cpp:163
OID object_identifier() const override
Definition kyber.cpp:179
friend class Kyber_KEM_Decryptor
Definition kyber.h:141
std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const final
Definition kyber.cpp:225
Kyber_PublicKey(std::span< const uint8_t > pub_key, KyberMode mode)
Definition kyber.cpp:190
size_t estimated_strength() const override
Definition kyber.cpp:183
PublicKeyOperation
Definition pk_keys.h:46
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:65
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition exceptn.cpp:13
MlPrivateKeyFormat
Byte encoding format of ML-KEM and ML-DSA the private key.
Definition kyber.h:81
@ Expanded
The expanded format, i.e., the format specified in FIPS-203/204.
Definition kyber.h:88