package kem

import "github.com/cloudflare/circl/kem"

Package kem provides a unified interface for KEM schemes.

A register of schemes is available in the package

github.com/cloudflare/circl/kem/schemes

Index

Variables

var (
	// ErrTypeMismatch is the error used if types of, for instance, private
	// and public keys don't match
	ErrTypeMismatch = errors.New("types mismatch")

	// ErrSeedSize is the error used if the provided seed is of the wrong
	// size.
	ErrSeedSize = errors.New("wrong seed size")

	// ErrPubKeySize is the error used if the provided public key is of
	// the wrong size.
	ErrPubKeySize = errors.New("wrong size for public key")

	// ErrCiphertextSize is the error used if the provided ciphertext
	// is of the wrong size.
	ErrCiphertextSize = errors.New("wrong size for ciphertext")

	// ErrPrivKeySize is the error used if the provided private key is of
	// the wrong size.
	ErrPrivKeySize = errors.New("wrong size for private key")

	// ErrPubKey is the error used if the provided public key is invalid.
	ErrPubKey = errors.New("invalid public key")

	// ErrPrivKey is the error used if the provided private key is invalid.
	ErrPrivKey = errors.New("invalid private key")

	// ErrCipherText is the error used if the provided ciphertext is invalid.
	ErrCipherText = errors.New("invalid ciphertext")
)

Types

type AuthScheme

type AuthScheme interface {
	Scheme
	AuthEncapsulate(pkr PublicKey, sks PrivateKey) (ct, ss []byte, err error)
	AuthEncapsulateDeterministically(pkr PublicKey, sks PrivateKey, seed []byte) (ct, ss []byte, err error)
	AuthDecapsulate(skr PrivateKey, ct []byte, pks PublicKey) ([]byte, error)
}

AuthScheme represents a KEM that supports authenticated key encapsulation.

type PrivateKey

type PrivateKey interface {
	// Returns the scheme for this private key
	Scheme() Scheme

	encoding.BinaryMarshaler
	Equal(PrivateKey) bool
	Public() PublicKey
}

A KEM private key

type PublicKey

type PublicKey interface {
	// Returns the scheme for this public key
	Scheme() Scheme

	encoding.BinaryMarshaler
	Equal(PublicKey) bool
}

A KEM public key

type Scheme

type Scheme interface {
	// Name of the scheme
	Name() string

	// GenerateKeyPair creates a new key pair.
	GenerateKeyPair() (PublicKey, PrivateKey, error)

	// Encapsulate generates a shared key ss for the public key and
	// encapsulates it into a ciphertext ct.
	Encapsulate(pk PublicKey) (ct, ss []byte, err error)

	// Returns the shared key encapsulated in ciphertext ct for the
	// private key sk.
	Decapsulate(sk PrivateKey, ct []byte) ([]byte, error)

	// Unmarshals a PublicKey from the provided buffer.
	UnmarshalBinaryPublicKey([]byte) (PublicKey, error)

	// Unmarshals a PrivateKey from the provided buffer.
	UnmarshalBinaryPrivateKey([]byte) (PrivateKey, error)

	// Size of encapsulated keys.
	CiphertextSize() int

	// Size of established shared keys.
	SharedKeySize() int

	// Size of packed private keys.
	PrivateKeySize() int

	// Size of packed public keys.
	PublicKeySize() int

	// DeriveKeyPair deterministically derives a pair of keys from a seed.
	// Panics if the length of seed is not equal to the value returned by
	// SeedSize.
	DeriveKeyPair(seed []byte) (PublicKey, PrivateKey)

	// Size of seed used in DeriveKey
	SeedSize() int

	// EncapsulateDeterministically generates a shared key ss for the public
	// key deterministically from the given seed and encapsulates it into
	// a ciphertext ct. If unsure, you're better off using Encapsulate().
	EncapsulateDeterministically(pk PublicKey, seed []byte) (
		ct, ss []byte, err error)

	// Size of seed used in EncapsulateDeterministically().
	EncapsulationSeedSize() int
}

A Scheme represents a specific instance of a KEM.

Source Files

kem.go

Directories

PathSynopsis
kem/frodoPackage frodo provides the key encapsulation mechanism FrodoKEM.
kem/frodo/frodo640shakePackage frodo640shake implements the variant FrodoKEM-640 with SHAKE.
kem/hybridPackage hybrid defines several hybrid classical/quantum KEMs for use in TLS.
kem/kyberPackage kyber implements the CRYSTALS-Kyber.CCAKEM IND-CCA2 secure key encapsulation mechanism (KEM) as submitted to round 3 of the NIST PQC competition and described in
kem/kyber/kyber1024Package kyber1024 implements the IND-CCA2 secure key encapsulation mechanism Kyber1024.CCAKEM as submitted to round 3 of the NIST PQC competition and described in
kem/kyber/kyber512Package kyber512 implements the IND-CCA2 secure key encapsulation mechanism Kyber512.CCAKEM as submitted to round 3 of the NIST PQC competition and described in
kem/kyber/kyber768Package kyber768 implements the IND-CCA2 secure key encapsulation mechanism Kyber768.CCAKEM as submitted to round 3 of the NIST PQC competition and described in
kem/mlkemPackage mlkem implements IND-CCA2 secure ML-KEM key encapsulation mechanism (KEM) as defined in FIPS 203.
kem/mlkem/mlkem1024Package mlkem1024 implements the IND-CCA2 secure key encapsulation mechanism ML-KEM-1024 as defined in FIPS203.
kem/mlkem/mlkem512Package mlkem512 implements the IND-CCA2 secure key encapsulation mechanism ML-KEM-512 as defined in FIPS203.
kem/mlkem/mlkem768Package mlkem768 implements the IND-CCA2 secure key encapsulation mechanism ML-KEM-768 as defined in FIPS203.
kem/schemesPackage schemes contains a register of KEM schemes.
kem/sikePackage sike is deprecated, it contains the SIKE key encapsulation mechanism.
kem/sike/sikep434Package sikep434 is deprecated, it implements the key encapsulation mechanism SIKEp434.
kem/sike/sikep503Package sikep503 is deprecated, it implements the key encapsulation mechanism SIKEp503.
kem/sike/sikep751Package sikep751 is deprecated, it implements the key encapsulation mechanism SIKEp751.
kem/xwingPackage xwing implements the X-Wing PQ/T hybrid KEM
Version
v1.6.1 (latest)
Published
Apr 9, 2025
Platform
linux/amd64
Imports
2 packages
Last checked
1 day ago

Tools for package owners.