1// Package sign provides unified interfaces for signature schemes.
  2//
  3// A register of schemes is available in the package
  4//
  5//	github.com/cloudflare/circl/sign/schemes
  6package sign
  7
  8import (
  9	"crypto"
 10	"encoding"
 11	"errors"
 12)
 13
 14type SignatureOpts struct {
 15	// If non-empty, includes the given context in the signature if supported
 16	// and will cause an error during signing otherwise.
 17	Context string
 18}
 19
 20// A public key is used to verify a signature set by the corresponding private
 21// key.
 22type PublicKey interface {
 23	// Returns the signature scheme for this public key.
 24	Scheme() Scheme
 25	Equal(crypto.PublicKey) bool
 26	encoding.BinaryMarshaler
 27	crypto.PublicKey
 28}
 29
 30// A private key allows one to create signatures.
 31type PrivateKey interface {
 32	// Returns the signature scheme for this private key.
 33	Scheme() Scheme
 34	Equal(crypto.PrivateKey) bool
 35	// For compatibility with Go standard library
 36	crypto.Signer
 37	crypto.PrivateKey
 38	encoding.BinaryMarshaler
 39}
 40
 41// A private key that retains the seed with which it was generated.
 42type Seeded interface {
 43	// returns the seed if retained, otherwise nil
 44	Seed() []byte
 45}
 46
 47// A Scheme represents a specific instance of a signature scheme.
 48type Scheme interface {
 49	// Name of the scheme.
 50	Name() string
 51
 52	// GenerateKey creates a new key-pair.
 53	GenerateKey() (PublicKey, PrivateKey, error)
 54
 55	// Creates a signature using the PrivateKey on the given message and
 56	// returns the signature. opts are additional options which can be nil.
 57	//
 58	// Panics if key is nil or wrong type or opts context is not supported.
 59	Sign(sk PrivateKey, message []byte, opts *SignatureOpts) []byte
 60
 61	// Checks whether the given signature is a valid signature set by
 62	// the private key corresponding to the given public key on the
 63	// given message. opts are additional options which can be nil.
 64	//
 65	// Panics if key is nil or wrong type or opts context is not supported.
 66	Verify(pk PublicKey, message []byte, signature []byte, opts *SignatureOpts) bool
 67
 68	// Deterministically derives a keypair from a seed. If you're unsure,
 69	// you're better off using GenerateKey().
 70	//
 71	// Panics if seed is not of length SeedSize().
 72	DeriveKey(seed []byte) (PublicKey, PrivateKey)
 73
 74	// Unmarshals a PublicKey from the provided buffer.
 75	UnmarshalBinaryPublicKey([]byte) (PublicKey, error)
 76
 77	// Unmarshals a PublicKey from the provided buffer.
 78	UnmarshalBinaryPrivateKey([]byte) (PrivateKey, error)
 79
 80	// Size of binary marshalled public keys.
 81	PublicKeySize() int
 82
 83	// Size of binary marshalled public keys.
 84	PrivateKeySize() int
 85
 86	// Size of signatures.
 87	SignatureSize() int
 88
 89	// Size of seeds.
 90	SeedSize() int
 91
 92	// Returns whether contexts are supported.
 93	SupportsContext() bool
 94}
 95
 96var (
 97	// ErrTypeMismatch is the error used if types of, for instance, private
 98	// and public keys don't match.
 99	ErrTypeMismatch = errors.New("types mismatch")
100
101	// ErrSeedSize is the error used if the provided seed is of the wrong
102	// size.
103	ErrSeedSize = errors.New("wrong seed size")
104
105	// ErrPubKeySize is the error used if the provided public key is of
106	// the wrong size.
107	ErrPubKeySize = errors.New("wrong size for public key")
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	// ErrContextNotSupported is the error used if a context is not
114	// supported.
115	ErrContextNotSupported = errors.New("context not supported")
116
117	// ErrContextTooLong is the error used if the context string is too long.
118	ErrContextTooLong = errors.New("context string too long")
119)