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 Scheme represents a specific instance of a signature scheme.
 42type Scheme interface {
 43	// Name of the scheme.
 44	Name() string
 45
 46	// GenerateKey creates a new key-pair.
 47	GenerateKey() (PublicKey, PrivateKey, error)
 48
 49	// Creates a signature using the PrivateKey on the given message and
 50	// returns the signature. opts are additional options which can be nil.
 51	//
 52	// Panics if key is nil or wrong type or opts context is not supported.
 53	Sign(sk PrivateKey, message []byte, opts *SignatureOpts) []byte
 54
 55	// Checks whether the given signature is a valid signature set by
 56	// the private key corresponding to the given public key on the
 57	// given message. opts are additional options which can be nil.
 58	//
 59	// Panics if key is nil or wrong type or opts context is not supported.
 60	Verify(pk PublicKey, message []byte, signature []byte, opts *SignatureOpts) bool
 61
 62	// Deterministically derives a keypair from a seed. If you're unsure,
 63	// you're better off using GenerateKey().
 64	//
 65	// Panics if seed is not of length SeedSize().
 66	DeriveKey(seed []byte) (PublicKey, PrivateKey)
 67
 68	// Unmarshals a PublicKey from the provided buffer.
 69	UnmarshalBinaryPublicKey([]byte) (PublicKey, error)
 70
 71	// Unmarshals a PublicKey from the provided buffer.
 72	UnmarshalBinaryPrivateKey([]byte) (PrivateKey, error)
 73
 74	// Size of binary marshalled public keys.
 75	PublicKeySize() int
 76
 77	// Size of binary marshalled public keys.
 78	PrivateKeySize() int
 79
 80	// Size of signatures.
 81	SignatureSize() int
 82
 83	// Size of seeds.
 84	SeedSize() int
 85
 86	// Returns whether contexts are supported.
 87	SupportsContext() bool
 88}
 89
 90var (
 91	// ErrTypeMismatch is the error used if types of, for instance, private
 92	// and public keys don't match.
 93	ErrTypeMismatch = errors.New("types mismatch")
 94
 95	// ErrSeedSize is the error used if the provided seed is of the wrong
 96	// size.
 97	ErrSeedSize = errors.New("wrong seed size")
 98
 99	// ErrPubKeySize is the error used if the provided public key is of
100	// the wrong size.
101	ErrPubKeySize = errors.New("wrong size for public key")
102
103	// ErrPrivKeySize is the error used if the provided private key is of
104	// the wrong size.
105	ErrPrivKeySize = errors.New("wrong size for private key")
106
107	// ErrContextNotSupported is the error used if a context is not
108	// supported.
109	ErrContextNotSupported = errors.New("context not supported")
110
111	// ErrContextTooLong is the error used if the context string is too long.
112	ErrContextTooLong = errors.New("context string too long")
113)