docs: update examples in README.md

pkg/attest/example_sign.go

@@ -0,0 +1,78 @@
+package attest
+
+import (
+	"context"
+
+	"github.com/docker/attest/pkg/attestation"
+	"github.com/docker/attest/pkg/mirror"
+	"github.com/docker/attest/pkg/oci"
+	"github.com/docker/attest/pkg/signerverifier"
+	v1 "github.com/google/go-containerregistry/pkg/v1"
+	"github.com/google/go-containerregistry/pkg/v1/empty"
+	"github.com/google/go-containerregistry/pkg/v1/mutate"
+)
+
+func ExampleSign_remote() {
+	// 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 := &SigningOptions{
+		Replace: true, // replace unsigned intoto statements with signed intoto attestations, otherwise leave in place
+	}
+
+	// configure VSA options (optional)
+	slsaBuildLevel := "3"
+	slsaPolicyUri := "https://docker.com/attest/policy"
+	slsaVerifierId := "https://docker.com"
+	opts.VSAOptions = &attestation.VSAOptions{
+		BuildLevel: "SLSA_BUILD_LEVEL_" + slsaBuildLevel,
+		PolicyURI:  slsaPolicyUri,
+		VerifierID: slsaVerifierId,
+	}
+
+	// load image index with unsigned attestation-manifests
+	ref := "docker/image-signer-verifier:latest"
+	att, err := oci.AttestationIndexFromRemote(ref)
+	if err != nil {
+		panic(err)
+	}
+	// example for local image index
+	// path := "/myimage"
+	// att, err := oci.AttestationIndexFromLocal(path)
+
+	// sign attestations
+	signedImageIndex, err := Sign(context.Background(), att.Index, signer, opts)
+	if err != nil {
+		panic(err)
+	}
+
+	// push image index with signed attestation-manifests
+	err = mirror.PushToRegistry(signedImageIndex, ref)
+	if err != nil {
+		panic(err)
+	}
+	// output image index to filesystem (optional)
+	path := "/myimage"
+	idx := v1.ImageIndex(empty.Index)
+	idx = mutate.AppendManifests(idx, mutate.IndexAddendum{
+		Add: signedImageIndex,
+		Descriptor: v1.Descriptor{
+			Annotations: map[string]string{
+				oci.OciReferenceTarget: att.Name,
+			},
+		},
+	})
+	err = mirror.SaveAsOCILayout(idx, path)
+	if err != nil {
+		panic(err)
+	}
+}

pkg/attest/example_verify.go

@@ -0,0 +1,69 @@
+package attest
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+
+	"github.com/docker/attest/internal/embed"
+	"github.com/docker/attest/pkg/oci"
+	"github.com/docker/attest/pkg/policy"
+	"github.com/docker/attest/pkg/tuf"
+)
+
+func createTufClient(outputPath string) (*tuf.TufClient, error) {
+	// using oci tuf metadata and targets
+	metadataURI := "regsitry-1.docker.io/docker/tuf-metadata:latest"
+	targetsURI := "regsitry-1.docker.io/docker/tuf-targets"
+	// example using http tuf metadata and targets
+	// metadataURI := "https://docker.github.io/tuf-staging/metadata"
+	// targetsURI := "https://docker.github.io/tuf-staging/targets"
+
+	return tuf.NewTufClient(embed.DefaultRoot, outputPath, metadataURI, targetsURI)
+}
+
+func ExampleVerify_remote() {
+	// create a tuf client
+	home, err := os.UserHomeDir()
+	if err != nil {
+		panic(err)
+	}
+	tufOutputPath := filepath.Join(home, ".docker", "tuf")
+	tufClient, err := createTufClient(tufOutputPath)
+	if err != nil {
+		panic(err)
+	}
+
+	// create a resolver for remote attestations
+	image := "regsitry-1.docker.io/notary:server"
+	platform := "linux/amd64"
+	resolver := &oci.RegistryResolver{
+		Image:    image,    // path to image index in OCI registry containing image attestations
+		Platform: platform, // platform of subject image (image that attestations are being verified against)
+	}
+	// example using a local resolver
+	// path := "/myimage"
+	// platform := "linux/amd64"
+	// resolver := &oci.OCILayoutResolver{
+	// 	Path:     path,     // file path to OCI layout containing image attestations
+	// 	Platform: platform, // platform of subject image (image that attestations are being verified against)
+	// }
+
+	// configure policy options
+	opts := &policy.PolicyOptions{
+		TufClient:       tufClient,
+		LocalTargetsDir: filepath.Join(home, ".docker", "policy"), // location to store policy files downloaded from TUF
+		LocalPolicyDir:  "",                                       // overrides TUF policy for local policy files if set
+	}
+
+	// verify attestations
+	policy, err := Verify(context.Background(), opts, resolver)
+	if err != nil {
+		panic(err) // failed policy or attestation signature verification
+	}
+	if policy {
+		print("policy passed: %v\n", policy)
+		return // passed policy
+	}
+	// no policy for image
+}