sign.go raw

   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
   6  package sign
   7  
   8  import (
   9  	"crypto"
  10  	"encoding"
  11  	"errors"
  12  )
  13  
  14  type 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.
  22  type 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.
  31  type 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.
  42  type 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.
  48  type 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  
  96  var (
  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  )
 120