Skip to content
Snippets Groups Projects
Commit f57a3a7c authored by Filippo Valsorda's avatar Filippo Valsorda Committed by Gopher Robot
Browse files

crypto/mlkem: add example and improve docs

Change-Id: I6a6a46565f9135d8f18bf219e5b76d5957df5ab0
Reviewed-on: https://go-review.googlesource.com/c/go/+/641295


LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: default avatarRuss Cox <rsc@golang.org>
Reviewed-by: default avatarDaniel McCarney <daniel@binaryparadox.net>
Auto-Submit: Filippo Valsorda <filippo@golang.org>
Reviewed-by: default avatarDmitri Shuralyov <dmitshur@google.com>
parent c9afcbad
Branches
Tags
No related merge requests found
// Copyright 2024 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_test
import (
"crypto/mlkem"
"log"
)
func Example() {
// Alice generates a new key pair and sends the encapsulation key to Bob.
dk, err := mlkem.GenerateKey768()
if err != nil {
log.Fatal(err)
}
encapsulationKey := dk.EncapsulationKey().Bytes()
// Bob uses the encapsulation key to encapsulate a shared secret, and sends
// back the ciphertext to Alice.
ciphertext := Bob(encapsulationKey)
// Alice decapsulates the shared secret from the ciphertext.
sharedSecret, err := dk.Decapsulate(ciphertext)
if err != nil {
log.Fatal(err)
}
// Alice and Bob now share a secret.
_ = sharedSecret
}
func Bob(encapsulationKey []byte) (ciphertext []byte) {
// Bob encapsulates a shared secret using the encapsulation key.
ek, err := mlkem.NewEncapsulationKey768(encapsulationKey)
if err != nil {
log.Fatal(err)
}
sharedSecret, ciphertext := ek.Encapsulate()
// Alice and Bob now share a secret.
_ = sharedSecret
// Bob sends the ciphertext to Alice.
return ciphertext
}
......@@ -7,12 +7,10 @@ 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 is the size of a ciphertext produced by ML-KEM-1024.
CiphertextSize1024 = 1568
// EncapsulationKeySize1024 is the size of an encapsulation key for the
// 1024-bit variant of ML-KEM.
// EncapsulationKeySize1024 is the size of an ML-KEM-1024 encapsulation key.
EncapsulationKeySize1024 = 1568
)
......@@ -23,7 +21,7 @@ type DecapsulationKey1024 struct {
}
// GenerateKey1024 generates a new decapsulation key, drawing random bytes from
// crypto/rand. The decapsulation key must be kept secret.
// the default crypto/rand source. The decapsulation key must be kept secret.
func GenerateKey1024() (*DecapsulationKey1024, error) {
key, err := mlkem.GenerateKey1024()
if err != nil {
......@@ -33,7 +31,7 @@ func GenerateKey1024() (*DecapsulationKey1024, error) {
return &DecapsulationKey1024{key}, nil
}
// NewDecapsulationKey1024 parses a decapsulation key from a 64-byte seed in the
// NewDecapsulationKey1024 expands 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)
......@@ -88,7 +86,7 @@ func (ek *EncapsulationKey1024) Bytes() []byte {
}
// Encapsulate generates a shared key and an associated ciphertext from an
// encapsulation key, drawing random bytes from crypto/rand.
// encapsulation key, drawing random bytes from the default crypto/rand source.
//
// The shared key must be kept secret.
func (ek *EncapsulationKey1024) Encapsulate() (sharedKey, ciphertext []byte) {
......
......@@ -5,6 +5,9 @@
// Package mlkem implements the quantum-resistant key encapsulation method
// ML-KEM (formerly known as Kyber), as specified in [NIST FIPS 203].
//
// Most applications should use the ML-KEM-768 parameter set, as implemented by
// [DecapsulationKey768] and [EncapsulationKey768].
//
// [NIST FIPS 203]: https://doi.org/10.6028/NIST.FIPS.203
package mlkem
......@@ -17,12 +20,10 @@ const (
// 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 is the size of a ciphertext produced by ML-KEM-768.
CiphertextSize768 = 1088
// EncapsulationKeySize768 is the size of an encapsulation key for the
// 768-bit variant of ML-KEM.
// EncapsulationKeySize768 is the size of an ML-KEM-768 encapsulation key.
EncapsulationKeySize768 = 1184
)
......@@ -33,7 +34,7 @@ type DecapsulationKey768 struct {
}
// GenerateKey768 generates a new decapsulation key, drawing random bytes from
// crypto/rand. The decapsulation key must be kept secret.
// the default crypto/rand source. The decapsulation key must be kept secret.
func GenerateKey768() (*DecapsulationKey768, error) {
key, err := mlkem.GenerateKey768()
if err != nil {
......@@ -43,7 +44,7 @@ func GenerateKey768() (*DecapsulationKey768, error) {
return &DecapsulationKey768{key}, nil
}
// NewDecapsulationKey768 parses a decapsulation key from a 64-byte seed in the
// NewDecapsulationKey768 expands 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)
......@@ -98,7 +99,7 @@ func (ek *EncapsulationKey768) Bytes() []byte {
}
// Encapsulate generates a shared key and an associated ciphertext from an
// encapsulation key, drawing random bytes from crypto/rand.
// encapsulation key, drawing random bytes from the default crypto/rand source.
//
// The shared key must be kept secret.
func (ek *EncapsulationKey768) Encapsulate() (sharedKey, ciphertext []byte) {
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment