signature

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2024 License: Apache-2.0 Imports: 10 Imported by: 9

Documentation

Overview

Package signature provides operations for types that implement signature.Envelope or signature.Signer.

An Envelope is a structure that creates and verifies a signature using the specified signing algorithm with required validation. To register a new envelope, call RegisterEnvelopeType first during the initialization.

A Signer is a structure used to sign payload generated after signature envelope created. The underlying signing logic is provided by the underlying local crypto library or the external signing plugin.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterEnvelopeType 

func RegisterEnvelopeType(mediaType string, newFunc NewEnvelopeFunc, parseFunc ParseEnvelopeFunc) error

RegisterEnvelopeType registers newFunc and parseFunc for the given mediaType. Those functions are intended to be called when creating a new envelope. It will be called while inializing the built-in envelopes(JWS/COSE).

func RegisteredEnvelopeTypes 

func RegisteredEnvelopeTypes() []string

RegisteredEnvelopeTypes lists registered envelope media types.

func VerifyAuthenticity 

func VerifyAuthenticity(signerInfo *SignerInfo, trustedCerts []*x509.Certificate) (*x509.Certificate, error)

VerifyAuthenticity verifies the certificate chain in the given SignerInfo with one of the trusted certificates and returns a certificate that matches with one of the certificates in the SignerInfo.

Reference: https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#steps

Types

type Algorithm 

type Algorithm int

Algorithm defines the signature algorithm. 

const (
	AlgorithmPS256 Algorithm = 1 + iota // RSASSA-PSS with SHA-256
	AlgorithmPS384                      // RSASSA-PSS with SHA-384
	AlgorithmPS512                      // RSASSA-PSS with SHA-512
	AlgorithmES256                      // ECDSA on secp256r1 with SHA-256
	AlgorithmES384                      // ECDSA on secp384r1 with SHA-384
	AlgorithmES512                      // ECDSA on secp521r1 with SHA-512
)

Signature algorithms supported by this library.

Reference: https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection

func (Algorithm) Hash 

func (alg Algorithm) Hash() crypto.Hash

Hash returns the hash function of the algorithm.

type Attribute 

type Attribute struct {
	// Key is the key name of the attribute.
	Key any

	// Critical marks the attribute that MUST be processed by a verifier.
	Critical bool

	// Value is the value of the attribute.
	Value any
}

Attribute represents metadata in the Signature envelope.

type DuplicateKeyError 

type DuplicateKeyError struct {
	Key string
}

DuplicateKeyError is used when repeated key name found.

func (*DuplicateKeyError) Error 

func (e *DuplicateKeyError) Error() string

Error returns the formatted error message.

type Envelope 

type Envelope interface {
	// Sign generates and sign the envelope according to the sign request.
	Sign(req *SignRequest) ([]byte, error)

	// Verify verifies the envelope and returns its enclosed payload and signer
	// info.
	Verify() (*EnvelopeContent, error)

	// Content returns the payload and signer information of the envelope.
	// Content is trusted only after the successful call to `Verify()`.
	Content() (*EnvelopeContent, error)
}

Envelope provides basic functions to manipulate signatures.

func NewEnvelope 

func NewEnvelope(mediaType string) (Envelope, error)

NewEnvelope generates an envelope of given media type.

func ParseEnvelope 

func ParseEnvelope(mediaType string, envelopeBytes []byte) (Envelope, error)

ParseEnvelope generates an envelope for given envelope bytes with specified media type.

type EnvelopeContent 

type EnvelopeContent struct {
	// SignerInfo is a parsed signature envelope.
	SignerInfo SignerInfo

	// Payload is payload to be signed.
	Payload Payload
}

EnvelopeContent represents a combination of payload to be signed and a parsed signature envelope.

type InvalidArgumentError 

type InvalidArgumentError struct {
	Param string
	Err   error
}

InvalidArgumentError is used when an argument to a function is invalid.

func (*InvalidArgumentError) Error 

func (e *InvalidArgumentError) Error() string

Error returns the error message.

func (*InvalidArgumentError) Unwrap 

func (e *InvalidArgumentError) Unwrap() error

Unwrap returns the unwrapped error.

type InvalidSignRequestError 

type InvalidSignRequestError struct {
	Msg string
}

InvalidSignRequestError is used when SignRequest is invalid.

func (*InvalidSignRequestError) Error 

func (e *InvalidSignRequestError) Error() string

Error returns the error message or the default message if not provided.

type InvalidSignatureError 

type InvalidSignatureError struct {
	Msg string
}

InvalidSignatureError is used when Signature envelope is invalid.

func (InvalidSignatureError) Error 

func (e InvalidSignatureError) Error() string

Error returns the error message or the default message if not provided.

type KeySpec 

type KeySpec struct {
	// KeyType is the type of the key.
	Type KeyType

	// KeySize is the size of the key in bits.
	Size int
}

KeySpec defines a key type and size.

func ExtractKeySpec 

func ExtractKeySpec(signingCert *x509.Certificate) (KeySpec, error)

ExtractKeySpec extracts KeySpec from the signing certificate.

func (KeySpec) SignatureAlgorithm 

func (k KeySpec) SignatureAlgorithm() Algorithm

SignatureAlgorithm returns the signing algorithm associated with the KeySpec.

type KeyType 

type KeyType int

KeyType defines the key type. 

const (
	KeyTypeRSA KeyType = 1 + iota // KeyType RSA
	KeyTypeEC                     // KeyType EC
)

type LocalSigner 

type LocalSigner interface {
	Signer

	// CertificateChain returns the certificate chain.
	CertificateChain() ([]*x509.Certificate, error)

	// PrivateKey returns the private key.
	PrivateKey() crypto.PrivateKey
}

LocalSigner is only used by built-in signers to sign.

func NewLocalSigner 

func NewLocalSigner(certs []*x509.Certificate, key crypto.PrivateKey) (LocalSigner, error)

NewLocalSigner returns a new signer with given certificates and private key.

type NewEnvelopeFunc 

type NewEnvelopeFunc func() Envelope

NewEnvelopeFunc defines a function to create a new Envelope.

type ParseEnvelopeFunc 

type ParseEnvelopeFunc func([]byte) (Envelope, error)

ParseEnvelopeFunc defines a function that takes envelope bytes to create an Envelope.

type Payload 

type Payload struct {
	// ContentType specifies the content type of payload.
	ContentType string

	// Content contains the raw bytes of the payload.
	//
	// For JWS envelope, Content is limited to be JSON format.
	Content []byte
}

Payload represents payload in bytes and its content type.

type SignRequest 

type SignRequest struct {
	// Payload is the payload to be signed.
	//
	// For JWS envelope, Payload.Content is limited to be JSON format.
	Payload Payload

	// Signer is the signer used to sign the digest.
	Signer Signer

	// SigningTime is the time at which the signature was generated.
	SigningTime time.Time

	// Expiry provides a “best by use” time for the artifact.
	Expiry time.Time

	// ExtendedSignedAttributes is additional signed attributes in the
	// signature envelope.
	ExtendedSignedAttributes []Attribute

	// SigningAgent provides the identifier of the software (e.g. Notation)
	// that produced the signature on behalf of the user.
	SigningAgent string

	// SigningScheme defines the Notary Project Signing Scheme used by the signature.
	SigningScheme SigningScheme

	// Timestamper denotes the timestamper for RFC 3161 timestamping
	Timestamper tspclient.Timestamper

	// TSARootCAs is the set of caller trusted TSA root certificates
	TSARootCAs *x509.CertPool
	// contains filtered or unexported fields
}

SignRequest is used to generate Signature.

func (*SignRequest) Context added in v1.1.0 

func (r *SignRequest) Context() context.Context

Context returns the SignRequest's context. To change the context, use SignRequest.WithContext.

The returned context is always non-nil; it defaults to the background context.

func (*SignRequest) WithContext added in v1.1.0 

func (r *SignRequest) WithContext(ctx context.Context) *SignRequest

WithContext returns a shallow copy of r with its context changed to ctx. The provided ctx must be non-nil.

type SignatureAuthenticityError 

type SignatureAuthenticityError struct{}

SignatureAuthenticityError is used when signature is not generated using trusted certificates.

func (*SignatureAuthenticityError) Error 

func (e *SignatureAuthenticityError) Error() string

Error returns the default error message.

type SignatureEnvelopeNotFoundError 

type SignatureEnvelopeNotFoundError struct{}

SignatureEnvelopeNotFoundError is used when signature envelope is not present.

func (*SignatureEnvelopeNotFoundError) Error 

func (e *SignatureEnvelopeNotFoundError) Error() string

Error returns the default error message.

type SignatureIntegrityError 

type SignatureIntegrityError struct {
	Err error
}

SignatureIntegrityError is used when the signature associated is no longer valid.

func (*SignatureIntegrityError) Error 

func (e *SignatureIntegrityError) Error() string

Error returns the formatted error message.

func (*SignatureIntegrityError) Unwrap 

func (e *SignatureIntegrityError) Unwrap() error

Unwrap unwraps the internal error.

type SignatureMediaType 

type SignatureMediaType string

SignatureMediaType list the supported media-type for signatures.

type SignatureNotFoundError 

type SignatureNotFoundError struct{}

SignatureNotFoundError is used when signature envelope is not present.

func (SignatureNotFoundError) Error 

func (e SignatureNotFoundError) Error() string

type SignedAttributes 

type SignedAttributes struct {
	// SigningScheme defines the Notary Project Signing Scheme used by the signature.
	SigningScheme SigningScheme

	// SigningTime indicates the time at which the signature was generated.
	SigningTime time.Time

	// Expiry provides a “best by use” time for the artifact.
	Expiry time.Time

	// additional signed attributes in the signature envelope.
	ExtendedAttributes []Attribute
}

SignedAttributes represents signed metadata in the signature envelope. Reference: https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#signed-attributes

type Signer 

type Signer interface {
	// Sign signs the payload and returns the raw signature and certificates.
	Sign(payload []byte) ([]byte, []*x509.Certificate, error)

	// KeySpec returns the key specification.
	KeySpec() (KeySpec, error)
}

Signer is used to sign bytes generated after signature envelope created.

type SignerInfo 

type SignerInfo struct {
	// SignedAttributes are additional metadata required to support the
	// signature verification process.
	SignedAttributes SignedAttributes

	// UnsignedAttributes are considered unsigned with respect to the signing
	// key that generates the signature.
	UnsignedAttributes UnsignedAttributes

	// SignatureAlgorithm defines the signature algorithm.
	SignatureAlgorithm Algorithm

	// CertificateChain is an ordered list of X.509 public certificates
	// associated with the signing key used to generate the signature.
	// The ordered list starts with the signing certificates, any intermediate
	// certificates and ends with the root certificate.
	CertificateChain []*x509.Certificate

	// Signature is the bytes generated from the signature.
	Signature []byte
}

SignerInfo represents a parsed signature envelope that is agnostic to signature envelope format.

func (*SignerInfo) AuthenticSigningTime 

func (signerInfo *SignerInfo) AuthenticSigningTime() (time.Time, error)

AuthenticSigningTime returns the authentic signing time under signing scheme notary.x509.signingAuthority. For signing scheme notary.x509, since it only supports authentic timestamp, an error is returned.

Reference: https://github.com/notaryproject/specifications/blob/3b0743cd9bb99faee60600dc31d706149775fd49/specs/signature-specification.md#signing-time--authentic-signing-time

func (*SignerInfo) ExtendedAttribute 

func (signerInfo *SignerInfo) ExtendedAttribute(key string) (Attribute, error)

ExtendedAttribute fetches the specified Attribute with provided key from signerInfo.SignedAttributes.ExtendedAttributes.

type SigningScheme 

type SigningScheme string

SigningScheme formalizes the feature set (guarantees) provided by the signature. Reference: https://github.com/notaryproject/notaryproject/blob/main/specs/signing-scheme.md 

const (
	// notary.x509 signing scheme.
	SigningSchemeX509 SigningScheme = "notary.x509"

	// notary.x509.signingAuthority schema.
	SigningSchemeX509SigningAuthority SigningScheme = "notary.x509.signingAuthority"
)

SigningSchemes supported by notation.

type TimestampError added in v1.1.0 

type TimestampError struct {
	Msg    string
	Detail error
}

TimestampError is any error related to RFC3161 Timestamp.

func (*TimestampError) Error added in v1.1.0 

func (e *TimestampError) Error() string

Error returns the formatted error message.

func (*TimestampError) Unwrap added in v1.1.0 

func (e *TimestampError) Unwrap() error

Unwrap returns the detail error of e.

type UnsignedAttributes 

type UnsignedAttributes struct {
	// TimestampSignature is a counter signature providing authentic timestamp.
	TimestampSignature []byte

	// SigningAgent provides the identifier of the software (e.g. Notation) that
	// produces the signature on behalf of the user.
	SigningAgent string
}

UnsignedAttributes represents unsigned metadata in the Signature envelope. Reference: https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#unsigned-attributes

type UnsupportedSignatureAlgoError 

type UnsupportedSignatureAlgoError struct {
	Alg string
}

UnsupportedSignatureAlgoError is used when signing algo is not supported.

func (*UnsupportedSignatureAlgoError) Error 

func (e *UnsupportedSignatureAlgoError) Error() string

Error returns the formatted error message.

type UnsupportedSignatureFormatError 

type UnsupportedSignatureFormatError struct {
	MediaType string
}

UnsupportedSignatureFormatError is used when Signature envelope is not supported.

func (*UnsupportedSignatureFormatError) Error 

func (e *UnsupportedSignatureFormatError) Error() string

Error returns the formatted error message.

type UnsupportedSigningKeyError 

type UnsupportedSigningKeyError struct {
	Msg string
}

UnsupportedSigningKeyError is used when a signing key is not supported.

func (UnsupportedSigningKeyError) Error 

func (e UnsupportedSigningKeyError) Error() string

Error returns the error message or the default message if not provided.

Source Files

View all Source files

Directories

Path Synopsis
internal
base
signaturetest
Package signaturetest includes variables and functions for signature unit test.
 Package signaturetest includes variables and functions for signature unit test.

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.