kem

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 4, 2026 License: AGPL-3.0 Imports: 5 Imported by: 0

Documentation

Overview

Package kem implements key encapsulation mechanisms (KEMs) for the Signal protocol. Kyber1024 (round-3, type byte 0x08) is the active KEM; the ML-KEM-1024 type byte (0x0A) is recognized for forward compatibility but is not yet enabled.

It is a pure-Go port of rust/protocol/src/kem.rs over github.com/cloudflare/circl. Serialization is wire-compatible with upstream libsignal: a key or ciphertext is one KeyType byte followed by the raw bytes circl produces (verified against upstream fixtures in TestUpstreamKeyFixtures).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BadKEMCiphertextLengthError 

type BadKEMCiphertextLengthError struct {
	KeyType KeyType
	Length  int
}

BadKEMCiphertextLengthError is returned when a serialized ciphertext has the wrong length for its key type.

func (BadKEMCiphertextLengthError) Error 

func (e BadKEMCiphertextLengthError) Error() string

type BadKEMKeyLengthError 

type BadKEMKeyLengthError struct {
	KeyType KeyType
	Length  int
}

BadKEMKeyLengthError is returned when a serialized key has the wrong length for its key type.

func (BadKEMKeyLengthError) Error 

func (e BadKEMKeyLengthError) Error() string

type BadKEMKeyTypeError 

type BadKEMKeyTypeError struct {
	Type byte
}

BadKEMKeyTypeError is returned for an unrecognized KEM key-type byte.

func (BadKEMKeyTypeError) Error 

func (e BadKEMKeyTypeError) Error() string

type ErrNoKeyTypeIdentifier 

type ErrNoKeyTypeIdentifier struct{}

ErrNoKeyTypeIdentifier is returned when deserializing from empty input that carries no KeyType byte.

func (ErrNoKeyTypeIdentifier) Error 

func (ErrNoKeyTypeIdentifier) Error() string

type KeyPair 

type KeyPair struct {
	PublicKey PublicKey
	SecretKey SecretKey
}

KeyPair is a KEM public/secret key pair.

func GenerateKeyPair 

func GenerateKeyPair(keyType KeyType, rng io.Reader) (KeyPair, error)

GenerateKeyPair generates a new key pair for the given KEM type, drawing seed entropy from rng. rng must be a cryptographically secure source.

func KeyPairFromPublicAndSecret 

func KeyPairFromPublicAndSecret(publicKey, secretKey []byte) (KeyPair, error)

KeyPairFromPublicAndSecret deserializes a key pair from the wire forms of a public and secret key, requiring matching key types.

func NewKeyPair 

func NewKeyPair(publicKey PublicKey, secretKey SecretKey) (KeyPair, error)

NewKeyPair pairs a public and secret key. It returns an error if their key types differ.

type KeyType 

type KeyType uint8

KeyType identifies a supported KEM protocol by its one-byte wire tag. 

const (
	// KeyTypeKyber1024 is round-3 Kyber1024; its serialized type byte is 0x08.
	KeyTypeKyber1024 KeyType = 0x08
	// KeyTypeMLKEM1024 is ML-KEM-1024 (FIPS 203); its type byte 0x0A is
	// recognized on the wire but not currently enabled.
	KeyTypeMLKEM1024 KeyType = 0x0A
)

func (KeyType) String 

func (k KeyType) String() string

String implements fmt.Stringer.

type PublicKey 

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

PublicKey is a KEM public key, able to encapsulate a shared secret.

func DeserializePublicKey 

func DeserializePublicKey(value []byte) (PublicKey, error)

DeserializePublicKey parses the wire form of a public key, validating the KeyType byte and the body length for that type.

func (PublicKey) Encapsulate 

func (p PublicKey) Encapsulate() (sharedSecret, ciphertext []byte, err error)

Encapsulate produces a fresh shared secret and a serialized ciphertext for the recipient holding the matching secret key. Randomness is drawn from the underlying KEM's cryptographically secure source.

func (PublicKey) Equal 

func (p PublicKey) Equal(other PublicKey) bool

Equal reports whether two public keys are equal, comparing the key body in constant time once the key types match.

func (PublicKey) KeyType 

func (p PublicKey) KeyType() KeyType

KeyType reports the KEM protocol of the public key.

func (PublicKey) Serialize 

func (p PublicKey) Serialize() []byte

Serialize returns the wire form of the public key: the KeyType byte followed by the raw key.

func (PublicKey) String 

func (p PublicKey) String() string

String implements fmt.Stringer for the public key, reporting only the key type and length (the public key body is not secret, but we keep the Debug form compact and consistent with the secret key, mirroring upstream).

type SecretKey 

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

SecretKey is a KEM secret key, able to decapsulate a shared secret.

func DeserializeSecretKey 

func DeserializeSecretKey(value []byte) (SecretKey, error)

DeserializeSecretKey parses the wire form of a secret key, validating the KeyType byte and the body length for that type.

func (SecretKey) Decapsulate 

func (s SecretKey) Decapsulate(ciphertext []byte) ([]byte, error)

Decapsulate recovers the shared secret from a serialized ciphertext. The ciphertext's key type must match this secret key's type.

func (SecretKey) Format 

func (s SecretKey) Format(f fmt.State, _ rune)

Format implements fmt.Formatter for the secret key, redacting under every verb.

func (SecretKey) KeyType 

func (s SecretKey) KeyType() KeyType

KeyType reports the KEM protocol of the secret key.

func (SecretKey) Serialize 

func (s SecretKey) Serialize() []byte

Serialize returns the wire form of the secret key: the KeyType byte followed by the raw key.

func (SecretKey) String 

func (s SecretKey) String() string

String implements fmt.Stringer for the secret key, redacting the key body so secret material never leaks into logs.

type UnsupportedKEMKeyTypeError 

type UnsupportedKEMKeyTypeError struct {
	Type byte
}

UnsupportedKEMKeyTypeError is returned for a key type that is recognized on the wire but not currently enabled (ML-KEM-1024).

func (UnsupportedKEMKeyTypeError) Error 

func (e UnsupportedKEMKeyTypeError) Error() string

type WrongKEMKeyTypeError 

type WrongKEMKeyTypeError struct {
	Got      byte
	Expected byte
}

WrongKEMKeyTypeError is returned when a ciphertext's key type does not match the secret key used to decapsulate it.

func (WrongKEMKeyTypeError) Error 

func (e WrongKEMKeyTypeError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.