mlkem

README

mlkem

Go bindings to https://github.com/pq-code-package/mlkem-native

This project vendors https://github.com/pq-code-package/mlkem-native, whose license is a combination of Apache 2.0, ISC, and MIT. This project's license is regular Apache 2.0.

Purpose

This package is intended for R&D and testing purposes only. Users looking for a production-ready implementation of ML-KEM should use crypto/mlkem. Users looking for an easy way to get started experimenting with ML-KEM and creating test vectors for their protocols have come to the right place.

All three parameter sets of ML-KEM (ML-KEM-512, ML-KEM-768, ML-KEM-1024) are supported. Randomness is sourced as-needed by a caller-provided io.Reader. Derandomized keygen and encapsulation can be achieved using bytes.NewReader:

sk, err := MLKEM768.GenerateKeypair(bytes.NewReader(seed))
ss, ct, err := sk.PublicKey().Encapsulate(bytes.NewReader(randomness))

Getting Started

go get github.com/chrisfenner/mlkem

This package vendors https://github.com/pq-code-package/mlkem-native and wraps it with cgo. mlkem.go contains the main package API.

Documentation

Overview

Package mlkem provides Go bindings to the C implementation from https://github.com/pq-code-package/mlkem-native.

Index

• Variables
• type ParameterSet
  • func (parms ParameterSet) GenerateKeypair(rand io.Reader) (SecretKey, error)
  • func (parms ParameterSet) ImportPublicKey(pk []byte) (PublicKey, error)
  • func (parms ParameterSet) String() string
• type PublicKey
• type SecretKey

Variables

var (
	ErrBadParameterSet        = errors.New("invalid parameter set")
	ErrMalformedPublicKey     = errors.New("malformed public key")
	ErrMalformedCiphertext    = errors.New("malformed ciphertext")
	ErrInsufficientRandomness = errors.New("insufficient randomness")
)

Types

type ParameterSet

type ParameterSet int

const (
	MLKEM512 ParameterSet
	MLKEM768
	MLKEM1024
)

func (ParameterSet) GenerateKeypair

func (parms ParameterSet) GenerateKeypair(rand io.Reader) (SecretKey, error)

GenerateKeypair generates a keypair, reading the seed from rand.

func (ParameterSet) ImportPublicKey

func (parms ParameterSet) ImportPublicKey(pk []byte) (PublicKey, error)

ImportPublicKey imports the given public key.

func (ParameterSet) String

func (parms ParameterSet) String() string

String implements Stringer.

type PublicKey

type PublicKey interface {
	// ParameterSet returns the parameter set associated with this key.
	ParameterSet() ParameterSet
	// Encapsulate performs key encapsulation with the given public key, reading randomness from rand.
	Encapsulate(rand io.Reader) (secret []byte, ciphertext []byte, err error)
	// Bytes returns the public key in FIPS-203 format as a byte slice.
	Bytes() []byte
}

PublicKey represents an ML-KEM public key.

type SecretKey

type SecretKey interface {
	// ParameterSet returns the parameter set associated with this key.
	ParameterSet() ParameterSet
	// Decapsulate recovers the shared secret from the ciphertext.
	Decapsulate(ciphertext []byte) ([]byte, error)
	// PublicKey returns the public key associated with this key.
	PublicKey() PublicKey
	// Bytes returns the expanded secret key in FIPS-203 format as a byte slice.
	Bytes() []byte
	// Seed returns the secret seed as a byte slice.
	Seed() []byte
}

SecretKey represents an ML-KEM secret key.