Add ML-KEM (FIPS 203).

We keep Kyber around (for now) as it's currently widely deployed.
Code differences between them are minimal anyway.

Tests against NIST's ACVP test vectors.

README.md

@@ -82,6 +82,7 @@ Alternatively, look at the [Cloudflare Go](https://github.com/cloudflare/go/tree
 |:---:|
 
  - [CSIDH](./dh/csidh): Post-Quantum Commutative Group Action ([CSIDH](https://csidh.isogeny.org/)).
+ - [ML-KEM](./kem/mlkem): modes 512, 768, 1024 ([ML-KEM](https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.203.pdf)).
  - [Kyber KEM](./kem/kyber): modes 512, 768, 1024 ([KYBER](https://pq-crystals.org/kyber/)).
  - [FrodoKEM](./kem/frodo): modes 640-SHAKE. ([FrodoKEM](https://frodokem.org/))
  - (**insecure, deprecated**) ~~[SIDH/SIKE](./kem/sike)~~: Supersingular Key Encapsulation with primes p434, p503, p751 ([SIKE](https://sike.org/)).

kem/kyber/gen.go

@@ -7,8 +7,10 @@ package main
 
 import (
 	"bytes"
+	"fmt"
 	"go/format"
 	"io/ioutil"
+	"path"
 	"strings"
 	"text/template"
 )
@@ -17,15 +19,43 @@ type Instance struct {
 	Name string
 }
 
+func (m Instance) KemName() string {
+	if m.NIST() {
+		return m.Name
+	}
+	return m.Name + ".CCAKEM"
+}
+
+func (m Instance) NIST() bool {
+	return strings.HasPrefix(m.Name, "ML-KEM")
+}
+
+func (m Instance) PkePkg() string {
+	if !m.NIST() {
+		return m.Pkg()
+	}
+	return strings.ReplaceAll(m.Pkg(), "mlkem", "kyber")
+}
+
 func (m Instance) Pkg() string {
-	return strings.ToLower(m.Name)
+	return strings.ToLower(strings.ReplaceAll(m.Name, "-", ""))
+}
+
+func (m Instance) PkgPath() string {
+	if m.NIST() {
+		return path.Join("..", "mlkem", m.Pkg())
+	}
+	return m.Pkg()
 }
 
 var (
 	Instances = []Instance{
 		{Name: "Kyber512"},
 		{Name: "Kyber768"},
 		{Name: "Kyber1024"},
+		{Name: "ML-KEM-512"},
+		{Name: "ML-KEM-768"},
+		{Name: "ML-KEM-1024"},
 	}
 	TemplateWarning = "// Code generated from"
 )
@@ -51,15 +81,15 @@ func generatePackageFiles() {
 		// Formating output code
 		code, err := format.Source(buf.Bytes())
 		if err != nil {
-			panic("error formating code")
+			panic(fmt.Sprintf("error formating code: %v", err))
 		}
 
 		res := string(code)
 		offset := strings.Index(res, TemplateWarning)
 		if offset == -1 {
 			panic("Missing template warning in pkg.templ.go")
 		}
-		err = ioutil.WriteFile(mode.Pkg()+"/kyber.go", []byte(res[offset:]), 0o644)
+		err = ioutil.WriteFile(mode.PkgPath()+"/kyber.go", []byte(res[offset:]), 0o644)
 		if err != nil {
 			panic(err)
 		}

kem/kyber/kat_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"crypto/sha256"
 	"fmt"
+	"strings"
 	"testing"
 
 	"github.com/cloudflare/circl/internal/nist"
@@ -22,6 +23,12 @@ func TestPQCgenKATKem(t *testing.T) {
 		{"Kyber1024", "89248f2f33f7f4f7051729111f3049c409a933ec904aedadf035f30fa5646cd5"},
 		{"Kyber768", "a1e122cad3c24bc51622e4c242d8b8acbcd3f618fee4220400605ca8f9ea02c2"},
 		{"Kyber512", "e9c2bd37133fcb40772f81559f14b1f58dccd1c816701be9ba6214d43baf4547"},
+
+		// TODO crossreference with standard branch of reference implementation
+		// 		once they've added the final change: domain separation in K-PKE.KeyGen().
+		{"ML-KEM-512", "a30184edee53b3b009356e1e31d7f9e93ce82550e3c622d7192e387b0cc84f2e"},
+		{"ML-KEM-768", "729367b590637f4a93c68d5e4a4d2e2b4454842a52c9eec503e3a0d24cb66471"},
+		{"ML-KEM-1024", "3fba7327d0320cb6134badf2a1bcb963a5b3c0026c7dece8f00d6a6155e47b33"},
 	}
 	for _, kat := range kats {
 		kat := kat
@@ -45,18 +52,26 @@ func testPQCgenKATKem(t *testing.T, name, expected string) {
 	}
 	f := sha256.New()
 	g := nist.NewDRBG(&seed)
-	fmt.Fprintf(f, "# %s\n\n", name)
+
+	// The "standard" branch reference implementation still uses Kyber
+	// as name instead of ML-KEM.
+	fmt.Fprintf(f, "# %s\n\n", strings.ReplaceAll(name, "ML-KEM-", "Kyber"))
 	for i := 0; i < 100; i++ {
 		g.Fill(seed[:])
 		fmt.Fprintf(f, "count = %d\n", i)
 		fmt.Fprintf(f, "seed = %X\n", seed)
 		g2 := nist.NewDRBG(&seed)
 
-		// This is not equivalent to g2.Fill(kseed[:]).  As the reference
-		// implementation calls randombytes twice generating the keypair,
-		// we have to do that as well.
-		g2.Fill(kseed[:32])
-		g2.Fill(kseed[32:])
+		if strings.HasPrefix(name, "ML-KEM") {
+			// https://github.com/pq-crystals/kyber/commit/830e0ba1a7fdba6cde03f8139b0d41ad2102b860
+			g2.Fill(kseed[:])
+		} else {
+			// This is not equivalent to g2.Fill(kseed[:]).  As the reference
+			// implementation calls randombytes twice generating the keypair,
+			// we have to do that as well.
+			g2.Fill(kseed[:32])
+			g2.Fill(kseed[32:])
+		}
 
 		g2.Fill(eseed)
 		pk, sk := scheme.DeriveKeyPair(kseed)
@@ -73,6 +88,6 @@ func testPQCgenKATKem(t *testing.T, name, expected string) {
 		fmt.Fprintf(f, "ss = %X\n\n", ss)
 	}
 	if fmt.Sprintf("%x", f.Sum(nil)) != expected {
-		t.Fatal()
+		t.Fatalf("%s %x %s", name, f.Sum(nil), expected)
 	}
 }