signature

package
v0.2403.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2024 License: Apache-2.0 Imports: 24 Imported by: 88

Documentation

Overview

Package signature provides wrapper types around public key signatures.

Index

Constants

View Source 
const (
	// PublicKeySize is the size of a public key in bytes.
	PublicKeySize = ed25519.PublicKeySize

	// SignatureSize is the size of a signature in bytes.
	SignatureSize = ed25519.SignatureSize
)
View Source 
const (
	SignerUnknown   SignerRole = 0
	SignerEntity    SignerRole = 1
	SignerNode      SignerRole = 2
	SignerP2P       SignerRole = 3
	SignerConsensus SignerRole = 4
	SignerVRF       SignerRole = 5

	SignerEntityName    = "entity"
	SignerNodeName      = "node"
	SignerP2PName       = "p2p"
	SignerConsensusName = "consensus"
	SignerVRFName       = "vrf"
)
View Source 
const (
	// ProofSize is the size of a VRF proof in bytes.
	ProofSize = ecvrf.ProofSize

	// BetaSize is the size of a VRF output in bytes.
	BetaSize = ecvrf.OutputSize
)

Variables

View Source 
var (
	// ErrMalformedPublicKey is the error returned when a public key is
	// malformed.
	ErrMalformedPublicKey = errors.New("signature: malformed public key")

	// ErrMalformedSignature is the error returned when a signature is
	// malformed.
	ErrMalformedSignature = errors.New("signature: malformed signature")

	// ErrPublicKeyMismatch is the error returned when a signature was
	// not produced by the expected public key.
	ErrPublicKeyMismatch = errors.New("signature: public key mismatch")

	// ErrVerifyFailed is the error return when a signature verification
	// fails when opening a signed blob.
	ErrVerifyFailed = errors.New("signed: signature verification failed")

	// ErrForbiddenPublicKey is the error returned when a public key is
	// in the blacklist.
	ErrForbiddenPublicKey = errors.New("signature: public key forbidden")
)
View Source 
var (
	// ErrNotExist is the error returned when a private key does not exist.
	ErrNotExist = os.ErrNotExist

	// ErrMalformedPrivateKey is the error returned when a private key is
	// malformed.
	ErrMalformedPrivateKey = errors.New("signature: malformed private key")

	// ErrRoleMismatch is the error returned when the signer factory role
	// is misconfigured.
	ErrRoleMismatch = errors.New("signature: signer factory role mismatch")

	// ErrRoleAction is the error returned when the signer role mismatches
	// the signing operations allowed by the role.
	ErrRoleAction = errors.New("signature: signer role action mismatch")

	// ErrInvalidRole is the error returned when the signer role is invalid.
	ErrInvalidRole = errors.New("signature: invalid signer role")

	// ErrVRFNotSupported is the error returned when the signer is not capable
	// of generating VRF proofs.
	ErrVRFNotSupported = errors.New("signature: VRF proofs not supported")

	// SignerRoles is the list of all supported signer roles.
	SignerRoles = []SignerRole{
		SignerEntity,
		SignerNode,
		SignerP2P,
		SignerConsensus,
		SignerVRF,
	}
)

Functions

func BuildPublicKeyBlacklist 

func BuildPublicKeyBlacklist(allowTestKeys bool)

BuildPublicKeyBlacklist builds the public key blacklist.

func IsUnsafeUnregisteredContextsAllowed 

func IsUnsafeUnregisteredContextsAllowed() bool

IsUnsafeUnregisteredContextsAllowed returns true iff context registration checks are bypassed.

func PrepareSignerContext 

func PrepareSignerContext(context Context) ([]byte, error)

PrepareSignerContext prepares a context for use during signing by a Signer.

func PrepareSignerMessage 

func PrepareSignerMessage(context Context, message []byte) ([]byte, error)

PrepareSignerMessage prepares a context and message for signing by a Signer.

func RegisterTestPublicKey 

func RegisterTestPublicKey(pk PublicKey)

RegisterTestPublicKey registers a hardcoded test public key with the internal public key blacklist.

func SetChainContext 

func SetChainContext(rawContext string)

SetChainContext configures the chain domain separation context that is used with any contexts constructed using the WithChainSeparation option.

func UnsafeAllowUnregisteredContexts 

func UnsafeAllowUnregisteredContexts()

UnsafeAllowUnregisteredContexts bypasses the context registration check.

This function is only for the benefit of implementing a remote signer.

func UnsafeResetChainContext 

func UnsafeResetChainContext()

UnsafeResetChainContext resets the chain context.

This function should NOT be used during normal operation as changing the chain context while an application is running is unsafe. The main use case for having this function is unit tests.

func VerifyManyToOne 

func VerifyManyToOne(context Context, message []byte, sigs []Signature) bool

VerifyManyToOne verifies multiple signatures against a single context and message, returning true iff every signature is valid.

Types

type BatchVerifier added in v0.2200.3 

type BatchVerifier struct {
	// contains filtered or unexported fields
}

BatchVerifier accumulates batch entries with Add, before performing batch verification with Verify.

func NewBatchVerifier added in v0.2200.3 

func NewBatchVerifier() *BatchVerifier

NewBatchVerifier creates an empty BatchVerifier.

func NewBatchVerifierWithCapacity added in v0.2200.3 

func NewBatchVerifierWithCapacity(n int) *BatchVerifier

NewBatchVerifierWithCapacity creates an empty BatchVerifier, with preallocations for a pre-determined batch size hint.

func (*BatchVerifier) Add added in v0.2200.3 

func (v *BatchVerifier) Add(
	publicKey PublicKey,
	context Context,
	message []byte,
	sig []byte,
)

Add adds a (public key, context, message, signature) quad to the current batch.

Note: Errors detected while preparing a entry for the validator will be stored in the verifier state, to be returned when the verification is done.

func (*BatchVerifier) AddError added in v0.2200.3 

func (v *BatchVerifier) AddError(err error)

AddError adds an invalid entry to the current batch. This is useful to simplify the process of creating and processing a batch.

func (*BatchVerifier) Reset added in v0.2200.3 

func (v *BatchVerifier) Reset()

Reset resets a batch for reuse.

Note: This method will reuse the internal entires slice to reduce memory reallocations. If the next batch is known to be significantly smaller it may be more memory efficient to simply create a new batch.

func (*BatchVerifier) Verify added in v0.2200.3 

func (v *BatchVerifier) Verify() (bool, []error)

Verify checks all entries in the current batch, returning true if all entries in the current batch are valid. If one or more signature is invalid, the returned error vector will provide information about each individual entry.

type Context 

type Context string

Context is a domain separation context.

func NewContext 

func NewContext(rawContext string, opts ...ContextOption) Context

NewContext creates and registers a new context. This routine will panic if the context is malformed or is already registered.

func (Context) WithSuffix added in v0.2100.0 

func (c Context) WithSuffix(str string) (Context, error)

WithSuffix appends a suffix to the context.

type ContextOption 

type ContextOption func(*contextOptions)

ContextOption is a context configuration option.

func WithChainSeparation 

func WithChainSeparation() ContextOption

WithChainSeparation is a context option that enforces additional domain separation based on the ChainID.

func WithDynamicSuffix added in v0.2100.0 

func WithDynamicSuffix(str string, len int) ContextOption

WithDynamicSuffix is a context option that configures the context to use a dynamic suffix.

type MultiSigned 

type MultiSigned struct {
	// Blob is the signed blob.
	Blob []byte `json:"untrusted_raw_value"`

	// Signatures are the signatures over the blob.
	Signatures []Signature `json:"signatures"`
}

MultiSigned is a blob signed by multiple public keys.

func SignMultiSigned 

func SignMultiSigned(signers []Signer, context Context, src interface{}) (*MultiSigned, error)

SignMultiSigned generates a MultiSigned with the Signers over the context and CBOR-serialized message.

func (*MultiSigned) IsOnlySignedBy 

func (s *MultiSigned) IsOnlySignedBy(pks []PublicKey) bool

IsOnlySignedBy returns true iff the MultiSigned is signed by all of the provided public keys, and none other.

Note: This does not verify the signature, and including the same key more than once in pks will always return false.

func (*MultiSigned) IsSignedBy 

func (s *MultiSigned) IsSignedBy(pk PublicKey) bool

IsSignedBy returns true iff the MultiSigned includes a signature for the provided public key.

Note: This does not verify the signature.

func (*MultiSigned) Open 

func (s *MultiSigned) Open(context Context, dst interface{}) error

Open first verifies the blob signatures, and then unmarshals the blob.

type PrettyMultiSigned 

type PrettyMultiSigned struct {
	Body       interface{} `json:"untrusted_raw_value"`
	Signatures []Signature `json:"signatures"`
}

PrettyMultiSigned is used for pretty-printing multi-signed messages so that the actual content is displayed instead of the binary blob.

It should only be used for pretty printing.

func NewPrettyMultiSigned 

func NewPrettyMultiSigned(s MultiSigned, b interface{}) (*PrettyMultiSigned, error)

NewPrettyMultiSigned creates a new PrettySigned instance that can be used for pretty printing multi-signed values.

func (PrettyMultiSigned) PrettyPrint 

func (p PrettyMultiSigned) PrettyPrint(_ context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of the type to the given writer.

func (PrettyMultiSigned) PrettyType 

func (p PrettyMultiSigned) PrettyType() (interface{}, error)

PrettyType returns a representation of the type that can be used for pretty printing.

type PrettySigned 

type PrettySigned struct {
	Body      interface{} `json:"untrusted_raw_value"`
	Signature Signature   `json:"signature"`
}

PrettySigned is used for pretty-printing signed messages so that the actual content is displayed instead of the binary blob.

It should only be used for pretty printing.

func NewPrettySigned 

func NewPrettySigned(s Signed, b interface{}) (*PrettySigned, error)

NewPrettySigned creates a new PrettySigned instance that can be used for pretty printing signed values.

func (PrettySigned) PrettyPrint 

func (p PrettySigned) PrettyPrint(_ context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of the type to the given writer.

func (PrettySigned) PrettyType 

func (p PrettySigned) PrettyType() (interface{}, error)

PrettyType returns a representation of the type that can be used for pretty printing.

type Proof added in v0.2200.0 

type Proof struct {
	// PublicKey is the public key that produced the proof.
	PublicKey PublicKey `json:"public_key"`

	// Proof is the actual raw proof.
	Proof RawProof `json:"proof"`
}

Proof is a VRF proof, bundled with the signing public key.

func Prove added in v0.2200.0 

func Prove(signer Signer, alphaString []byte) (*Proof, error)

Prove generates a VRF proof with the private key over the alpha.

func (*Proof) UnsafeToHash added in v0.2200.0 

func (p *Proof) UnsafeToHash() []byte

UnsafeToHash extracts the hash (beta) from a VRF proof. This MUST only be called for proofs that are known to be valid.

func (*Proof) Verify added in v0.2200.0 

func (p *Proof) Verify(alphaString []byte) (bool, []byte)

Verify verifies a VRP proof over the alpha, and returns true iff the proof is valid. Iff the proof is valid, beta is also returned.

type PublicKey 

type PublicKey [PublicKeySize]byte

PublicKey is a public key used for signing.

func HashToPublicKey added in v0.2300.0 

func HashToPublicKey(dst, message []byte) (pk PublicKey)

HashToPublicKey creates a public key via h2c from the given domain separator and message. The private key of the returned public key is unknown.

func NewBlacklistedPublicKey 

func NewBlacklistedPublicKey(hex string) PublicKey

NewBlacklistedPublicKey creates a new blacklisted public key from the given hex representation or panics.

func NewPublicKey 

func NewPublicKey(hex string) (pk PublicKey)

NewPublicKey creates a new public key from the given hex representation or panics.

func (PublicKey) Blacklist 

func (k PublicKey) Blacklist() error

Blacklist adds the public key to the blacklist.

func (PublicKey) Equal 

func (k PublicKey) Equal(cmp PublicKey) bool

Equal compares vs another public key for equality.

func (PublicKey) Hash 

func (k PublicKey) Hash() hash.Hash

Hash returns a cryptographic hash of the public key.

func (PublicKey) IsBlacklisted 

func (k PublicKey) IsBlacklisted() bool

IsBlacklisted returns true iff the public key is blacklisted, prohibiting it from use.

func (PublicKey) IsValid 

func (k PublicKey) IsValid() bool

IsValid checks whether the public key is well-formed.

func (*PublicKey) LoadPEM 

func (k *PublicKey) LoadPEM(fn string, signer Signer) error

LoadPEM loads a public key from a PEM file on disk. Iff the public key is missing and a Signer is provided, the Signer's corresponding public key will be written and loaded.

func (PublicKey) MarshalBinary 

func (k PublicKey) MarshalBinary() (data []byte, err error)

MarshalBinary encodes a public key into binary form.

func (PublicKey) MarshalPEM 

func (k PublicKey) MarshalPEM() (data []byte, err error)

MarshalPEM encodes a PublicKey into PEM form.

func (PublicKey) MarshalText 

func (k PublicKey) MarshalText() (data []byte, err error)

MarshalText encodes a public key into text form.

func (PublicKey) String 

func (k PublicKey) String() string

String returns a string representation of the public key.

func (*PublicKey) UnmarshalBinary 

func (k *PublicKey) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a binary marshaled public key.

func (*PublicKey) UnmarshalHex 

func (k *PublicKey) UnmarshalHex(text string) error

UnmarshalHex deserializes a hexadecimal text string into the given type.

func (*PublicKey) UnmarshalPEM 

func (k *PublicKey) UnmarshalPEM(data []byte) error

UnmarshalPEM decodes a PEM marshaled PublicKey.

func (*PublicKey) UnmarshalText 

func (k *PublicKey) UnmarshalText(text []byte) error

UnmarshalText decodes a text marshaled public key.

func (PublicKey) Verify 

func (k PublicKey) Verify(context Context, message, sig []byte) bool

Verify returns true iff the signature is valid for the public key over the context and message.

func (PublicKey) VerifyVRF added in v0.2200.0 

func (k PublicKey) VerifyVRF(alphaString, piString []byte) (bool, []byte)

VerifyVRF returns true iff the VRF proof is valid for the public key over alpha. Iff the proof is valid, beta is also returned.

type RawProof added in v0.2200.0 

type RawProof [ProofSize]byte

RawProof is a raw VRF proof.

func (RawProof) MarshalBinary added in v0.2200.0 

func (r RawProof) MarshalBinary() (data []byte, err error)

MarshalBinary encodes a VRF proof into binary form.

func (RawProof) MarshalText added in v0.2200.0 

func (r RawProof) MarshalText() (data []byte, err error)

MarshalText encodes a VRF proof into text form.

func (RawProof) String added in v0.2200.0 

func (r RawProof) String() string

String returns a string representation of the raw VRF proof.

func (*RawProof) UnmarshalBinary added in v0.2200.0 

func (r *RawProof) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a binary marshaled VRF proof.

func (*RawProof) UnmarshalText added in v0.2200.0 

func (r *RawProof) UnmarshalText(text []byte) error

UnmarshalText decodes a text marshaled VRF proof.

type RawSignature 

type RawSignature [SignatureSize]byte

RawSignature is a raw signature.

func SignRaw added in v0.2400.0 

func SignRaw(signer Signer, context Context, message []byte) (*RawSignature, error)

SignRaw generates a signature with the private key over the context and message.

func (RawSignature) Equal 

func (r RawSignature) Equal(cmp RawSignature) bool

Equal compares vs another public key for equality.

func (RawSignature) MarshalBinary 

func (r RawSignature) MarshalBinary() (data []byte, err error)

MarshalBinary encodes a signature into binary form.

func (RawSignature) MarshalPEM 

func (r RawSignature) MarshalPEM() (data []byte, err error)

MarshalPEM encodes a raw signature into PEM format.

func (RawSignature) MarshalText 

func (r RawSignature) MarshalText() (data []byte, err error)

MarshalText encodes a signature into text form.

func (RawSignature) String 

func (r RawSignature) String() string

String returns a string representation of the raw signature.

func (*RawSignature) UnmarshalBinary 

func (r *RawSignature) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes a binary marshaled signature.

func (*RawSignature) UnmarshalPEM 

func (r *RawSignature) UnmarshalPEM(data []byte) error

UnmarshalPEM decodes a PEM marshaled raw signature.

func (*RawSignature) UnmarshalText 

func (r *RawSignature) UnmarshalText(text []byte) error

UnmarshalText decodes a text marshaled signature.

type Signature 

type Signature struct {
	// PublicKey is the public key that produced the signature.
	PublicKey PublicKey `json:"public_key"`

	// Signature is the actual raw signature.
	Signature RawSignature `json:"signature"`
}

Signature is a signature, bundled with the signing public key.

func Sign 

func Sign(signer Signer, context Context, message []byte) (*Signature, error)

Sign generates a signature with the private key over the context and message.

func (*Signature) Equal 

func (s *Signature) Equal(cmp *Signature) bool

Equal compares vs another signature for equality.

func (Signature) MarshalPEM 

func (s Signature) MarshalPEM() (data []byte, err error)

MarshalPEM encodes a signature into PEM format.

func (*Signature) SanityCheck 

func (s *Signature) SanityCheck(expectedPubKey PublicKey) error

SanityCheck checks if the signature appears to be well formed.

func (*Signature) UnmarshalPEM 

func (s *Signature) UnmarshalPEM(data []byte) error

UnmarshalPEM decodes a PEM marshaled signature.

func (*Signature) Verify 

func (s *Signature) Verify(context Context, message []byte) bool

Verify returns true iff the signature is valid over the given context and message.

type Signed 

type Signed struct {
	// Blob is the signed blob.
	Blob []byte `json:"untrusted_raw_value"`

	// Signature is the signature over blob.
	Signature Signature `json:"signature"`
}

Signed is a signed blob.

func SignSigned 

func SignSigned(signer Signer, context Context, src interface{}) (*Signed, error)

SignSigned generates a Signed with the Signer over the context and CBOR-serialized message.

func (*Signed) Equal 

func (s *Signed) Equal(cmp *Signed) bool

Equal compares vs another Signed for equality.

func (*Signed) Open 

func (s *Signed) Open(context Context, dst interface{}) error

Open first verifies the blob signature and then unmarshals the blob.

type SignedPublicKey 

type SignedPublicKey struct {
	Signed
}

SignedPublicKey is a signed blob containing a PublicKey.

func (*SignedPublicKey) Open 

func (s *SignedPublicKey) Open(context Context, pub *PublicKey) error

Open first verifies the blob signature and then unmarshals the blob.

type Signer 

type Signer interface {
	// Public returns the PublicKey corresponding to the signer.
	Public() PublicKey

	// ContextSign generates a signature with the private key over the context and
	// message.
	ContextSign(context Context, message []byte) ([]byte, error)

	// String returns the string representation of a Signer, which MUST not
	// include any sensitive information.
	String() string

	// Reset tears down the Signer and obliterates any sensitive state if any.
	Reset()
}

Signer is an opaque interface for private keys that is capable of producing signatures, in the spirit of `crypto.Signer`.

type SignerFactory 

type SignerFactory interface {
	// EnsureRole ensures that the SignerFactory is configured for the given
	// role.
	EnsureRole(role SignerRole) error

	// Generate will generate and persist an new private key corresponding to
	// the provided role, and return a Signer ready for use.  Certain
	// implementations require an entropy source to be provided.
	Generate(role SignerRole, rng io.Reader) (Signer, error)

	// Load will load the private key corresponding to the provided role, and
	// return a Signer ready for use.
	Load(role SignerRole) (Signer, error)
}

SignerFactory is the opaque factory interface for Signers.

type SignerFactoryCtor 

type SignerFactoryCtor func(interface{}, ...SignerRole) (SignerFactory, error)

SignerFactoryCtor is an SignerFactory constructor.

type SignerRole 

type SignerRole int

SignerRole is the role of the Signer (Entity, Node, etc).

func (SignerRole) MarshalText added in v0.2010.0 

func (role SignerRole) MarshalText() ([]byte, error)

MarshalText encodes a SignerRole into text form.

func (SignerRole) String added in v0.2010.0 

func (role SignerRole) String() string

String returns the string representation of a SignerRole.

func (*SignerRole) UnmarshalText added in v0.2010.0 

func (role *SignerRole) UnmarshalText(text []byte) error

UnmarshalText decodes a text slice into a SignerRole.

type StaticEntropyProvider added in v0.2200.0 

type StaticEntropyProvider interface {
	// StaticEntropy returns PrivateKeySize bytes of cryptographic entropy that/ is independent from
	// the Signer's private key.  The value of this entropy is constant for the lifespan of the
	// signer's underlying key pair.
	StaticEntropy() ([]byte, error)
}

StaticEntropyProvider is the interface implemented by signers that support providing persistent static entropy that is entirely independent from a keypair.

type UnsafeSigner 

type UnsafeSigner interface {
	Signer

	// UnsafeBytes returns the byte representation of the private key.
	UnsafeBytes() []byte
}

UnsafeSigner is a Signer that also supports access to the raw private key, primarily for testing.

type VRFSigner added in v0.2200.0 

type VRFSigner interface {
	Signer

	// Prove generates a VRF proof with the private key over the alpha.
	Prove(alphaString []byte) ([]byte, error)
}

VRFSigner is a Signer that also supports generating VRF proofs, using the semantics from the IETF Verifiable Random Functions draft.

Source Files

View all Source files

Directories

Path Synopsis
signers
composite
Package composite provides a composite signer.
 Package composite provides a composite signer.
file
Package file provides a PEM file backed signer.
 Package file provides a PEM file backed signer.
memory
Package memory provides a memory backed Signer, primarily for use in testing.
 Package memory provides a memory backed Signer, primarily for use in testing.
plugin
Package plugin implements the Go plugin signature signer.
 Package plugin implements the Go plugin signature signer.
remote
Package remote provides a gRPC backed signer (both client and server).
 Package remote provides a gRPC backed signer (both client and server).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.