Botan 3.14.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/module_lattice_keys.h>
18#include <botan/pk_keys.h>
19#include <span>
20
21#if !defined(BOTAN_HAS_KYBER_90S) && !defined(BOTAN_HAS_KYBER) && !defined(BOTAN_HAS_ML_KEM)
22static_assert(
23 false,
24 "botan module 'kyber_common' is useful only when enabling at least one of those modules: 'kyber', 'kyber_90s', 'ml_kem'");
25#endif
26
27namespace Botan {
28
29class BOTAN_PUBLIC_API(3, 0) KyberMode final {
30 public:
31 enum Mode : uint8_t /* NOLINT(*-use-enum-class) */ {
32 // Kyber512 as proposed in round 3 of the NIST competition
33 Kyber512_R3 BOTAN_DEPRECATED("Kyber R3 is deprecated - use ML-KEM") = 0,
34 // Kyber768 as proposed in round 3 of the NIST competition
35 Kyber768_R3 BOTAN_DEPRECATED("Kyber R3 is deprecated - use ML-KEM") = 1,
36 // Kyber1024 as proposed in round 3 of the NIST competition
37 Kyber1024_R3 BOTAN_DEPRECATED("Kyber R3 is deprecated - use ML-KEM") = 2,
38
39 Kyber512 BOTAN_DEPRECATED("Kyber R3 is deprecated - use ML-KEM") = 0,
40 Kyber768 BOTAN_DEPRECATED("Kyber R3 is deprecated - use ML-KEM") = 1,
41 Kyber1024 BOTAN_DEPRECATED("Kyber R3 is deprecated - use ML-KEM") = 2,
42
46
47 Kyber512_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated") = 6,
48 Kyber768_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated") = 7,
49 Kyber1024_90s BOTAN_DEPRECATED("Kyber 90s mode is deprecated") = 8,
50 };
51
52 // NOLINTNEXTLINE(*-explicit-conversions,*-explicit-constructor)
53 KyberMode(Mode mode);
54
55 explicit KyberMode(const OID& oid);
56 explicit KyberMode(std::string_view str);
57
58 OID object_identifier() const;
59 std::string to_string() const;
60
61 Mode mode() const { return m_mode; }
62
63 BOTAN_DEPRECATED("Kyber 90s mode is deprecated") bool is_90s() const;
64
65 BOTAN_DEPRECATED("Kyber 90s mode is deprecated") bool is_modern() const;
66
67 bool is_ml_kem() const;
68
69 bool is_kyber_round3() const;
70
71 bool is_available() const;
72
73 bool operator==(const KyberMode& other) const { return m_mode == other.m_mode; }
74
75 bool operator!=(const KyberMode& other) const { return !(*this == other); }
76
77 private:
78 Mode m_mode;
79};
80
81class Kyber_PublicKeyInternal;
82class Kyber_PrivateKeyInternal;
83
84class BOTAN_PUBLIC_API(3, 0) Kyber_PublicKey : public virtual Public_Key {
85 public:
86 Kyber_PublicKey(std::span<const uint8_t> pub_key, KyberMode mode);
87
88 Kyber_PublicKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits);
89
90 Kyber_PublicKey(const Kyber_PublicKey& other);
91 Kyber_PublicKey& operator=(const Kyber_PublicKey& other) = default;
92 Kyber_PublicKey(Kyber_PublicKey&& other) = default;
94
95 ~Kyber_PublicKey() override = default;
96
97 std::string algo_name() const override;
98
100
101 OID object_identifier() const override;
102
103 size_t key_length() const override;
104
105 size_t estimated_strength() const override;
106
107 std::vector<uint8_t> raw_public_key_bits() const override;
108
109 std::vector<uint8_t> public_key_bits() const override;
110
111 bool check_key(RandomNumberGenerator& rng, bool strong) const override;
112
113 std::unique_ptr<Private_Key> generate_another(RandomNumberGenerator& rng) const final;
114
115 bool supports_operation(PublicKeyOperation op) const override {
117 }
118
119 std::unique_ptr<PK_Ops::KEM_Encryption> _create_kem_encryption_op(
120 const PK_KEM_Options_Reader& options) const override;
121
122 KyberMode mode() const;
123
124 protected:
125 Kyber_PublicKey() = default;
126
127 static std::shared_ptr<Kyber_PublicKeyInternal> initialize_from_encoding(std::span<const uint8_t> pub_key,
128 KyberMode m);
129
130 protected:
133
134 std::shared_ptr<const Kyber_PublicKeyInternal> m_public; // NOLINT(*non-private-member-variable*)
135};
136
139
140class BOTAN_PUBLIC_API(3, 0) Kyber_PrivateKey final : public virtual Kyber_PublicKey,
141 public virtual Module_Lattice_PrivateKey,
142 public virtual Private_Key {
143 public:
144 /**
145 * Create a new private key.
146 *
147 * New ML-KEM keys are encoded in the format MlPrivateKeyFormat::Seed,
148 * new Kyber round 3 keys in MlPrivateKeyFormat::Expanded.
149 */
151
152 /**
153 * Import a private key using its key bytes.
154 *
155 * ML-KEM keys are accepted in all three CHOICE alternatives of RFC 9935
156 * (seed, expanded key, or both) and, for backwards compatibility, as the
157 * raw 64-byte seed d || z or the raw expanded key of FIPS 203. Kyber
158 * round 3 keys are accepted as the raw expanded key only. The detected
159 * format is retained, see private_key_format().
160 */
161 Kyber_PrivateKey(std::span<const uint8_t> sk, KyberMode mode);
162
163 /**
164 * Import a private key using its key bytes. See the constructor above
165 * for the accepted encodings.
166 */
167 Kyber_PrivateKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> key_bits);
168
169 std::unique_ptr<Public_Key> public_key() const override;
170
171 bool check_key(RandomNumberGenerator& rng, bool strong) const override;
172
173 std::unique_ptr<PK_Ops::KEM_Decryption> _create_kem_decryption_op(
174 RandomNumberGenerator& rng, const PK_KEM_Options_Reader& options) const override;
175
176 /**
177 * The format this key was loaded from, or the default format of a newly
178 * generated key (MlPrivateKeyFormat::Seed for ML-KEM). It is the format
179 * used for private_key_bits(), private_key_info() and
180 * raw_private_key_bits().
181 *
182 * Note that keys that contain the seed can be serialized in any format
183 * using the formatted_*() methods, whereas keys loaded from an expanded
184 * key can NOT be serialized as seed.
185 */
186 MlPrivateKeyFormat private_key_format() const override;
187
188 /**
189 * The raw key material in the given @p format: the 64-byte seed d || z
190 * or the expanded key of FIPS 203, without ASN.1 wrapping.
191 *
192 * @throws Encoding_Error for MlPrivateKeyFormat::Both (no raw encoding
193 * exists), for MlPrivateKeyFormat::Seed if the key was loaded
194 * from an expanded key (and thus holds no seed), and for
195 * anything but MlPrivateKeyFormat::Expanded on Kyber round 3 keys.
196 */
198
199 /**
200 * The ML-KEM-PrivateKey CHOICE encoding of RFC 9935 in the given
201 * @p format, i.e. the content of the PKCS#8 privateKey field. Kyber
202 * round 3 keys are encoded as the raw expanded key
203 * (MlPrivateKeyFormat::Expanded only).
204 *
205 * @throws Encoding_Error if the key cannot be encoded in @p format
206 * (see formatted_raw_private_key_bits())
207 */
209
210 BOTAN_DEPRECATED("Use formatted_raw_private_key_bits")
214
215 private:
217
218 std::shared_ptr<const Kyber_PrivateKeyInternal> m_private;
219 MlPrivateKeyFormat m_private_key_format;
220};
221
223
224} // namespace Botan
225
226#endif
#define BOTAN_DIAGNOSTIC_POP
Definition api.h:128
#define BOTAN_DIAGNOSTIC_PUSH
Definition api.h:125
#define BOTAN_DIAGNOSTIC_IGNORE_INHERITED_VIA_DOMINANCE
Definition api.h:127
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
bool operator!=(const KyberMode &other) const
Definition kyber.h:75
KyberMode(Mode mode)
Definition kyber.cpp:85
Mode mode() const
Definition kyber.h:61
secure_vector< uint8_t > private_key_bits_with_format(MlPrivateKeyFormat format) const
Definition kyber.h:211
std::unique_ptr< PK_Ops::KEM_Decryption > _create_kem_decryption_op(RandomNumberGenerator &rng, const PK_KEM_Options_Reader &options) const override
Definition kyber.cpp:306
secure_vector< uint8_t > formatted_private_key_bits(MlPrivateKeyFormat format) const override
Definition kyber.cpp:349
std::unique_ptr< Public_Key > public_key() const override
Definition kyber.cpp:260
bool check_key(RandomNumberGenerator &rng, bool strong) const override
Definition kyber.cpp:264
Kyber_PrivateKey(RandomNumberGenerator &rng, KyberMode mode)
Definition kyber.cpp:226
MlPrivateKeyFormat private_key_format() const override
Definition kyber.cpp:326
secure_vector< uint8_t > formatted_raw_private_key_bits(MlPrivateKeyFormat format) const override
Definition kyber.cpp:330
friend class Kyber_KEM_Decryptor
Definition kyber.h:216
Kyber_PublicKey & operator=(const Kyber_PublicKey &other)=default
std::vector< uint8_t > public_key_bits() const override
Definition kyber.cpp:203
Kyber_PublicKey(Kyber_PublicKey &&other)=default
std::vector< uint8_t > raw_public_key_bits() const override
Definition kyber.cpp:199
bool check_key(RandomNumberGenerator &rng, bool strong) const override
Definition kyber.cpp:213
std::string algo_name() const override
Definition kyber.cpp:163
friend class Kyber_KEM_Encryptor
Definition kyber.h:131
size_t key_length() const override
Definition kyber.cpp:209
AlgorithmIdentifier algorithm_identifier() const override
Definition kyber.cpp:167
~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:115
KyberMode mode() const
Definition kyber.cpp:159
std::shared_ptr< const Kyber_PublicKeyInternal > m_public
Definition kyber.h:134
OID object_identifier() const override
Definition kyber.cpp:175
friend class Kyber_KEM_Decryptor
Definition kyber.h:132
std::unique_ptr< Private_Key > generate_another(RandomNumberGenerator &rng) const final
Definition kyber.cpp:219
Kyber_PublicKey(std::span< const uint8_t > pub_key, KyberMode mode)
Definition kyber.cpp:191
Kyber_PublicKey & operator=(Kyber_PublicKey &&other)=default
size_t estimated_strength() const override
Definition kyber.cpp:179
PublicKeyOperation
Definition pk_keys.h:50
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition exceptn.cpp:13