signature

package
Version: v0.2103.1 Latest Latest
Warning

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

Go to latest
Published: Oct 8, 2021 License: Apache-2.0 Imports: 22 Imported by: 12

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

	SignerEntityName    = "entity"
	SignerNodeName      = "node"
	SignerP2PName       = "p2p"
	SignerConsensusName = "consensus"
)

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")
)
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")

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

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 VerifyBatch

func VerifyBatch(context Context, messages [][]byte, sigs []Signature) bool

VerifyBatch verifies multiple signatures, made by multiple public keys, against a single context and multiple messages, returning true iff every signature is valid.

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 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(ctx 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(ctx 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 PublicKey

type PublicKey [PublicKeySize]byte

PublicKey is a public key used for signing.

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.

type RawSignature

type RawSignature [SignatureSize]byte

RawSignature is a raw signature.

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 corresonding 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 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.

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