Botan 3.14.1
Crypto and TLS for C&
dilithium.h
Go to the documentation of this file.
1/*
2* Crystals Dilithium Digital Signature Algorithms
3* Based on the public domain reference implementation by the
4* designers (https://github.com/pq-crystals/dilithium)
5*
6* Further changes
7* (C) 2021-2023 Jack Lloyd
8* (C) 2021-2022 Manuel Glaser - Rohde & Schwarz Cybersecurity
9* (C) 2021-2023 Michael Boric, René Meusel - Rohde & Schwarz Cybersecurity
10*
11* Botan is released under the Simplified BSD License (see license.txt)
12*/
13
14#ifndef BOTAN_DILITHIUM_COMMON_H_
15#define BOTAN_DILITHIUM_COMMON_H_
16
17#include <botan/module_lattice_keys.h>
18#include <botan/pk_keys.h>
19
20namespace Botan {
21
23 public:
24 enum Mode : uint8_t /* NOLINT(*-use-enum-class) */ {
25 Dilithium4x4 BOTAN_DEPRECATED("Dilithium R3 is deprecated - use ML-DSA") = 1,
26 Dilithium4x4_AES BOTAN_DEPRECATED("Dilithium AES mode is deprecated"),
27 Dilithium6x5 BOTAN_DEPRECATED("Dilithium R3 is deprecated - use ML-DSA"),
28 Dilithium6x5_AES BOTAN_DEPRECATED("Dilithium AES mode is deprecated"),
29 Dilithium8x7 BOTAN_DEPRECATED("Dilithium R3 is deprecated - use ML-DSA"),
30 Dilithium8x7_AES BOTAN_DEPRECATED("Dilithium AES mode is deprecated"),
34 };
35
36 public:
37 // NOLINTNEXTLINE(*-explicit-conversions,*-explicit-constructor)
39
40 explicit DilithiumMode(const OID& oid);
41 explicit DilithiumMode(std::string_view str);
42
43 OID object_identifier() const;
44 std::string to_string() const;
45
46 BOTAN_DEPRECATED("Dilithium AES mode is deprecated") bool is_aes() const;
47 BOTAN_DEPRECATED("Dilithium AES mode is deprecated") bool is_modern() const;
48 bool is_ml_dsa() const;
49
50 bool is_dilithium_round3() const { return !is_ml_dsa(); }
51
52 bool is_available() const;
53
54 Mode mode() const { return m_mode; }
55
56 private:
57 Mode m_mode;
58};
59
60class Dilithium_PublicKeyInternal;
61class Dilithium_PrivateKeyInternal;
62
63/**
64 * This implementation is based on
65 * https://github.com/pq-crystals/dilithium/commit/3e9b9f1412f6c7435dbeb4e10692ea58f181ee51
66 *
67 * Note that this is _not_ compatible with the round 3 submission of the NIST competition.
68 */
69class BOTAN_PUBLIC_API(3, 0) Dilithium_PublicKey : public virtual Public_Key {
70 public:
71 std::string algo_name() const override;
72
74
75 OID object_identifier() const override;
76
77 size_t key_length() const override;
78
79 size_t estimated_strength() const override;
80
81 std::vector<uint8_t> raw_public_key_bits() const override;
82
83 std::vector<uint8_t> public_key_bits() const override;
84
85 bool check_key(RandomNumberGenerator& rng, bool strong) const override;
86
87 bool supports_operation(PublicKeyOperation op) const override { return (op == PublicKeyOperation::Signature); }
88
89 std::unique_ptr<Private_Key> generate_another(RandomNumberGenerator& rng) const final;
90
91 Dilithium_PublicKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> pk);
92
93 Dilithium_PublicKey(std::span<const uint8_t> pk, DilithiumMode mode);
94
95 std::unique_ptr<PK_Ops::Verification> _create_verification_op(
96 const PK_Signature_Options_Reader& options) const override;
97
98 std::unique_ptr<PK_Ops::Verification> create_x509_verification_op(const AlgorithmIdentifier& signature_algorithm,
99 std::string_view provider) const override;
100
101 protected:
103
106
107 std::shared_ptr<const Dilithium_PublicKeyInternal> m_public; // NOLINT(*non-private-member-variable*)
108};
109
112
114 public virtual Module_Lattice_PrivateKey,
115 public virtual Private_Key {
116 public:
117 std::unique_ptr<Public_Key> public_key() const override;
118
119 bool check_key(RandomNumberGenerator& rng, bool strong) const override;
120
121 /**
122 * Generates a new key pair.
123 *
124 * New ML-DSA keys are encoded in the format MlPrivateKeyFormat::Seed,
125 * new Dilithium round 3 keys in MlPrivateKeyFormat::Expanded.
126 */
128
129 /**
130 * Read an encoded private key.
131 *
132 * ML-DSA keys are accepted in all three CHOICE alternatives of RFC 9881
133 * (seed, expanded key, or both) and, for backwards compatibility, as the
134 * raw 32-byte seed or the raw expanded key of FIPS 204. Dilithium round 3
135 * keys are accepted as the raw expanded key only. The detected format is
136 * retained, see private_key_format().
137 */
138 Dilithium_PrivateKey(const AlgorithmIdentifier& alg_id, std::span<const uint8_t> sk);
139
140 /**
141 * Read an encoded private key given the dilithium @p mode. See the
142 * constructor above for the accepted encodings.
143 */
144 Dilithium_PrivateKey(std::span<const uint8_t> sk, DilithiumMode mode);
145
146 /**
147 * The format this key was loaded from, or the default format of a newly
148 * generated key (MlPrivateKeyFormat::Seed for ML-DSA). It is the format
149 * used for private_key_bits(), private_key_info() and
150 * raw_private_key_bits().
151 */
152 MlPrivateKeyFormat private_key_format() const override;
153
154 /**
155 * The raw key material in the given @p format: the 32-byte seed or the
156 * expanded key of FIPS 204, without ASN.1 wrapping.
157 *
158 * @throws Encoding_Error for MlPrivateKeyFormat::Both (no raw encoding
159 * exists), for MlPrivateKeyFormat::Seed if the key was loaded
160 * from an expanded key (and thus holds no seed), and for
161 * anything but MlPrivateKeyFormat::Expanded on Dilithium round 3 keys.
162 */
164
165 /**
166 * The ML-DSA-PrivateKey CHOICE encoding of RFC 9881 in the given
167 * @p format, i.e. the content of the PKCS#8 privateKey field. Dilithium
168 * round 3 keys are encoded as the raw expanded key
169 * (MlPrivateKeyFormat::Expanded only).
170 *
171 * @throws Encoding_Error if the key cannot be encoded in @p format
172 * (see formatted_raw_private_key_bits())
173 */
175
176 std::unique_ptr<PK_Ops::Signature> _create_signature_op(
177 RandomNumberGenerator& rng, const PK_Signature_Options_Reader& options) const override;
178
179 bool is_ml_dsa() const;
180
181 bool is_dilithium_round3() const;
182
183 private:
185
186 std::shared_ptr<const Dilithium_PrivateKeyInternal> m_private;
187 MlPrivateKeyFormat m_private_key_format;
188};
189
191
192} // namespace Botan
193
194#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
Mode mode() const
Definition dilithium.h:54
DilithiumMode(Mode mode)
Definition dilithium.h:38
bool is_dilithium_round3() const
Definition dilithium.h:50
bool is_ml_dsa() const
MlPrivateKeyFormat private_key_format() const override
friend class Dilithium_Signature_Operation
Definition dilithium.h:184
Dilithium_PrivateKey(RandomNumberGenerator &rng, DilithiumMode mode)
secure_vector< uint8_t > formatted_raw_private_key_bits(MlPrivateKeyFormat format) const override
bool check_key(RandomNumberGenerator &rng, bool strong) const override
std::unique_ptr< Public_Key > public_key() const override
std::unique_ptr< PK_Ops::Signature > _create_signature_op(RandomNumberGenerator &rng, const PK_Signature_Options_Reader &options) const override
secure_vector< uint8_t > formatted_private_key_bits(MlPrivateKeyFormat format) const override
AlgorithmIdentifier algorithm_identifier() const override
std::vector< uint8_t > public_key_bits() const override
friend class Dilithium_Signature_Operation
Definition dilithium.h:105
OID object_identifier() const override
bool supports_operation(PublicKeyOperation op) const override
Definition dilithium.h:87
Dilithium_PublicKey(const AlgorithmIdentifier &alg_id, std::span< const uint8_t > pk)
size_t key_length() const override
friend class Dilithium_Verification_Operation
Definition dilithium.h:104
std::string algo_name() const override
size_t estimated_strength() const override
std::shared_ptr< const Dilithium_PublicKeyInternal > m_public
Definition dilithium.h:107
std::vector< uint8_t > raw_public_key_bits() const override
bool check_key(RandomNumberGenerator &rng, bool strong) const override
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