doc(README): include MLKEM

README-EN.md

@@ -40,6 +40,8 @@ ShangMi (SM) cipher suites for Golang, referred to as **GMSM**, is a secure, hig
 
 - **DRBG** - Random Number Generation Using Deterministic Random Bit Generators, for detail, please reference **NIST Special Publication 800-90A** and **GM/T 0105-2021**: CTR-DRBG using derivation function and HASH-DRBG. NIST related implementations are tested with part of NIST provided test vectors. It's **NOT** concurrent safe! You can also use [randomness](https://github.com/Trisia/randomness) tool to check the generated random bits.
 
+- **MLKEM** - NIST FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism Standard.
+  
 - **MLDSA** - NIST FIPS 204 Module-Lattice-Based Digital Signature Standard.
 
 - **SLHDSA** - NIST FIPS 205 Stateless Hash-Based Digital Signature Standard

README.md

@@ -53,6 +53,8 @@ Go语言商用密码软件，简称**GMSM**，一个安全、高性能、易于
 
 - **DRBG** - 《GM/T 0105-2021软件随机数发生器设计指南》实现。本实现同时支持**NIST Special Publication 800-90A**（部分） 和 **GM/T 0105-2021**，NIST相关实现使用了NIST提供的测试数据进行测试。本实现**不支持并发使用**。
 
+- **MLKEM** - NIST FIPS 203  Module-Lattice-Based Key-Encapsulation Mechanism Standard实现，基于Golang标准库，支持所有三组参数集（ML-KEM-512/ML-KEM-768/ML-KEM-1024）。
+  
 - **MLDSA** - NIST FIPS 204 Module-Lattice-Based Digital Signature Standard实现。
 
 - **SLHDSA** - NIST FIPS 205 Stateless Hash-Based Digital Signature Standard实现。

mlkem/mlkem1024.go

@@ -21,7 +21,7 @@ type DecapsulationKey1024 struct {
 	d [32]byte // decapsulation key seed
 	z [32]byte // implicit rejection sampling seed
 
-	ρ [32]byte // sampleNTT seed for A, stored for the encapsulation key
+	ρ [32]byte // rho, sampleNTT seed for A, stored for the encapsulation key
 	h [32]byte // H(ek), stored for ML-KEM.Decaps_internal
 
 	encryptionKey1024
@@ -193,7 +193,7 @@ func kemKeyGen1024(dk *DecapsulationKey1024, d, z *[32]byte) {
 	g.Write(d[:])
 	g.Write([]byte{k1024}) // Module dimension as a domain separator.
 	G := g.Sum(make([]byte, 0, 64))
-	ρ, σ := G[:32], G[32:]
+	ρ, σ := G[:32], G[32:] // rho, sigma
 	dk.ρ = [32]byte(ρ)
 
 	A := &dk.a

mlkem/mlkem512.go

@@ -21,7 +21,7 @@ type DecapsulationKey512 struct {
 	d [32]byte // decapsulation key seed
 	z [32]byte // implicit rejection sampling seed
 
-	ρ [32]byte // sampleNTT seed for A, stored for the encapsulation key
+	ρ [32]byte // rho, sampleNTT seed for A, stored for the encapsulation key
 	h [32]byte // H(ek), stored for ML-KEM.Decaps_internal
 
 	encryptionKey512
@@ -193,7 +193,7 @@ func kemKeyGen512(dk *DecapsulationKey512, d, z *[32]byte) {
 	g.Write(d[:])
 	g.Write([]byte{k512}) // Module dimension as a domain separator.
 	G := g.Sum(make([]byte, 0, 64))
-	ρ, σ := G[:32], G[32:]
+	ρ, σ := G[:32], G[32:] // rho, sigma
 	dk.ρ = [32]byte(ρ)
 
 	A := &dk.a

mlkem/mlkem768.go

@@ -35,8 +35,8 @@ import (
 
 const (
 	// ML-KEM global constants.
-	n = 256
+	n                = 256
-	q = 3329
+	q                = 3329
 	maxBytesOf64Mulη = 192
 
 	// encodingSizeX is the byte size of a ringElement or nttElement encoded
@@ -56,9 +56,9 @@ const (
 
 // ML-KEM-768 parameters.
 const (
-	k = 3
+	k  = 3
-	η1 = 2
+	η1 = 2 // eta1
-	η2 = 2
+	η2 = 2 // eta2
 
 	CiphertextSize768       = k*encodingSize10 + encodingSize4
 	EncapsulationKeySize768 = k*encodingSize12 + 32
@@ -67,7 +67,7 @@ const (
 
 // ML-KEM-512 parameters.
 const (
-	k512 = 2
+	k512   = 2
 	η1_512 = 3
 	η2_512 = 2
 
@@ -78,7 +78,7 @@ const (
 
 // ML-KEM-1024 parameters.
 const (
-	k1024 = 4
+	k1024   = 4
 	η1_1024 = 2
 	η2_1024 = 2
 
@@ -93,7 +93,7 @@ type DecapsulationKey768 struct {
 	d [32]byte // decapsulation key seed
 	z [32]byte // implicit rejection sampling seed
 
-	ρ [32]byte // sampleNTT seed for A, stored for the encapsulation key
+	ρ [32]byte // rho, sampleNTT seed for A, stored for the encapsulation key
 	h [32]byte // H(ek), stored for ML-KEM.Decaps_internal
 
 	encryptionKey
@@ -265,7 +265,7 @@ func kemKeyGen(dk *DecapsulationKey768, d, z *[32]byte) {
 	g.Write(d[:])
 	g.Write([]byte{k}) // Module dimension as a domain separator.
 	G := g.Sum(make([]byte, 0, 64))
-	ρ, σ := G[:32], G[32:]
+	ρ, σ := G[:32], G[32:] // rho, sigma
 	dk.ρ = [32]byte(ρ)
 
 	A := &dk.a