Botan 3.14.1
Crypto and TLS for C&
module_lattice_keys.h
Go to the documentation of this file.
1/*
2 * Common private key interface for the module-lattice schemes ML-KEM and ML-DSA
3 *
4 * (C) 2026 Jack Lloyd
5 * (C) 2026 Falko Strenzke - MTG AG
6 *
7 * Botan is released under the Simplified BSD License (see license.txt)
8 */
9
10#ifndef BOTAN_MODULE_LATTICE_KEYS_H_
11#define BOTAN_MODULE_LATTICE_KEYS_H_
12
13#include <botan/pk_keys.h>
14
15namespace Botan {
16
17/**
18 * Encoding format of an ML-KEM or ML-DSA private key
19 */
20enum class MlPrivateKeyFormat : uint8_t {
21 /**
22 * Only the private random seed from which the key pair is expanded.
23 *
24 * - ML-KEM: the 64-byte seed d || z (FIPS 203)
25 * - ML-DSA: the 32-byte seed xi (FIPS 204)
26 *
27 * As content of the PKCS#8 privateKey field this is the "seed" CHOICE
28 * alternative ([0] IMPLICIT OCTET STRING) of RFC 9935 (ML-KEM) or
29 * RFC 9881 (ML-DSA). This is the format of newly generated ML-KEM and
30 * ML-DSA keys.
31 *
32 * Not available for the pre-standard Kyber and Dilithium round 3 variants.
33 */
35 /**
36 * The expanded private key as specified in FIPS 203 (ML-KEM) or FIPS 204
37 * (ML-DSA). As content of the PKCS#8 privateKey field this is the
38 * "expandedKey" CHOICE alternative (OCTET STRING) of RFC 9935 (ML-KEM) or
39 * RFC 9881 (ML-DSA).
40 *
41 * This is the only format supported by the pre-standard Kyber and
42 * Dilithium round 3 variants.
43 */
45 /**
46 * Seed and expanded key together. As content of the PKCS#8 privateKey
47 * field this is the "both" CHOICE alternative
48 * (SEQUENCE { seed OCTET STRING, expandedKey OCTET STRING }) of RFC 9935
49 * (ML-KEM) or RFC 9881 (ML-DSA).
50 *
51 * There is no raw (non-ASN.1) encoding of this format.
52 */
54};
55
56/**
57 * Interface shared by the private keys of the module-lattice schemes
58 * ML-KEM/Kyber (Kyber_PrivateKey) and ML-DSA/Dilithium (Dilithium_PrivateKey).
59 *
60 * Such keys can be represented by their private seed, by the expanded key of
61 * FIPS 203/204, or by both. A key remembers the format it was
62 * loaded from, or the scheme's default format when it was freshly generated;
63 * private_key_bits(), private_key_info() and raw_private_key_bits() use that
64 * format. Keys that contain the seed can additionally be exported in any other
65 * format, whereas keys loaded from an expanded encoding cannot be exported as a
66 * seed.
67 *
68 * Given a generic Private_Key, this interface is obtained via
69 * dynamic_cast<const Module_Lattice_PrivateKey*>(&key).
70 */
72 public:
73 /**
74 * The private key format this key was loaded from or, for a freshly
75 * generated key, the default format of the scheme. This is the format
76 * used by private_key_bits(), private_key_info() and raw_private_key_bits().
77 */
79
80 /**
81 * The raw private key material in the given @p format without any
82 * ASN.1 wrapping, i.e. the bare seed bytes or the expanded key as
83 * specified in FIPS 203/204.
84 *
85 * @throws Encoding_Error if the key cannot be encoded in @p format.
86 * This is the case for MlPrivateKeyFormat::Both, which has no
87 * raw encoding, for MlPrivateKeyFormat::Seed if the key does not
88 * contain the seed, and for anything but
89 * MlPrivateKeyFormat::Expanded on Kyber or Dilithium round 3 keys.
90 */
92
93 /**
94 * The private key encoded in the given @p format as it appears in the
95 * privateKey OCTET STRING of a PKCS#8 PrivateKeyInfo structure. This is
96 * what private_key_bits() returns for a key whose private_key_format()
97 * is @p format.
98 *
99 * - ML-KEM: the ML-KEM-PrivateKey CHOICE encoding of RFC 9935
100 * - ML-DSA: the ML-DSA-PrivateKey CHOICE encoding of RFC 9881
101 * - Kyber and Dilithium round 3: the raw expanded key
102 *
103 * @throws Encoding_Error if the key cannot be encoded in @p format
104 * (see formatted_raw_private_key_bits()).
105 */
107
108 /**
109 * Equivalent to formatted_private_key_bits(private_key_format())
110 */
112
113 /**
114 * Equivalent to formatted_raw_private_key_bits(private_key_format()).
115 *
116 * @note Keys in the format MlPrivateKeyFormat::Both, which has no raw
117 * encoding, return the seed instead.
118 */
119 secure_vector<uint8_t> raw_private_key_bits() const final;
120};
121
122} // namespace Botan
123
124#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
virtual MlPrivateKeyFormat private_key_format() const =0
secure_vector< uint8_t > raw_private_key_bits() const final
virtual secure_vector< uint8_t > formatted_private_key_bits(MlPrivateKeyFormat format) const =0
secure_vector< uint8_t > private_key_bits() const final
virtual secure_vector< uint8_t > formatted_raw_private_key_bits(MlPrivateKeyFormat format) const =0
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128