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 code was upstreamed in the standard library in Go 1.24, and as of Go 1.26 it is just a wrapper for the crypto/mlkem and crypto/mlkem/mlkemtest packages.

filippo.io/mlkem768/xwing

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

The xwing package implements the hybrid quantum-resistant key encapsulation method X-Wing, which combines X25519, ML-KEM-768, and SHA3-256 as specified in draft-connolly-cfrg-xwing-kem.

Most users will probably be better served by the hybrid KEMs in the crypto/hpke package.

Documentation

Index

• Constants
• func Decapsulate(dk *DecapsulationKey, ciphertext []byte) (sharedKey []byte, err error)
• func Encapsulate(encapsulationKey []byte) (ciphertext, sharedKey []byte, err error)
• func EncapsulateDerand(encapsulationKey, randomness []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.

func EncapsulateDerand

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

EncapsulateDerand works like Encapsulate but accepts the random bytes as an input. It should only be used for testing.

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.