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

     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 Scheme represents a specific instance of a signature scheme.
    42  type 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  
    90  var (
    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  )