spire

Documentation

Overview

The spire package is used to interact with the Spire server and Spire agent respectively. The pipeline controller (once registered) is able to create and delete entries in the Spire server for the various TaskRuns that it instantiates. The TaskRun is able to attest to the Spire agent and obtains the valid SVID (SPIFFE Verifiable Identity Document) to sign the TaskRun results. Separately, the pipeline controller SVID is used to sign the TaskRun Status to validate no modification during the TaskRun execution. Each TaskRun result and status is verified and validated once the TaskRun execution is completed. Tekton Chains will also validate the results and status before signing and creating attestation for the TaskRun.

Index

• Constants
• func CheckStatusInternalAnnotation(tr *v1beta1.TaskRun) error
• type ControllerAPIClient
  • func GetControllerAPIClient(ctx context.Context) ControllerAPIClient
• type EntrypointerAPIClient
  • func NewEntrypointerAPIClient(c *spireconfig.SpireConfig) EntrypointerAPIClient
• type MockClient
  • func (sc *MockClient) AppendStatusInternalAnnotation(ctx context.Context, tr *v1beta1.TaskRun) error
  • func (sc *MockClient) CheckSpireVerifiedFlag(tr *v1beta1.TaskRun) bool
  • func (sc *MockClient) Close() error
  • func (sc *MockClient) CreateEntries(ctx context.Context, tr *v1beta1.TaskRun, pod *corev1.Pod, ttl time.Duration) error
  • func (sc *MockClient) DeleteEntry(ctx context.Context, tr *v1beta1.TaskRun, pod *corev1.Pod) error
  • func (*MockClient) GetIdentity(tr *v1beta1.TaskRun) string
  • func (sc *MockClient) SetConfig(c spireconfig.SpireConfig)
  • func (sc *MockClient) Sign(ctx context.Context, results []v1beta1.PipelineResourceResult) ([]v1beta1.PipelineResourceResult, error)
  • func (sc *MockClient) VerifyStatusInternalAnnotation(ctx context.Context, tr *v1beta1.TaskRun, logger *zap.SugaredLogger) error
  • func (sc *MockClient) VerifyTaskRunResults(ctx context.Context, prs []v1beta1.PipelineResourceResult, tr *v1beta1.TaskRun) error

Constants

const (
	// TaskRunStatusHashAnnotation TaskRun status annotation Hash Key
	TaskRunStatusHashAnnotation = "tekton.dev/status-hash"

	// VerifiedAnnotation TaskRun status annotation get set when status annotations fails spire checks.
	// not set if spire checks pass
	VerifiedAnnotation = "tekton.dev/spire-verified"
	// KeySVID key used by TaskRun SVID
	KeySVID = "SVID"
	// KeySignatureSuffix is the suffix of the keys that contain signatures
	KeySignatureSuffix = ".sig"
	// KeyResultManifest key used to get the result manifest from the results
	KeyResultManifest = "RESULT_MANIFEST"
	// WorkloadAPI is the name of the SPIFFE/SPIRE CSI Driver volume
	WorkloadAPI = "spiffe-workload-api"
	// VolumeMountPath is the volume mount in the the pods to access the SPIFFE/SPIRE agent workload API
	VolumeMountPath = "/spiffe-workload-api"
)

Functions

func CheckStatusInternalAnnotation

func CheckStatusInternalAnnotation(tr *v1beta1.TaskRun) error

CheckStatusInternalAnnotation ensures that the internal status annotation hash and current status hash match

Types

type ControllerAPIClient

type ControllerAPIClient interface {
	AppendStatusInternalAnnotation(ctx context.Context, tr *v1beta1.TaskRun) error
	CheckSpireVerifiedFlag(tr *v1beta1.TaskRun) bool
	Close() error
	CreateEntries(ctx context.Context, tr *v1beta1.TaskRun, pod *corev1.Pod, ttl time.Duration) error
	DeleteEntry(ctx context.Context, tr *v1beta1.TaskRun, pod *corev1.Pod) error
	VerifyStatusInternalAnnotation(ctx context.Context, tr *v1beta1.TaskRun, logger *zap.SugaredLogger) error
	VerifyTaskRunResults(ctx context.Context, prs []v1beta1.PipelineResourceResult, tr *v1beta1.TaskRun) error
	SetConfig(c spireconfig.SpireConfig)
}

ControllerAPIClient interface maps to the spire controller API to interact with spire

func GetControllerAPIClient

func GetControllerAPIClient(ctx context.Context) ControllerAPIClient

GetControllerAPIClient extracts the ControllerAPIClient from the context.

type EntrypointerAPIClient

type EntrypointerAPIClient interface {
	Close() error
	// Sign returns the signature material to be put in the PipelineResourceResult to append to the output results
	Sign(ctx context.Context, results []v1beta1.PipelineResourceResult) ([]v1beta1.PipelineResourceResult, error)
}

EntrypointerAPIClient interface maps to the spire entrypointer API to interact with spire

func NewEntrypointerAPIClient

func NewEntrypointerAPIClient(c *spireconfig.SpireConfig) EntrypointerAPIClient

NewEntrypointerAPIClient creates the EntrypointerAPIClient

type MockClient

type MockClient struct {
	// Entries is a dictionary of entries that mock the SPIRE server datastore (for function Sign only)
	Entries map[string]bool

	// SignIdentities represents the list of identities to use to sign (providing context of a caller to Sign)
	// when Sign is called, the identity is dequeued from the slice. A signature will only be provided if the
	// corresponding entry is in Entries. This only takes effect if SignOverride is nil.
	SignIdentities []string

	// VerifyAlwaysReturns defines whether to always verify successfully or to always fail verification if non-nil.
	// This only take effect on Verify functions:
	// - VerifyStatusInternalAnnotationOverride
	// - VerifyTaskRunResultsOverride
	VerifyAlwaysReturns *bool

	// VerifyStatusInternalAnnotationOverride contains the function to overwrite a call to VerifyStatusInternalAnnotation
	VerifyStatusInternalAnnotationOverride func(ctx context.Context, tr *v1beta1.TaskRun, logger *zap.SugaredLogger) error

	// VerifyTaskRunResultsOverride contains the function to overwrite a call to VerifyTaskRunResults
	VerifyTaskRunResultsOverride func(ctx context.Context, prs []v1beta1.PipelineResourceResult, tr *v1beta1.TaskRun) error

	// AppendStatusInternalAnnotationOverride  contains the function to overwrite a call to AppendStatusInternalAnnotation
	AppendStatusInternalAnnotationOverride func(ctx context.Context, tr *v1beta1.TaskRun) error

	// CheckSpireVerifiedFlagOverride contains the function to overwrite a call to CheckSpireVerifiedFlag
	CheckSpireVerifiedFlagOverride func(tr *v1beta1.TaskRun) bool

	// SignOverride contains the function to overwrite a call to Sign
	SignOverride func(ctx context.Context, results []v1beta1.PipelineResourceResult) ([]v1beta1.PipelineResourceResult, error)
}

MockClient is a client used for mocking the this package for unit testing other tekton components that use the spire entrypointer or controller client.

The MockClient implements both SpireControllerApiClient and SpireEntrypointerApiClient and in addition to that provides the helper functions to define and query internal state.

func (*MockClient) AppendStatusInternalAnnotation

func (sc *MockClient) AppendStatusInternalAnnotation(ctx context.Context, tr *v1beta1.TaskRun) error

AppendStatusInternalAnnotation creates the status annotations which are used by the controller to verify the status hash

func (*MockClient) CheckSpireVerifiedFlag

func (sc *MockClient) CheckSpireVerifiedFlag(tr *v1beta1.TaskRun) bool

CheckSpireVerifiedFlag checks if the verified status annotation is set which would result in spire verification failed

func (*MockClient) Close

func (sc *MockClient) Close() error

Close mock closing the spire client connection

func (*MockClient) CreateEntries

func (sc *MockClient) CreateEntries(ctx context.Context, tr *v1beta1.TaskRun, pod *corev1.Pod, ttl time.Duration) error

CreateEntries adds entries to the dictionary of entries that mock the SPIRE server datastore

func (*MockClient) DeleteEntry

func (sc *MockClient) DeleteEntry(ctx context.Context, tr *v1beta1.TaskRun, pod *corev1.Pod) error

DeleteEntry removes the entry from the dictionary of entries that mock the SPIRE server datastore

func (*MockClient) GetIdentity

func (*MockClient) GetIdentity(tr *v1beta1.TaskRun) string

GetIdentity get the taskrun namespace and taskrun name that is used for signing and verifying in mocked spire

func (*MockClient) SetConfig

func (sc *MockClient) SetConfig(c spireconfig.SpireConfig)

SetConfig sets the spire configuration for MockClient

func (*MockClient) Sign

func (sc *MockClient) Sign(ctx context.Context, results []v1beta1.PipelineResourceResult) ([]v1beta1.PipelineResourceResult, error)

Sign signs and appends signatures to the PipelineResourceResult based on the mocked spire client

func (*MockClient) VerifyStatusInternalAnnotation

func (sc *MockClient) VerifyStatusInternalAnnotation(ctx context.Context, tr *v1beta1.TaskRun, logger *zap.SugaredLogger) error

VerifyStatusInternalAnnotation checks that the internal status annotations are valid by the mocked spire client

func (*MockClient) VerifyTaskRunResults

func (sc *MockClient) VerifyTaskRunResults(ctx context.Context, prs []v1beta1.PipelineResourceResult, tr *v1beta1.TaskRun) error

VerifyTaskRunResults checks that all the TaskRun results are valid by the mocked spire client