docs: first cut of a new README (#99)

Lots of this is taken from image-signer-verifier's README. The stuff on
policy is all new.

Co-authored-by: James Carnegie <kipz@users.noreply.github.com>

pkg/attest/example_verify_test.go

@@ -48,11 +48,11 @@ func ExampleVerify_remote() {
 		PolicyId:        "",                                       // set to ignore policy mapping and select a policy by id
 	}
 
-	// verify attestations
 	src, err := oci.ParseImageSpec(image, oci.WithPlatform(platform))
 	if err != nil {
 		panic(err)
 	}
+	// verify attestations
 	result, err := attest.Verify(context.Background(), src, opts)
 	if err != nil {
 		panic(err)

pkg/attestation/example_attestation_manifest_test.go

@@ -0,0 +1,87 @@
+package attestation_test
+
+import (
+	"context"
+	"time"
+
+	"github.com/docker/attest/pkg/attest"
+	"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"
+	intoto "github.com/in-toto/in-toto-golang/in_toto"
+	"github.com/in-toto/in-toto-golang/in_toto/slsa_provenance/common"
+)
+
+func ExampleAttestationManifest() {
+	// 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 := attest.NewAttestationManifest(desc)
+	if err != nil {
+		panic(err)
+	}
+
+	// sign and add the attestation to the manifest
+	err = manifest.AddAttestation(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
+	err = mirror.SaveReferrers(manifest, output)
+	if err != nil {
+		panic(err)
+	}
+}