github.com/cloudflare/circl@v1.5.0/kem/kem.go (about)

     1  // Package kem provides a unified interface for KEM schemes.
     2  //
     3  // A register of schemes is available in the package
     4  //
     5  //	github.com/cloudflare/circl/kem/schemes
     6  package kem
     7  
     8  import (
     9  	"encoding"
    10  	"errors"
    11  )
    12  
    13  // A KEM public key
    14  type PublicKey interface {
    15  	// Returns the scheme for this public key
    16  	Scheme() Scheme
    17  
    18  	encoding.BinaryMarshaler
    19  	Equal(PublicKey) bool
    20  }
    21  
    22  // A KEM private key
    23  type PrivateKey interface {
    24  	// Returns the scheme for this private key
    25  	Scheme() Scheme
    26  
    27  	encoding.BinaryMarshaler
    28  	Equal(PrivateKey) bool
    29  	Public() PublicKey
    30  }
    31  
    32  // A Scheme represents a specific instance of a KEM.
    33  type Scheme interface {
    34  	// Name of the scheme
    35  	Name() string
    36  
    37  	// GenerateKeyPair creates a new key pair.
    38  	GenerateKeyPair() (PublicKey, PrivateKey, error)
    39  
    40  	// Encapsulate generates a shared key ss for the public key and
    41  	// encapsulates it into a ciphertext ct.
    42  	Encapsulate(pk PublicKey) (ct, ss []byte, err error)
    43  
    44  	// Returns the shared key encapsulated in ciphertext ct for the
    45  	// private key sk.
    46  	Decapsulate(sk PrivateKey, ct []byte) ([]byte, error)
    47  
    48  	// Unmarshals a PublicKey from the provided buffer.
    49  	UnmarshalBinaryPublicKey([]byte) (PublicKey, error)
    50  
    51  	// Unmarshals a PrivateKey from the provided buffer.
    52  	UnmarshalBinaryPrivateKey([]byte) (PrivateKey, error)
    53  
    54  	// Size of encapsulated keys.
    55  	CiphertextSize() int
    56  
    57  	// Size of established shared keys.
    58  	SharedKeySize() int
    59  
    60  	// Size of packed private keys.
    61  	PrivateKeySize() int
    62  
    63  	// Size of packed public keys.
    64  	PublicKeySize() int
    65  
    66  	// DeriveKeyPair deterministically derives a pair of keys from a seed.
    67  	// Panics if the length of seed is not equal to the value returned by
    68  	// SeedSize.
    69  	DeriveKeyPair(seed []byte) (PublicKey, PrivateKey)
    70  
    71  	// Size of seed used in DeriveKey
    72  	SeedSize() int
    73  
    74  	// EncapsulateDeterministically generates a shared key ss for the public
    75  	// key deterministically from the given seed and encapsulates it into
    76  	// a ciphertext ct. If unsure, you're better off using Encapsulate().
    77  	EncapsulateDeterministically(pk PublicKey, seed []byte) (
    78  		ct, ss []byte, err error)
    79  
    80  	// Size of seed used in EncapsulateDeterministically().
    81  	EncapsulationSeedSize() int
    82  }
    83  
    84  // AuthScheme represents a KEM that supports authenticated key encapsulation.
    85  type AuthScheme interface {
    86  	Scheme
    87  	AuthEncapsulate(pkr PublicKey, sks PrivateKey) (ct, ss []byte, err error)
    88  	AuthEncapsulateDeterministically(pkr PublicKey, sks PrivateKey, seed []byte) (ct, ss []byte, err error)
    89  	AuthDecapsulate(skr PrivateKey, ct []byte, pks PublicKey) ([]byte, error)
    90  }
    91  
    92  var (
    93  	// ErrTypeMismatch is the error used if types of, for instance, private
    94  	// and public keys don't match
    95  	ErrTypeMismatch = errors.New("types mismatch")
    96  
    97  	// ErrSeedSize is the error used if the provided seed is of the wrong
    98  	// size.
    99  	ErrSeedSize = errors.New("wrong seed size")
   100  
   101  	// ErrPubKeySize is the error used if the provided public key is of
   102  	// the wrong size.
   103  	ErrPubKeySize = errors.New("wrong size for public key")
   104  
   105  	// ErrCiphertextSize is the error used if the provided ciphertext
   106  	// is of the wrong size.
   107  	ErrCiphertextSize = errors.New("wrong size for ciphertext")
   108  
   109  	// ErrPrivKeySize is the error used if the provided private key is of
   110  	// the wrong size.
   111  	ErrPrivKeySize = errors.New("wrong size for private key")
   112  
   113  	// ErrPubKey is the error used if the provided public key is invalid.
   114  	ErrPubKey = errors.New("invalid public key")
   115  
   116  	// ErrPrivKey is the error used if the provided private key is invalid.
   117  	ErrPrivKey = errors.New("invalid private key")
   118  
   119  	// ErrCipherText is the error used if the provided ciphertext is invalid.
   120  	ErrCipherText = errors.New("invalid ciphertext")
   121  )