signature

Documentation

Overview

Package signature implements signing and verification of pipeline steps.

Index

• Constants
• func EmptyToNilMap[K comparable, V any, M ~map[K]V](m M) M
• func EmptyToNilPtr[V any, P pointerEmptyable[V]](p P) P
• func EmptyToNilSlice[E any, S ~[]E](s S) S
• func Sign(_ context.Context, key Key, sf SignedFielder, opts ...Option) (*pipeline.Signature, error)
• func SignSteps(ctx context.Context, s pipeline.Steps, key Key, repoURL string, opts ...Option) error
• func Verify(ctx context.Context, s *pipeline.Signature, keySet any, sf SignedFielder, ...) error
• type CommandStepWithInvariants
  • func (c *CommandStepWithInvariants) SignedFields() (map[string]any, error)
  • func (c *CommandStepWithInvariants) ValuesForFields(fields []string) (map[string]any, error)
• type Key
• type Logger
• type Option
  • func WithDebugSigning(debugSigning bool) Option
  • func WithEnv(env map[string]string) Option
  • func WithLogger(logger Logger) Option
• type SignedFielder

Constants

const EnvNamespacePrefix = "env::"

EnvNamespacePrefix is the string that prefixes all fields in the "env" namespace. This is used to separate signed data that came from the environment from data that came from an object.

Functions

func EmptyToNilMap

func EmptyToNilMap[K comparable, V any, M ~map[K]V](m M) M

EmptyToNilMap returns a nil map if m is empty, otherwise it returns m. This can be used to canonicalise empty/nil values if there is no semantic distinction between nil and empty. Sign and Verify do not apply this automatically. nil was chosen as the canonical value, since it is the zero value for the type. (A user would have to write e.g. "env: {}" to get a zero-length non-nil env map.)

func EmptyToNilPtr

func EmptyToNilPtr[V any, P pointerEmptyable[V]](p P) P

EmptyToNilPtr returns a nil pointer if p points to a variable containing an empty value for V, otherwise it returns p. Emptiness is determined by calling IsEmpty on p. Sign and Verify do not apply this automatically. nil was chosen as the canonical value since it is the zero value for pointer types. (A user would have to write e.g. "matrix: {}" to get an empty non-nil matrix specification.)

func EmptyToNilSlice

func EmptyToNilSlice[E any, S ~[]E](s S) S

EmptyToNilSlice returns a nil slice if s is empty, otherwise it returns s. This can be used to canonicalise empty/nil values if there is no semantic distinction between nil and empty. Sign and Verify do not apply this automatically. nil was chosen as the canonical value, since it is the zero value for the type. (A user would have to write e.g. "plugins: []" to get a zero-length non-nil plugins slice.)

func Sign

func Sign(_ context.Context, key Key, sf SignedFielder, opts ...Option) (*pipeline.Signature, error)

Sign computes a new signature for an environment (env) combined with an object containing values (sf) using a given key. The key can be a jwk.Key or a crypto.Signer. If it is a jwk.Key, the public key thumbprint is logged.

func SignSteps

func SignSteps(ctx context.Context, s pipeline.Steps, key Key, repoURL string, opts ...Option) error

SignSteps adds signatures to each command step (and recursively to any command steps that are within group steps). The steps are mutated directly, so an error part-way through may leave some steps un-signed.

func Verify

func Verify(ctx context.Context, s *pipeline.Signature, keySet any, sf SignedFielder, opts ...Option) error

Verify verifies an existing signature against environment (env) combined with the keyset. The keySet can be a jwk.Set or a crypto.Signer. If it is a jwk.Set, the public key thumbprints are logged.

Types

type CommandStepWithInvariants

type CommandStepWithInvariants struct {
	pipeline.CommandStep
	RepositoryURL string
}

CommandStepWithInvariants is a CommandStep with PipelineInvariants.

func (*CommandStepWithInvariants) SignedFields

func (c *CommandStepWithInvariants) SignedFields() (map[string]any, error)

SignedFields returns the default fields for signing.

func (*CommandStepWithInvariants) ValuesForFields

func (c *CommandStepWithInvariants) ValuesForFields(fields []string) (map[string]any, error)

ValuesForFields returns the contents of fields to sign.

type Key

type Key interface {
	Algorithm() jwa.KeyAlgorithm
}

type Logger

type Logger interface{ Debug(f string, v ...any) }

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithDebugSigning

func WithDebugSigning(debugSigning bool) Option

func WithEnv

func WithEnv(env map[string]string) Option

func WithLogger

func WithLogger(logger Logger) Option

type SignedFielder

type SignedFielder interface {
	// SignedFields returns the default set of fields to sign, and their values.
	// This is called by Sign.
	SignedFields() (map[string]any, error)

	// ValuesForFields looks up each field and produces a map of values. This is
	// called by Verify. The set of fields might differ from the default, e.g.
	// when verifying older signatures computed with fewer fields or deprecated
	// field names. signedFielder implementations should reject requests for
	// values if "mandatory" fields are missing (e.g. signing a command step
	// should always sign the command).
	ValuesForFields([]string) (map[string]any, error)
}

SignedFielder describes types that can be signed and have signatures verified. Converting non-string fields into strings (in a stable, canonical way) is an exercise left to the implementer.