crypto/mlkem: init package

This commit exposes the crypto/internal/mlkem package as a public crypto
package based on the linked proposal. Since we've already implemented
this internal to the FIPS boundary this largely defers to that
implementation.

Updates #70122

Change-Id: I5ec9c2783c4d44583244c6d16597704a51e9b738
Reviewed-on: https://go-review.googlesource.com/c/go/+/630240
Reviewed-by: Filippo Valsorda <filippo@golang.org>
Reviewed-by: Roland Shoemaker <roland@golang.org>
Auto-Submit: Filippo Valsorda <filippo@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>

3 files changed, 234 insertions, 8 deletions

diff --git a/src/crypto/mlkem/mlkem1024.go b/src/crypto/mlkem/mlkem1024.go
new file mode 100644
index 0000000000..530aacf00f
--- /dev/null
+++ b/src/crypto/mlkem/mlkem1024.go
@@ -0,0 +1,96 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package mlkem
+
+import "crypto/internal/fips140/mlkem"
+
+const (
+	// CiphertextSize1024 is the size of a ciphertext produced by the 1024-bit
+	// variant of ML-KEM.
+	CiphertextSize1024 = 1568
+
+	// EncapsulationKeySize1024 is the size of an encapsulation key for the
+	// 1024-bit variant of ML-KEM.
+	EncapsulationKeySize1024 = 1568
+)
+
+// DecapsulationKey1024 is the secret key used to decapsulate a shared key
+// from a ciphertext. It includes various precomputed values.
+type DecapsulationKey1024 struct {
+	key *mlkem.DecapsulationKey1024
+}
+
+// GenerateKey1024 generates a new decapsulation key, drawing random bytes from
+// crypto/rand. The decapsulation key must be kept secret.
+func GenerateKey1024() (*DecapsulationKey1024, error) {
+	key, err := mlkem.GenerateKey1024()
+	if err != nil {
+		return nil, err
+	}
+
+	return &DecapsulationKey1024{key}, nil
+}
+
+// NewDecapsulationKey1024 parses a decapsulation key from a 64-byte seed in the
+// "d || z" form. The seed must be uniformly random.
+func NewDecapsulationKey1024(seed []byte) (*DecapsulationKey1024, error) {
+	key, err := mlkem.NewDecapsulationKey1024(seed)
+	if err != nil {
+		return nil, err
+	}
+
+	return &DecapsulationKey1024{key}, nil
+}
+
+// Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
+//
+// The decapsulation key must be kept secret.
+func (dk *DecapsulationKey1024) Bytes() []byte {
+	return dk.key.Bytes()
+}
+
+// Decapsulate generates a shared key from a ciphertext and a decapsulation
+// key. If the ciphertext is not valid, Decapsulate returns an error.
+//
+// The shared key must be kept secret.
+func (dk *DecapsulationKey1024) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) {
+	return dk.key.Decapsulate(ciphertext)
+}
+
+// EncapsulationKey returns the public encapsulation key necessary to produce
+// ciphertexts.
+func (dk *DecapsulationKey1024) EncapsulationKey() *EncapsulationKey1024 {
+	return &EncapsulationKey1024{dk.key.EncapsulationKey()}
+}
+
+// An EncapsulationKey1024 is the public key used to produce ciphertexts to be
+// decapsulated by the corresponding DecapsulationKey1024.
+type EncapsulationKey1024 struct {
+	key *mlkem.EncapsulationKey1024
+}
+
+// NewEncapsulationKey1024 parses an encapsulation key from its encoded form. If
+// the encapsulation key is not valid, NewEncapsulationKey1024 returns an error.
+func NewEncapsulationKey1024(encapsulationKey []byte) (*EncapsulationKey1024, error) {
+	key, err := mlkem.NewEncapsulationKey1024(encapsulationKey)
+	if err != nil {
+		return nil, err
+	}
+
+	return &EncapsulationKey1024{key}, nil
+}
+
+// Bytes returns the encapsulation key as a byte slice.
+func (ek *EncapsulationKey1024) Bytes() []byte {
+	return ek.key.Bytes()
+}
+
+// Encapsulate generates a shared key and an associated ciphertext from an
+// encapsulation key, drawing random bytes from crypto/rand.
+//
+// The shared key must be kept secret.
+func (ek *EncapsulationKey1024) Encapsulate() (ciphertext, sharedKey []byte) {
+	return ek.key.Encapsulate()
+}
diff --git a/src/crypto/mlkem/mlkem768.go b/src/crypto/mlkem/mlkem768.go
new file mode 100644
index 0000000000..d6f5c94171
--- /dev/null
+++ b/src/crypto/mlkem/mlkem768.go
@@ -0,0 +1,106 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package mlkem implements the quantum-resistant key encapsulation method
+// ML-KEM (formerly known as Kyber), as specified in [NIST FIPS 203].
+//
+// [NIST FIPS 203]: https://doi.org/10.6028/NIST.FIPS.203
+package mlkem
+
+import "crypto/internal/fips140/mlkem"
+
+const (
+	// SharedKeySize is the size of a shared key produced by ML-KEM.
+	SharedKeySize = 32
+
+	// SeedSize is the size of a seed used to generate a decapsulation key.
+	SeedSize = 64
+
+	// CiphertextSize768 is the size of a ciphertext produced by the 768-bit
+	// variant of ML-KEM.
+	CiphertextSize768 = 1088
+
+	// EncapsulationKeySize768 is the size of an encapsulation key for the
+	// 768-bit variant of ML-KEM.
+	EncapsulationKeySize768 = 1184
+)
+
+// DecapsulationKey768 is the secret key used to decapsulate a shared key
+// from a ciphertext. It includes various precomputed values.
+type DecapsulationKey768 struct {
+	key *mlkem.DecapsulationKey768
+}
+
+// GenerateKey768 generates a new decapsulation key, drawing random bytes from
+// crypto/rand. The decapsulation key must be kept secret.
+func GenerateKey768() (*DecapsulationKey768, error) {
+	key, err := mlkem.GenerateKey768()
+	if err != nil {
+		return nil, err
+	}
+
+	return &DecapsulationKey768{key}, nil
+}
+
+// NewDecapsulationKey768 parses a decapsulation key from a 64-byte seed in the
+// "d || z" form. The seed must be uniformly random.
+func NewDecapsulationKey768(seed []byte) (*DecapsulationKey768, error) {
+	key, err := mlkem.NewDecapsulationKey768(seed)
+	if err != nil {
+		return nil, err
+	}
+
+	return &DecapsulationKey768{key}, nil
+}
+
+// Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.
+//
+// The decapsulation key must be kept secret.
+func (dk *DecapsulationKey768) Bytes() []byte {
+	return dk.key.Bytes()
+}
+
+// Decapsulate generates a shared key from a ciphertext and a decapsulation
+// key. If the ciphertext is not valid, Decapsulate returns an error.
+//
+// The shared key must be kept secret.
+func (dk *DecapsulationKey768) Decapsulate(ciphertext []byte) (sharedKey []byte, err error) {
+	return dk.key.Decapsulate(ciphertext)
+}
+
+// EncapsulationKey returns the public encapsulation key necessary to produce
+// ciphertexts.
+func (dk *DecapsulationKey768) EncapsulationKey() *EncapsulationKey768 {
+	return &EncapsulationKey768{dk.key.EncapsulationKey()}
+}
+
+// An EncapsulationKey768 is the public key used to produce ciphertexts to be
+// decapsulated by the corresponding DecapsulationKey768.
+type EncapsulationKey768 struct {
+	key *mlkem.EncapsulationKey768
+}
+
+// NewEncapsulationKey768 parses an encapsulation key from its encoded form. If
+// the encapsulation key is not valid, NewEncapsulationKey768 returns an error.
+func NewEncapsulationKey768(encapsulationKey []byte) (*EncapsulationKey768, error) {
+	key, err := mlkem.NewEncapsulationKey768(encapsulationKey)
+	if err != nil {
+		return nil, err
+	}
+
+	return &EncapsulationKey768{key}, nil
+}
+
+// Bytes returns the encapsulation key as a byte slice.
+func (ek *EncapsulationKey768) Bytes() []byte {
+	return ek.key.Bytes()
+}
+
+// Encapsulate generates a shared key and an associated ciphertext from an
+// encapsulation key, drawing random bytes from crypto/rand.
+//
+// The shared key must be kept secret.
+func (ek *EncapsulationKey768) Encapsulate() (ciphertext, sharedKey []byte) {
+	return ek.key.Encapsulate()
+}
diff --git a/src/crypto/internal/fips140test/mlkem_test.go b/src/crypto/mlkem/mlkem_test.go
index 43467456f0..ddc52dab97 100644
--- a/src/crypto/internal/fips140test/mlkem_test.go
+++ b/src/crypto/mlkem/mlkem_test.go
@@ -2,16 +2,13 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-package fipstest_test
-
-// TODO(fips, #70122): move this to crypto/mlkem once it exists.
+package mlkem
 
 import (
 	"bytes"
-	. "crypto/internal/fips140/mlkem"
+	"crypto/internal/fips140/mlkem"
 	"crypto/internal/fips140/sha3"
 	"crypto/rand"
-	_ "embed"
 	"encoding/hex"
 	"flag"
 	"testing"
@@ -192,7 +189,7 @@ func TestAccumulated(t *testing.T) {
 		o.Write(ek.Bytes())
 
 		s.Read(msg[:])
-		ct, k := ek.EncapsulateInternal(&msg)
+		ct, k := ek.key.EncapsulateInternal(&msg)
 		o.Write(ct)
 		o.Write(k)
 
@@ -226,7 +223,7 @@ func BenchmarkKeyGen(b *testing.B) {
 	rand.Read(z[:])
 	b.ResetTimer()
 	for i := 0; i < b.N; i++ {
-		dk := GenerateKeyInternal768(&d, &z)
+		dk := mlkem.GenerateKeyInternal768(&d, &z)
 		sink ^= dk.EncapsulationKey().Bytes()[0]
 	}
 }
@@ -247,7 +244,7 @@ func BenchmarkEncaps(b *testing.B) {
 		if err != nil {
 			b.Fatal(err)
 		}
-		c, K := ek.EncapsulateInternal(&m)
+		c, K := ek.key.EncapsulateInternal(&m)
 		sink ^= c[0] ^ K[0]
 	}
 }
@@ -307,3 +304,30 @@ func BenchmarkRoundTrip(b *testing.B) {
 		}
 	})
 }
+
+// Test that the constants from the public API match the corresponding values from the internal API.
+func TestConstantSizes(t *testing.T) {
+	if SharedKeySize != mlkem.SharedKeySize {
+		t.Errorf("SharedKeySize mismatch: got %d, want %d", SharedKeySize, mlkem.SharedKeySize)
+	}
+
+	if SeedSize != mlkem.SeedSize {
+		t.Errorf("SeedSize mismatch: got %d, want %d", SeedSize, mlkem.SeedSize)
+	}
+
+	if CiphertextSize768 != mlkem.CiphertextSize768 {
+		t.Errorf("CiphertextSize768 mismatch: got %d, want %d", CiphertextSize768, mlkem.CiphertextSize768)
+	}
+
+	if EncapsulationKeySize768 != mlkem.EncapsulationKeySize768 {
+		t.Errorf("EncapsulationKeySize768 mismatch: got %d, want %d", EncapsulationKeySize768, mlkem.EncapsulationKeySize768)
+	}
+
+	if CiphertextSize1024 != mlkem.CiphertextSize1024 {
+		t.Errorf("CiphertextSize1024 mismatch: got %d, want %d", CiphertextSize1024, mlkem.CiphertextSize1024)
+	}
+
+	if EncapsulationKeySize1024 != mlkem.EncapsulationKeySize1024 {
+		t.Errorf("EncapsulationKeySize1024 mismatch: got %d, want %d", EncapsulationKeySize1024, mlkem.EncapsulationKeySize1024)
+	}
+}