package xwing

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

Package xwing implements the X-Wing PQ/T hybrid KEM

https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem

Implements the final version (-05).

Index ¶

• Constants
• Variables
• func Decapsulate(ct, sk []byte) (ss []byte)
• func DeriveKeyPair(seed []byte) (*PrivateKey, *PublicKey)
• func DeriveKeyPairPacked(seed []byte) ([]byte, []byte)
• func Encapsulate(pk, seed []byte) (ss, ct []byte, err error)
• func GenerateKeyPair(rand io.Reader) (*PrivateKey, *PublicKey, error)
• func GenerateKeyPairPacked(rand io.Reader) ([]byte, []byte, error)
• func Scheme() kem.Scheme
• type PrivateKey
• func (sk *PrivateKey) DecapsulateTo(ss, ct []byte)
• func (sk *PrivateKey) Equal(other kem.PrivateKey) bool
• func (sk *PrivateKey) MarshalBinary() ([]byte, error)
• func (sk *PrivateKey) Pack(buf []byte)
• func (sk *PrivateKey) Public() kem.PublicKey
• func (*PrivateKey) Scheme() kem.Scheme
• func (sk *PrivateKey) Unpack(buf []byte)
• type PublicKey
• func (pk *PublicKey) EncapsulateTo(ct, ss, seed []byte)
• func (pk *PublicKey) Equal(other kem.PublicKey) bool
• func (pk *PublicKey) MarshalBinary() ([]byte, error)
• func (pk *PublicKey) Pack(buf []byte)
• func (*PublicKey) Scheme() kem.Scheme
• func (pk *PublicKey) Unpack(buf []byte) error

Constants ¶

const (
	// Size of a seed of a keypair
	SeedSize = 32

	// Size of an X-Wing public key
	PublicKeySize = 1216

	// Size of an X-Wing private key
	PrivateKeySize = 32

	// Size of the seed passed to EncapsulateTo
	EncapsulationSeedSize = 64

	// Size of the established shared key
	SharedKeySize = 32

	// Size of an X-Wing ciphertext.
	CiphertextSize = 1120
)

Variables ¶

var ErrSharedKeySize = errors.New("wrong size for shared key")

Raised when passing a byte slice of the wrong size for the shared secret to the EncapsulateTo or DecapsulateTo functions.

Functions ¶

func Decapsulate ¶

func Decapsulate(ct, sk []byte) (ss []byte)

Decapsulate computes the shared key which is encapsulated in ct for the private key sk.

Panics if sk or ct are not of length PrivateKeySize and CiphertextSize respectively.

func DeriveKeyPair ¶

func DeriveKeyPair(seed []byte) (*PrivateKey, *PublicKey)

DeriveKeyPair derives a public/private keypair deterministically from the given seed.

Panics if seed is not of length SeedSize.

func DeriveKeyPairPacked ¶

func DeriveKeyPairPacked(seed []byte) ([]byte, []byte)

DeriveKeyPairPacked derives a keypair like DeriveKeyPair, and returns them packed.

func Encapsulate ¶

func Encapsulate(pk, seed []byte) (ss, ct []byte, err error)

Encapsulate generates a shared key and ciphertext that contains it for the public key pk using randomness from seed.

seed may be nil, in which case crypto/rand.Reader is used.

Warning: note that the order of the returned ss and ct matches the X-Wing standard, which is the reverse of the Circl KEM API.

Returns ErrPubKey if ML-KEM encapsulation key check fails.

Panics if pk is not of size PublicKeySize, or randomness could not be read from crypto/rand.Reader.

func GenerateKeyPair ¶

func GenerateKeyPair(rand io.Reader) (*PrivateKey, *PublicKey, error)

GenerateKeyPair generates public and private keys using entropy from rand. If rand is nil, crypto/rand.Reader will be used.

func GenerateKeyPairPacked ¶

func GenerateKeyPairPacked(rand io.Reader) ([]byte, []byte, error)

GenerateKeyPairPacked generates a keypair like GenerateKeyPair, and returns them packed.

func Scheme ¶

func Scheme() kem.Scheme

Returns the generic KEM interface for X-Wing PQ/T hybrid KEM.

Types ¶

type PrivateKey ¶

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

An X-Wing private key.

func (*PrivateKey) DecapsulateTo ¶

func (sk *PrivateKey) DecapsulateTo(ss, ct []byte)

DecapsulateTo computes the shared key which is encapsulated in ct for the private key.

Panics if ct or ss are not of length CiphertextSize and SharedKeySize respectively.

func (*PrivateKey) Equal ¶

func (sk *PrivateKey) Equal(other kem.PrivateKey) bool

func (*PrivateKey) MarshalBinary ¶

func (sk *PrivateKey) MarshalBinary() ([]byte, error)

func (*PrivateKey) Pack ¶

func (sk *PrivateKey) Pack(buf []byte)

Packs sk to buf.

Panics if buf is not of size PrivateKeySize

func (*PrivateKey) Public ¶

func (sk *PrivateKey) Public() kem.PublicKey

func (*PrivateKey) Scheme ¶

func (*PrivateKey) Scheme() kem.Scheme

func (*PrivateKey) Unpack ¶

func (sk *PrivateKey) Unpack(buf []byte)

Unpacks sk from buf.

Panics if buf is not of size PrivateKeySize.

type PublicKey ¶

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

An X-Wing public key.

func (*PublicKey) EncapsulateTo ¶

func (pk *PublicKey) EncapsulateTo(ct, ss, seed []byte)

EncapsulateTo generates a shared key and ciphertext that contains it for the public key using randomness from seed and writes the shared key to ss and ciphertext to ct.

Panics if ss, ct or seed are not of length SharedKeySize, CiphertextSize and EncapsulationSeedSize respectively.

seed may be nil, in which case crypto/rand.Reader is used to generate one.

func (*PublicKey) Equal ¶

func (pk *PublicKey) Equal(other kem.PublicKey) bool

func (*PublicKey) MarshalBinary ¶

func (pk *PublicKey) MarshalBinary() ([]byte, error)

func (*PublicKey) Pack ¶

func (pk *PublicKey) Pack(buf []byte)

Packs pk to buf.

Panics if buf is not of size PublicKeySize.

func (*PublicKey) Scheme ¶

func (*PublicKey) Scheme() kem.Scheme

func (*PublicKey) Unpack ¶

func (pk *PublicKey) Unpack(buf []byte) error

Unpacks pk from buf.

Panics if buf is not of size PublicKeySize.

Returns ErrPubKey if pk fails the ML-KEM encapsulation key check.

Source Files ¶

scheme.go xwing.go