1 // Copyright 2023 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 // Package mlkem implements the quantum-resistant key encapsulation method
6 // ML-KEM (formerly known as Kyber), as specified in [NIST FIPS 203].
7 //
8 // Most applications should use the ML-KEM-768 parameter set, as implemented by
9 // [DecapsulationKey768] and [EncapsulationKey768].
10 //
11 // [NIST FIPS 203]: https://doi.org/10.6028/NIST.FIPS.203
12 package mlkem
13 14 import (
15 "crypto"
16 "crypto/internal/fips140/mlkem"
17 )
18 19 const (
20 // SharedKeySize is the size of a shared key produced by ML-KEM.
21 SharedKeySize = 32
22 23 // SeedSize is the size of a seed used to generate a decapsulation key.
24 SeedSize = 64
25 26 // CiphertextSize768 is the size of a ciphertext produced by ML-KEM-768.
27 CiphertextSize768 = 1088
28 29 // EncapsulationKeySize768 is the size of an ML-KEM-768 encapsulation key.
30 EncapsulationKeySize768 = 1184
31 32 // CiphertextSize1024 is the size of a ciphertext produced by ML-KEM-1024.
33 CiphertextSize1024 = 1568
34 35 // EncapsulationKeySize1024 is the size of an ML-KEM-1024 encapsulation key.
36 EncapsulationKeySize1024 = 1568
37 )
38 39 // DecapsulationKey768 is the secret key used to decapsulate a shared key
40 // from a ciphertext. It includes various precomputed values.
41 type DecapsulationKey768 struct {
42 key *mlkem.DecapsulationKey768
43 }
44 45 // GenerateKey768 generates a new decapsulation key, drawing random bytes from
46 // the default crypto/rand source. The decapsulation key must be kept secret.
47 func GenerateKey768() (*DecapsulationKey768, error) {
48 key, err := mlkem.GenerateKey768()
49 if err != nil {
50 return nil, err
51 }
52 53 return &DecapsulationKey768{key}, nil
54 }
55 56 // NewDecapsulationKey768 expands a decapsulation key from a 64-byte seed in the
57 // "d || z" form. The seed must be uniformly random.
58 func NewDecapsulationKey768(seed []byte) (*DecapsulationKey768, error) {
59 key, err := mlkem.NewDecapsulationKey768(seed)
60 if err != nil {
61 return nil, err
62 }
63 64 return &DecapsulationKey768{key}, nil
65 }
66 67 // Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
68 //
69 // The decapsulation key must be kept secret.
70 func (dk *DecapsulationKey768) Bytes() []byte {
71 return dk.key.Bytes()
72 }
73 74 // Decapsulate generates a shared key from a ciphertext and a decapsulation
75 // key. If the ciphertext is not valid, Decapsulate returns an error.
76 //
77 // The shared key must be kept secret.
78 func (dk *DecapsulationKey768) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) {
79 return dk.key.Decapsulate(ciphertext)
80 }
81 82 // EncapsulationKey returns the public encapsulation key necessary to produce
83 // ciphertexts.
84 func (dk *DecapsulationKey768) EncapsulationKey() *EncapsulationKey768 {
85 return &EncapsulationKey768{dk.key.EncapsulationKey()}
86 }
87 88 // Encapsulator returns the public encapsulation key as a crypto.Encapsulator.
89 func (dk *DecapsulationKey768) Encapsulator() crypto.Encapsulator {
90 return dk.EncapsulationKey()
91 }
92 93 // An EncapsulationKey768 is the public key used to produce ciphertexts to be
94 // decapsulated by the corresponding DecapsulationKey768.
95 type EncapsulationKey768 struct {
96 key *mlkem.EncapsulationKey768
97 }
98 99 // NewEncapsulationKey768 parses an encapsulation key from its encoded form. If
100 // the encapsulation key is not valid, NewEncapsulationKey768 returns an error.
101 func NewEncapsulationKey768(encapsulationKey []byte) (*EncapsulationKey768, error) {
102 key, err := mlkem.NewEncapsulationKey768(encapsulationKey)
103 if err != nil {
104 return nil, err
105 }
106 107 return &EncapsulationKey768{key}, nil
108 }
109 110 // Bytes returns the encapsulation key as a byte slice.
111 func (ek *EncapsulationKey768) Bytes() []byte {
112 return ek.key.Bytes()
113 }
114 115 // Encapsulate generates a shared key and an associated ciphertext from an
116 // encapsulation key, drawing random bytes from the default crypto/rand source.
117 //
118 // The shared key must be kept secret.
119 func (ek *EncapsulationKey768) Encapsulate() (sharedKey, ciphertext []byte) {
120 return ek.key.Encapsulate()
121 }
122 123 // DecapsulationKey1024 is the secret key used to decapsulate a shared key
124 // from a ciphertext. It includes various precomputed values.
125 type DecapsulationKey1024 struct {
126 key *mlkem.DecapsulationKey1024
127 }
128 129 // GenerateKey1024 generates a new decapsulation key, drawing random bytes from
130 // the default crypto/rand source. The decapsulation key must be kept secret.
131 func GenerateKey1024() (*DecapsulationKey1024, error) {
132 key, err := mlkem.GenerateKey1024()
133 if err != nil {
134 return nil, err
135 }
136 137 return &DecapsulationKey1024{key}, nil
138 }
139 140 // NewDecapsulationKey1024 expands a decapsulation key from a 64-byte seed in the
141 // "d || z" form. The seed must be uniformly random.
142 func NewDecapsulationKey1024(seed []byte) (*DecapsulationKey1024, error) {
143 key, err := mlkem.NewDecapsulationKey1024(seed)
144 if err != nil {
145 return nil, err
146 }
147 148 return &DecapsulationKey1024{key}, nil
149 }
150 151 // Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
152 //
153 // The decapsulation key must be kept secret.
154 func (dk *DecapsulationKey1024) Bytes() []byte {
155 return dk.key.Bytes()
156 }
157 158 // Decapsulate generates a shared key from a ciphertext and a decapsulation
159 // key. If the ciphertext is not valid, Decapsulate returns an error.
160 //
161 // The shared key must be kept secret.
162 func (dk *DecapsulationKey1024) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) {
163 return dk.key.Decapsulate(ciphertext)
164 }
165 166 // EncapsulationKey returns the public encapsulation key necessary to produce
167 // ciphertexts.
168 func (dk *DecapsulationKey1024) EncapsulationKey() *EncapsulationKey1024 {
169 return &EncapsulationKey1024{dk.key.EncapsulationKey()}
170 }
171 172 // Encapsulator returns the public encapsulation key as a crypto.Encapsulator.
173 func (dk *DecapsulationKey1024) Encapsulator() crypto.Encapsulator {
174 return dk.EncapsulationKey()
175 }
176 177 // An EncapsulationKey1024 is the public key used to produce ciphertexts to be
178 // decapsulated by the corresponding DecapsulationKey1024.
179 type EncapsulationKey1024 struct {
180 key *mlkem.EncapsulationKey1024
181 }
182 183 // NewEncapsulationKey1024 parses an encapsulation key from its encoded form. If
184 // the encapsulation key is not valid, NewEncapsulationKey1024 returns an error.
185 func NewEncapsulationKey1024(encapsulationKey []byte) (*EncapsulationKey1024, error) {
186 key, err := mlkem.NewEncapsulationKey1024(encapsulationKey)
187 if err != nil {
188 return nil, err
189 }
190 191 return &EncapsulationKey1024{key}, nil
192 }
193 194 // Bytes returns the encapsulation key as a byte slice.
195 func (ek *EncapsulationKey1024) Bytes() []byte {
196 return ek.key.Bytes()
197 }
198 199 // Encapsulate generates a shared key and an associated ciphertext from an
200 // encapsulation key, drawing random bytes from the default crypto/rand source.
201 //
202 // The shared key must be kept secret.
203 func (ek *EncapsulationKey1024) Encapsulate() (sharedKey, ciphertext []byte) {
204 return ek.key.Encapsulate()
205 }
206