attestation

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2024 License: Apache-2.0 Imports: 29 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 

func DSSEMediaType(predicateType string) (string, error)

func ToVSAResourceURI 

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

func UpdateIndexImages 

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 

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

func WithReplacedLayers 

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

func WithoutSubject 

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

Types

type AnnotatedStatement 

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

func ExtractAnnotatedStatements 

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

func ExtractStatementsFromIndex 

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

type DockerDSSEExtension 

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

type DockerTLExtension 

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 

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 

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

type LayoutResolver 

type LayoutResolver struct {
	*Manifest
	*oci.ImageSpec
}

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

func NewOCILayoutResolver 

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

func (*LayoutResolver) Attestations 

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

func (*LayoutResolver) ImageDescriptor 

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

func (*LayoutResolver) ImageName 

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

func (*LayoutResolver) ImagePlatform 

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

type Manifest 

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/attestation"
	"github.com/docker/attest/oci"
	"github.com/docker/attest/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)
	}
	ctx := context.Background()
	err = oci.SaveImagesNoTag(ctx, artifacts, output)
	if err != nil {
		panic(err)
	}
}

Output:

func FetchManifest 

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

func ManifestsFromIndex 

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

ManifestsFromIndex extracts all attestation manifests from an index.

func NewManifest 

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

NewManifest creates a new attestation manifest from a descriptor.

func (*Manifest) Add 

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

func (*Manifest) BuildImage 

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 

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

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

type ManifestImageOptions 

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

type MockRegistryResolver 

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

func (*MockRegistryResolver) ImageDescriptor 

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

func (*MockRegistryResolver) ImageName 

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

type MockResolver 

type MockResolver struct {
	Envs         []*Envelope
	Image        string
	PlatformFn   func() (*v1.Platform, error)
	DescriptorFn func() (*v1.Descriptor, error)
	ImangeNameFn func() (string, error)
}

func (MockResolver) Attestations 

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

func (MockResolver) ImageDescriptor 

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

func (MockResolver) ImageName 

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

func (MockResolver) ImagePlatform 

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

type Options 

type Options struct {
	NoReferrers   bool
	Attach        bool
	ReferrersRepo string
}

type ReferrersResolver 

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

func NewReferrersResolver 

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

func (*ReferrersResolver) Attestations 

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

type RegistryResolver 

type RegistryResolver struct {
	*oci.RegistryImageDetailsResolver
	*Manifest
}

func NewRegistryResolver 

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

func (*RegistryResolver) Attestations 

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

type Resolver 

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 

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

type VSAInputAttestation 

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

type VSAPolicy 

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

type VSAPredicate 

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 

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

type VerifyOptions 

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

Source Files

View all Source files

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.