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).

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

The version currently implemented is the one specified by NIST FIPS 203 ipd, with the unintentional transposition of the matrix A reverted to match the behavior of Kyber version 3.0. Future v0 versions of this package might introduce backwards incompatible changes to implement changes to FIPS 203.

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 ipd 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).

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

The version currently implemented is the one specified by NIST FIPS 203 ipd, with the unintentional transposition of the matrix A reverted to match the behavior of Kyber version 3.0. Future v0 versions of this package might introduce backwards incompatible changes to implement changes to FIPS 203.

Index

• Constants
• func Decapsulate(decapsulationKey, ciphertext []byte) (sharedKey []byte, err error)
• func Encapsulate(encapsulationKey []byte) (ciphertext, sharedKey []byte, err error)
• func EncapsulateFromSeed(encapsulationKey, seed []byte) (ciphertext, sharedKey []byte, err error)
• func GenerateKey() (encapsulationKey, decapsulationKey []byte, err error)
• func GenerateKeyFromSeed(seed []byte) (encapsulationKey, decapsulationKey []byte, err error)

Constants

const (
	CiphertextSize        = k*encodingSize10 + encodingSize4
	EncapsulationKeySize  = encryptionKeySize
	DecapsulationKeySize  = decryptionKeySize + encryptionKeySize + 32 + 32
	SharedKeySize         = 32
	KeySeedSize           = 32 * 2
	EncapsulationSeedSize = messageSize
)

Functions

func Decapsulate

func Decapsulate(decapsulationKey, ciphertext []byte) (sharedKey []byte, err error)

Decapsulate generates a shared key from a ciphertext and a decapsulation key. If the decapsulation key or the ciphertext are 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.

func EncapsulateFromSeed

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

EncapsulateFromSeed generates a shared key and an associated ciphertext from an encapsulation key, drawing random bytes from given seed. If the encapsulation key is not valid, Encapsulate returns an error.

The shared key must be kept secret.

func GenerateKey

func GenerateKey() (encapsulationKey, decapsulationKey []byte, err error)

GenerateKey generates an encapsulation key and a corresponding decapsulation key, drawing random bytes from crypto/rand.

The decapsulation key must be kept secret.

func GenerateKeyFromSeed

func GenerateKeyFromSeed(seed []byte) (encapsulationKey, decapsulationKey []byte, err error)

GenerateKeyFromSeed generates an encapsulation key and a corresponding decapsulation key, drawing random bytes from the given seed.