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 )
122