attestation

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Aug 28, 2024 License: Apache-2.0 Imports: 28 Imported by: 0

README

attestations

This package is for components that deal with the creation, storage, and retrieval of signed attestions using OCI.

For more generic OCI components see the oci package.

Documentation

Index

Examples

Constants

View Source
const (
	DockerReferenceType           = "vnd.docker.reference.type"
	AttestationManifestType       = "attestation-manifest"
	InTotoPredicateType           = "in-toto.io/predicate-type"
	DockerReferenceDigest         = "vnd.docker.reference.digest"
	DockerDSSEExtKind             = "application/vnd.docker.attestation-verification.v1+json"
	RekorTLExtKind                = "Rekor"
	OCIDescriptorDSSEMediaType    = ociv1.MediaTypeDescriptor + "+dsse"
	InTotoReferenceLifecycleStage = "vnd.docker.lifecycle-stage"
	LifecycleStageExperimental    = "experimental"
)
View Source
const (
	VSAPredicateType = "https://slsa.dev/verification_summary/v1"
)

Variables

This section is empty.

Functions

func DSSEMediaType added in v0.1.3

func DSSEMediaType(predicateType string) (string, error)

func ToVSAResourceURI added in v0.1.3

func ToVSAResourceURI(sub intoto.Subject) (string, error)

func UpdateIndexImages added in v0.1.8

func UpdateIndexImages(idx v1.ImageIndex, manifest []*Manifest, options ...func(*ManifestImageOptions) error) (v1.ImageIndex, error)

func ValidPayloadType

func ValidPayloadType(payloadType string) bool

func VerifyDSSE

func VerifyDSSE(ctx context.Context, env *Envelope, opts *VerifyOptions) ([]byte, error)

func WithReferrersRepo added in v0.3.1

func WithReferrersRepo(repo string) func(*ReferrersResolver) error

func WithReplacedLayers added in v0.1.8

func WithReplacedLayers(replaceLayers bool) func(*ManifestImageOptions) error

func WithoutSubject added in v0.1.8

func WithoutSubject(skipSubject bool) func(*ManifestImageOptions) error

Types

type AnnotatedStatement added in v0.3.1

type AnnotatedStatement struct {
	OCIDescriptor   *v1.Descriptor
	InTotoStatement *intoto.Statement
	Annotations     map[string]string
}

func ExtractAnnotatedStatements added in v0.3.1

func ExtractAnnotatedStatements(path string, mediaType string) ([]*AnnotatedStatement, error)

func ExtractStatementsFromIndex added in v0.3.1

func ExtractStatementsFromIndex(idx v1.ImageIndex, mediaType string) ([]*AnnotatedStatement, error)

type DockerDSSEExtension added in v0.2.0

type DockerDSSEExtension struct {
	TL *DockerTLExtension `json:"tl"`
}

type DockerTLExtension added in v0.2.0

type DockerTLExtension struct {
	Kind string `json:"kind"`
	Data any    `json:"data"`
}

type Envelope

type Envelope struct {
	PayloadType string       `json:"payloadType"`
	Payload     string       `json:"payload"`
	Signatures  []*Signature `json:"signatures"`
}

the following types are needed until https://github.com/secure-systems-lab/dsse/pull/61 is merged.

func ExtractEnvelopes added in v0.3.1

func ExtractEnvelopes(manifest *Manifest, predicateType string) ([]*Envelope, error)

func SignDSSE

func SignDSSE(ctx context.Context, payload []byte, signer dsse.SignerVerifier, opts *SigningOptions) (*Envelope, error)

SignDSSE signs a payload with a given signer and uploads the signature to the transparency log.

type Extension

type Extension struct {
	Kind string               `json:"kind"`
	Ext  *DockerDSSEExtension `json:"ext"`
}

type KeyMetadata

type KeyMetadata struct {
	ID            string     `json:"id"`
	PEM           string     `json:"key"`
	From          time.Time  `json:"from"`
	To            *time.Time `json:"to"`
	Status        string     `json:"status"`
	SigningFormat string     `json:"signing-format"`
	Distrust      bool       `json:"distrust,omitempty"`
}

type Keys

type Keys []*KeyMetadata

type KeysMap

type KeysMap map[string]*KeyMetadata

type Layer added in v0.2.0

type Layer struct {
	Statement   *intoto.Statement
	Layer       v1.Layer
	Annotations map[string]string
}

type LayoutResolver added in v0.3.1

type LayoutResolver struct {
	*Manifest
	*oci.ImageSpec
}

implementation of Resolver that closes over attestations from an oci layout.

func NewOCILayoutResolver added in v0.3.1

func NewOCILayoutResolver(src *oci.ImageSpec) (*LayoutResolver, error)

func (*LayoutResolver) Attestations added in v0.3.1

func (r *LayoutResolver) Attestations(_ context.Context, predicateType string) ([]*Envelope, error)

func (*LayoutResolver) ImageDescriptor added in v0.3.1

func (r *LayoutResolver) ImageDescriptor(_ context.Context) (*v1.Descriptor, error)

func (*LayoutResolver) ImageName added in v0.3.1

func (r *LayoutResolver) ImageName(_ context.Context) (string, error)

func (*LayoutResolver) ImagePlatform added in v0.3.1

func (r *LayoutResolver) ImagePlatform(_ context.Context) (*v1.Platform, error)

type Manifest added in v0.2.0

type Manifest struct {
	OriginalDescriptor *v1.Descriptor
	OriginalLayers     []*Layer

	// accumulated during signing
	SignedLayers []*Layer
	// details of subject image
	SubjectName       string
	SubjectDescriptor *v1.Descriptor
}
Example
package main

import (
	"context"
	"time"

	"github.com/docker/attest/pkg/attestation"
	"github.com/docker/attest/pkg/oci"
	"github.com/docker/attest/pkg/signerverifier"

	v1 "github.com/google/go-containerregistry/pkg/v1"

	intoto "github.com/in-toto/in-toto-golang/in_toto"
	"github.com/in-toto/in-toto-golang/in_toto/slsa_provenance/common"
)

func main() {
	// configure signerverifier
	// local signer (unsafe for production)
	signer, err := signerverifier.GenKeyPair()
	if err != nil {
		panic(err)
	}
	// example using AWS KMS signer
	// aws_arn := "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012"
	// aws_region := "us-west-2"
	// signer, err := signerverifier.GetAWSSigner(cmd.Context(), aws_arn, aws_region)

	// configure signing options
	opts := &attestation.SigningOptions{
		SkipTL: true, // skip trust logging to a transparency log
	}

	ref := "docker/image-signer-verifier:latest"

	digest, err := v1.NewHash("sha256:da8b190665956ea07890a0273e2a9c96bfe291662f08e2860e868eef69c34620")
	if err != nil {
		panic(err)
	}
	desc := &v1.Descriptor{
		Digest:    digest,
		Size:      1234,
		MediaType: "application/vnd.oci.image.manifest.v1+json",
	}

	// the in-toto statement to be signed
	statement := &intoto.Statement{
		StatementHeader: intoto.StatementHeader{
			PredicateType: attestation.VSAPredicateType,
			Subject:       []intoto.Subject{{Name: ref, Digest: common.DigestSet{digest.Algorithm: digest.Hex}}},
			Type:          intoto.StatementInTotoV01,
		},
		Predicate: attestation.VSAPredicate{
			Verifier: attestation.VSAVerifier{
				ID: "test-verifier",
			},
			TimeVerified:       time.Now().UTC().Format(time.RFC3339),
			ResourceURI:        "some-uri",
			Policy:             attestation.VSAPolicy{URI: "some-uri"},
			VerificationResult: "PASSED",
			VerifiedLevels:     []string{"SLSA_BUILD_LEVEL_1"},
		},
	}

	// create a new manifest to hold the attestation
	manifest, err := attestation.NewManifest(desc)
	if err != nil {
		panic(err)
	}

	// sign and add the attestation to the manifest
	err = manifest.Add(context.Background(), signer, statement, opts)
	if err != nil {
		panic(err)
	}

	output, err := oci.ParseImageSpecs("docker/image-signer-verifier-referrers:latest")
	if err != nil {
		panic(err)
	}

	// save the manifest to the registry as a referrers artifact
	artifacts, err := manifest.BuildReferringArtifacts()
	if err != nil {
		panic(err)
	}
	err = oci.SaveImagesNoTag(artifacts, output)
	if err != nil {
		panic(err)
	}
}

func FetchManifest added in v0.3.1

func FetchManifest(ctx context.Context, image string, platform *v1.Platform) (*Manifest, error)

func ManifestsFromIndex added in v0.3.1

func ManifestsFromIndex(index v1.ImageIndex) ([]*Manifest, error)

ManifestsFromIndex extracts all attestation manifests from an index.

func NewManifest added in v0.3.1

func NewManifest(subject *v1.Descriptor) (*Manifest, error)

NewManifest creates a new attestation manifest from a descriptor.

func (*Manifest) Add added in v0.3.1

func (manifest *Manifest) Add(ctx context.Context, signer dsse.SignerVerifier, statement *intoto.Statement, opts *SigningOptions) error

func (*Manifest) BuildImage added in v0.3.1

func (manifest *Manifest) BuildImage(options ...func(*ManifestImageOptions) error) (v1.Image, error)

build an image with signed attestations, optionally replacing existing layers with signed layers.

func (*Manifest) BuildReferringArtifacts added in v0.2.0

func (manifest *Manifest) BuildReferringArtifacts() ([]v1.Image, error)

build an image per attestation (layer) suitable for use as Referrers.

type ManifestImageOptions added in v0.2.0

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

type MockRegistryResolver added in v0.3.1

type MockRegistryResolver struct {
	Subject      *v1.Descriptor
	ImageNameStr string
	*MockResolver
}

func (*MockRegistryResolver) ImageDescriptor added in v0.3.1

func (r *MockRegistryResolver) ImageDescriptor(_ context.Context) (*v1.Descriptor, error)

func (*MockRegistryResolver) ImageName added in v0.3.1

func (r *MockRegistryResolver) ImageName(_ context.Context) (string, error)

type MockResolver added in v0.3.1

type MockResolver struct {
	Envs []*Envelope
}

func (MockResolver) Attestations added in v0.3.1

func (r MockResolver) Attestations(_ context.Context, _ string) ([]*Envelope, error)

func (MockResolver) ImageDescriptor added in v0.3.1

func (r MockResolver) ImageDescriptor(_ context.Context) (*v1.Descriptor, error)

func (MockResolver) ImageName added in v0.3.1

func (r MockResolver) ImageName(_ context.Context) (string, error)

func (MockResolver) ImagePlatform added in v0.3.1

func (r MockResolver) ImagePlatform(_ context.Context) (*v1.Platform, error)

type Options added in v0.3.1

type Options struct {
	NoReferrers   bool
	Attach        bool
	ReferrersRepo string
}

type ReferrersResolver added in v0.3.1

type ReferrersResolver struct {
	oci.ImageDetailsResolver
	// contains filtered or unexported fields
}

func NewReferrersResolver added in v0.3.1

func NewReferrersResolver(src oci.ImageDetailsResolver, options ...func(*ReferrersResolver) error) (*ReferrersResolver, error)

func (*ReferrersResolver) Attestations added in v0.3.1

func (r *ReferrersResolver) Attestations(ctx context.Context, predicateType string) ([]*Envelope, error)

type RegistryResolver added in v0.3.1

type RegistryResolver struct {
	*oci.RegistryImageDetailsResolver
	*Manifest
}

func NewRegistryResolver added in v0.3.1

func NewRegistryResolver(src *oci.RegistryImageDetailsResolver) (*RegistryResolver, error)

func (*RegistryResolver) Attestations added in v0.3.1

func (r *RegistryResolver) Attestations(ctx context.Context, predicateType string) ([]*Envelope, error)

type Resolver added in v0.3.1

type Resolver interface {
	oci.ImageDetailsResolver
	Attestations(ctx context.Context, mediaType string) ([]*Envelope, error)
}

type Signature

type Signature struct {
	KeyID     string     `json:"keyid"`
	Sig       string     `json:"sig"`
	Extension *Extension `json:"extension,omitempty"`
}

type SigningOptions added in v0.1.5

type SigningOptions struct {
	// don't log to the configured transparency log
	SkipTL bool
}

type VSAInputAttestation added in v0.1.3

type VSAInputAttestation struct {
	Digest    map[string]string `json:"digest"`
	MediaType string            `json:"mediaType"`
}

type VSAPolicy added in v0.1.3

type VSAPolicy struct {
	URI              string            `json:"uri,omitempty"`
	Digest           map[string]string `json:"digest"`
	DownloadLocation string            `json:"downloadLocation,omitempty"`
}

type VSAPredicate added in v0.1.3

type VSAPredicate struct {
	Verifier           VSAVerifier           `json:"verifier"`
	TimeVerified       string                `json:"timeVerified"`
	ResourceURI        string                `json:"resourceUri"`
	Policy             VSAPolicy             `json:"policy"`
	InputAttestations  []VSAInputAttestation `json:"inputAttestations,omitempty"`
	VerificationResult string                `json:"verificationResult"`
	VerifiedLevels     []string              `json:"verifiedLevels"`
}

type VSAVerifier added in v0.1.3

type VSAVerifier struct {
	ID string `json:"id"`
}

type VerifyOptions added in v0.1.5

type VerifyOptions struct {
	Keys   []*KeyMetadata `json:"keys"`
	SkipTL bool           `json:"skip_tl"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL