cloudflared-mirror/vendor/github.com/cloudflare/circl/kem/kem.go

119 lines
3.4 KiB
Go
Raw Normal View History

// Package kem provides a unified interface for KEM schemes.
//
// A register of schemes is available in the package
//
// github.com/cloudflare/circl/kem/schemes
package kem
import (
"encoding"
"errors"
)
// A KEM public key
type PublicKey interface {
// Returns the scheme for this public key
Scheme() Scheme
encoding.BinaryMarshaler
Equal(PublicKey) bool
}
// A KEM private key
type PrivateKey interface {
// Returns the scheme for this private key
Scheme() Scheme
encoding.BinaryMarshaler
Equal(PrivateKey) bool
Public() PublicKey
}
// A Scheme represents a specific instance of a KEM.
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 deterministicallly 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
}
// AuthScheme represents a KEM that supports authenticated key encapsulation.
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)
}
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")
// ErrCipherText is the error used if the provided ciphertext is invalid.
ErrCipherText = errors.New("invalid ciphertext")
)