mlkem768

README

filippo.io/mlkem768

https://pkg.go.dev/filippo.io/mlkem768

Package mlkem768 implements the quantum-resistant key encapsulation method ML-KEM (formerly known as Kyber), as specified in NIST FIPS 203.

Only the recommended ML-KEM-768 parameter set is provided.

This package targets security, correctness, simplicity, readability, and reviewability as its primary goals. All critical operations are performed in constant time.

Variable and function names, as well as code layout, are selected to facilitate reviewing the implementation against the NIST FIPS 203 document.

Reviewers unfamiliar with polynomials or linear algebra might find the background at https://words.filippo.io/kyber-math/ useful.

This code is aimed at being upstreamed in the standard library.

Documentation

Overview

Package mlkem768 implements the quantum-resistant key encapsulation method ML-KEM (formerly known as Kyber), as specified in NIST FIPS 203.

Only the recommended ML-KEM-768 parameter set is provided.

Index

• Constants
• func Decapsulate(dk *DecapsulationKey, ciphertext []byte) (sharedKey []byte, err error)
• func Encapsulate(encapsulationKey []byte) (ciphertext, sharedKey []byte, err error)
• type DecapsulationKey
  • func GenerateKey() (*DecapsulationKey, error)
  • func NewKeyFromSeed(seed []byte) (*DecapsulationKey, error)
  • func (dk *DecapsulationKey) Bytes() []byte
  • func (dk *DecapsulationKey) EncapsulationKey() []byte

Constants

const (
	CiphertextSize       = k*encodingSize10 + encodingSize4
	EncapsulationKeySize = encryptionKeySize
	SharedKeySize        = 32
	SeedSize             = 32 + 32
)

Functions

func Decapsulate

func Decapsulate(dk *DecapsulationKey, ciphertext []byte) (sharedKey []byte, err error)

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 Encapsulate

func Encapsulate(encapsulationKey []byte) (ciphertext, sharedKey []byte, err error)

Encapsulate generates a shared key and an associated ciphertext from an encapsulation key, drawing random bytes from crypto/rand. If the encapsulation key is not valid, Encapsulate returns an error.

The shared key must be kept secret.

Types

type DecapsulationKey

type DecapsulationKey struct {
	// contains filtered or unexported fields
}

A DecapsulationKey is the secret key used to decapsulate a shared key from a ciphertext. It includes various precomputed values.

func GenerateKey

func GenerateKey() (*DecapsulationKey, error)

GenerateKey generates a new decapsulation key, drawing random bytes from crypto/rand. The decapsulation key must be kept secret.

func NewKeyFromSeed

func NewKeyFromSeed(seed []byte) (*DecapsulationKey, error)

NewKeyFromSeed deterministically generates a decapsulation key from a 64-byte seed in the "d || z" form. The seed must be uniformly random.

func (*DecapsulationKey) Bytes

func (dk *DecapsulationKey) Bytes() []byte

Bytes returns the decapsulation key as a 64-byte seed in the "d || z" form.

func (*DecapsulationKey) EncapsulationKey

func (dk *DecapsulationKey) EncapsulationKey() []byte

EncapsulationKey returns the public encapsulation key necessary to produce ciphertexts.