docs: update README.md

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

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)
+}