From 20fc3729888c7b8d6283fa45b217bc94c384bad7 Mon Sep 17 00:00:00 2001
From: mrjoelkamp <joel.kamp@docker.com>
Date: Mon, 29 Apr 2024 13:43:50 -0500
Subject: [PATCH] docs: update README.md

---
 README.md            | 62 ++++++++++++++++++++++++++++++++++++++++++++
 pkg/attest/verify.go | 15 +++++++++++
 2 files changed, 77 insertions(+)

diff --git a/README.md b/README.md
index 792a1e8..797896e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,64 @@
 # attest
 Library to create, verify, and evaluate policy for attestations on container images
+
+# usage
+## signing attestations
+
+
+## verifying attestations
+1. Create a TUF client
+    * using OCI registry for TUF
+        ```go
+        tufClient, err := tuf.NewTufClient(embed.DefaultRoot, "/.docker/tuf", "docker/tuf-metadata:latest", "docker/tuf-targets")
+        ```
+    * using HTTPS for TUF
+        ```go
+        tufClient, err := tuf.NewTufClient(embed.DefaultRoot, "/.docker/tuf", "https://docker.github.io/tuf/metadata", "https://docker.github.io/tuf/targets")
+        ```
+
+1. Configure an attestation resolver
+    * using OCI registry
+        ```go
+        var resolver oci.AttestationResolver
+        resolver = &oci.RegistryResolver{
+			Image:    image,    // path to image index in OCI registry containing image attestations (e.g. docker/nginx:latest)
+			Platform: platform, // platform of subject image (image that attestations are being verified against)
+		}
+        ```
+    * using local OCI layout
+        ```go
+        var resolver oci.AttestationResolver
+        resolver = &oci.OCILayoutResolver{
+			Path:     path,     // file path to OCI layout containing image attestations (e.g. /myimage)
+			Platform: platform, // platform of subject image (image that attestations are being verified against)
+		}
+        ```
+
+2. Configure policy options
+    ```go
+    opts := &policy.PolicyOptions{
+		TufClient:       tufClient,
+		LocalTargetsDir: "/.docker/policy", // location to store policy files downloaded from TUF
+		LocalPolicyDir:  "", // overrides TUF policy for local policy files
+	}
+    ```
+
+3. Verify attestations
+    ```go
+    policy, err := attest.Verify(ctx, opts, resolver)
+    if err != nil {
+        return false // failed policy or attestation signature verification
+    }
+    if policy {
+        return true // passed policy
+    }
+    return true // no policy for image
+    ```
+
+## mirroring TUF repositories
+TODO: write content for this outline
+### mirroring TUF metadata to OCI
+#### delegated metadata
+### mirroring TUF targets to OCI
+#### delegated targets
+### using `go-tuf` OCI registry client
diff --git a/pkg/attest/verify.go b/pkg/attest/verify.go
index b23c1ca..52f05c6 100644
--- a/pkg/attest/verify.go
+++ b/pkg/attest/verify.go
@@ -38,3 +38,18 @@ func VerifyAttestations(ctx context.Context, resolver oci.AttestationResolver, f
 
 	return nil
 }
+
+func Verify(ctx context.Context, opts *policy.PolicyOptions, resolver oci.AttestationResolver) (policyFound bool, err error) {
+	policyFiles, err := policy.ResolvePolicy(ctx, resolver, opts)
+	if err != nil {
+		return false, fmt.Errorf("failed to resolve policy: %w", err)
+	}
+
+	// no policy for image -> success
+	if policyFiles == nil {
+		return false, nil
+	}
+
+	// policy found -> verify
+	return true, VerifyAttestations(ctx, resolver, policyFiles)
+}