Botan 3.14.1
Crypto and TLS for C&
ml_dsa_impl.cpp
Go to the documentation of this file.
1/*
2* Asymmetric primitives for ML-DSA
3* (C) 2024 Jack Lloyd
4* (C) 2024 Fabian Albert, René Meusel - Rohde & Schwarz Cybersecurity
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#include <botan/internal/ml_dsa_impl.h>
10
11#include <botan/asn1_obj.h>
12#include <botan/ber_dec.h>
13#include <botan/der_enc.h>
14#include <botan/exceptn.h>
15#include <botan/mem_ops.h>
16#include <botan/internal/dilithium_algos.h>
17#include <botan/internal/dilithium_types.h>
18#include <utility>
19
20namespace Botan {
21
22namespace {
23
24DilithiumInternalKeypair decode_seed_only(std::span<const uint8_t> key_bits, DilithiumConstants mode) {
28 .verify_end();
30 throw Decoding_Error("invalid length of ML-DSA private key seed");
31 }
32 return Dilithium_Algos::expand_keypair(std::move(seed), std::move(mode));
33}
34
35DilithiumInternalKeypair decode_expanded_only(std::span<const uint8_t> key_bits, DilithiumConstants mode) {
38 if(expanded.size() != mode.private_key_bytes()) {
39 throw Decoding_Error("invalid length of ML-DSA (or Dilithium) expanded private key byte string");
40 }
41 // decode_keypair() takes a strong span, hence no std::move
42 return Dilithium_Algos::decode_keypair(expanded, std::move(mode));
43}
44
45DilithiumInternalKeypair decode_seed_plus_expanded(std::span<const uint8_t> key_bits, DilithiumConstants mode) {
52 .end_cons()
53 .verify_end();
54 if(expanded.size() != mode.private_key_bytes()) {
55 throw Decoding_Error("invalid length of ML-DSA expanded private key byte string");
56 }
57 // The expanded key is not parsed on its own: it must be byte-identical to the
58 // canonical encoding of the key pair expanded from the seed, which is what is returned.
59 const DilithiumInternalKeypair key_pair_from_seed =
60 Dilithium_Algos::expand_keypair(std::move(seed), std::move(mode));
61 const DilithiumSerializedPrivateKey expanded_from_seed = Dilithium_Algos::encode_keypair(key_pair_from_seed);
62 // both operands are secret key material, hence the constant-time comparison
63 if(!constant_time_compare(expanded_from_seed.get(), expanded.get())) {
64 throw Decoding_Error("seed and expanded key in ML-DSA serialized key do not match");
65 }
66 return key_pair_from_seed;
67}
68
69} // namespace
70
72 MlPrivateKeyFormat format) const {
73 BOTAN_ASSERT_NONNULL(keypair.second);
74 const auto& seed = keypair.second->seed();
75 if(format != MlPrivateKeyFormat::Expanded && !seed.has_value()) {
76 throw Encoding_Error("ML-DSA private key does not contain the seed, cannot encode it in the requested format");
77 }
78
80 DER_Encoder der_enc(result);
81 switch(format) {
83 /*
84 * RFC 9881 "seed" CHOICE alternative: [0] IMPLICIT OCTET STRING, i.e.
85 *
86 * <80 20>
87 * 0 32: [0]
88 * : 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
89 * : 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
90 *
91 * Note: The previous, non-standard format, which only contained the
92 * seed as a raw byte string, is still accepted by decode_keypair().
93 */
95 break;
97 // RFC 9881 "expandedKey" CHOICE alternative: OCTET STRING
99 break;
101 // RFC 9881 "both" CHOICE alternative:
102 // SEQUENCE { seed OCTET STRING, expandedKey OCTET STRING }
103 der_enc.start_sequence()
104 .encode(seed->get(), ASN1_Type::OctetString)
106 .end_cons();
107 break;
108 }
109
110 return result;
111}
112
114 DilithiumConstants mode) const {
115 if(private_key_bits.size() == DilithiumConstants::SEED_RANDOMNESS_BYTES) {
116 // backwards compatibility (not RFC 9881 conforming) to the raw seed format
117 return {
118 .keypair = Dilithium_Algos::expand_keypair(DilithiumSeedRandomness(private_key_bits), std::move(mode)),
119 .format = MlPrivateKeyFormat::Seed,
120 };
121 }
122 if(private_key_bits.size() == mode.private_key_bytes()) {
123 // raw expanded key in the FIPS 204 sk encoding without ASN.1 wrapping (not RFC 9881 conforming),
124 // as used e.g. by the NIST ACVP and Wycheproof test vectors. The length cannot collide with any
125 // of the RFC 9881 encodings.
126 return {
128 std::move(mode)),
130 };
131 }
132 // "seed-only" format from RFC 9881
133 BER_Decoder ber_dec(private_key_bits, BER_Decoder::Limits::DER());
134 auto obj = ber_dec.peek_next_object();
135 if(obj.type() == ASN1_Type(0) && obj.class_tag() == ASN1_Class::ContextSpecific) {
136 return {
137 .keypair = decode_seed_only(private_key_bits, std::move(mode)),
138 .format = MlPrivateKeyFormat::Seed,
139 };
140 }
141 // now it could still be "expanded-only" or "both"
142 if(obj.type() == ASN1_Type::OctetString && obj.class_tag() == ASN1_Class::Universal) {
143 return {
144 .keypair = decode_expanded_only(private_key_bits, std::move(mode)),
146 };
147 }
148 return {
149 .keypair = decode_seed_plus_expanded(private_key_bits, std::move(mode)),
150 .format = MlPrivateKeyFormat::Both,
151 };
152}
153
154} // namespace Botan
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
static Limits DER()
Definition ber_dec.h:44
const BER_Object & peek_next_object()
Definition ber_dec.cpp:510
BER_Decoder & decode(bool &out)
Definition ber_dec.h:361
BER_Decoder & verify_end()
Definition ber_dec.cpp:471
BER_Decoder & end_cons()
Definition ber_dec.cpp:635
BER_Decoder start_sequence()
Definition ber_dec.h:279
DER_Encoder & start_sequence()
Definition der_enc.h:86
DER_Encoder & end_cons()
Definition der_enc.cpp:208
DER_Encoder & encode(bool b)
Definition der_enc.cpp:313
static constexpr size_t SEED_RANDOMNESS_BYTES
size_t private_key_bytes() const
byte length of the encoded private key
secure_vector< uint8_t > encode_keypair(const DilithiumInternalKeypair &keypair, MlPrivateKeyFormat format) const override
DilithiumDecodedKeypair decode_keypair(std::span< const uint8_t > private_key, DilithiumConstants mode) const override
DilithiumInternalKeypair expand_keypair(DilithiumSeedRandomness xi, DilithiumConstants mode)
DilithiumSerializedPrivateKey encode_keypair(const DilithiumInternalKeypair &keypair)
DilithiumInternalKeypair decode_keypair(StrongSpan< const DilithiumSerializedPrivateKey > sk, DilithiumConstants mode)
ASN1_Type
Definition asn1_obj.h:47
Strong< secure_vector< uint8_t >, struct DilithiumSeedRandomness_ > DilithiumSeedRandomness
Principal seed used to generate Dilithium key pairs.
Strong< secure_vector< uint8_t >, struct DilithiumSerializedPrivateKey_ > DilithiumSerializedPrivateKey
Serialized private key data.
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
bool constant_time_compare(std::span< const uint8_t > x, std::span< const uint8_t > y)
Definition mem_ops.cpp:17
std::pair< std::shared_ptr< const Dilithium_PublicKeyInternal >, std::shared_ptr< const Dilithium_PrivateKeyInternal > > DilithiumInternalKeypair
Internal representation of a Dilithium key pair.
A decoded private key together with the encoding format it was found in.