feat: Create interface for verifiers

[laurentsimon]

This PR supersedes #184.
This PR attempts to create a better framework to support new builders. It starts simple:

• Create an interface that each verifier will instantiate. The interface is defined in register/register.go:

type SLSAVerifier interface {
	// Match matches a BuilderID.
	Match(builderID string) bool

	// Verify verifies a provenance.
	Verify(ctx context.Context,
		provenance []byte, artifactHash string,
		provenanceOpts *options.ProvenanceOpts,
		builderOpts *options.BuilderOpts,
	) ([]byte, string, error)
}

• Each verifier registers its instantiation via register.RegisterVerifier(): see verifiers/internal/gcb/verifier.go and verifiers/internal/gha/verifier.go.
• If the user provides a builder in the CLI, we search for a verifier that supports the builderID using v.Match(builderID). See verifiers/verifier.go
• If no builderID is provided by the user, we default to the GHA native builders, see verifiers/verifier.go. I'm doing this to avoid breaking previous version, but we can change this behavior later. We could also check whether builder supports particular repositories: GCB supports GitLab, whereas GHA builders do not.
• Add verification of material source URI and configSource URI, and that they match (hardening)

I also moved errors to their own errors folder.

Everything else is moving files around and renaming calls to account for files that have been moved around.

[asraa]

First question:
I can base #147

on top of this, but the problem is that blob verification and container verification have different APIs. Container verification takes an image reference, whereas blobs require the provenance bytes.

Either we have some sort of struct with type information capturing the object to verify, or we have two possibilities for each builder VerifyBlob and VerifyOCI. @ianlewis

[laurentsimon]

We can create a different API, as you say: VerifyImage(), VerifyArtifact() for the interface. Would that work?

I'm thinking of having a function called HasSupport(branch | tag | trigger | etc), as well. We can discuss this further in a follow-up PR, though.

[asraa]

We can create a different API, as you say: VerifyImage(), VerifyArtifact() for the interface. Would that work?

That SGTM

In addition, can we expose a SLSA Level SLSALevel() on each builder? GCB builders are v2, and GHA reusble workflows are v3, we should support exposing the information.

[laurentsimon]

We can create a different API, as you say: VerifyImage(), VerifyArtifact() for the interface. Would that work?

That SGTM

In addition, can we expose a SLSA Level SLSALevel() on each builder? GCB builders are v2, and GHA reusable workflows are v3, we should support exposing the information.

Yes we can. Level 3 is a little subjective, so I was hesitant to do that. But maybe that's a good way to get the ball rolling.

[laurentsimon]

comment from @ianlewis:

aside: I'm curious. Remind me again why these flags are copied to local variables? Also, why we need a special isFlagPassed function?

reply from @laurentsimon

I don't think I found a way to have an option be a pointer to a string, and for the pointer to be nil if the user does not provide the option. If that's possible, I can update the code.

[asraa]

Yeah, I believe StringVar is as close as you can get, and the best that can be done is use a default empty string. but problem is that empty string doesn't necessarily mean no value.

In this case we can document that? empty tags passed in mean no tag verification.

[laurentsimon]

done. Added a comment.

[laurentsimon]

TODO: support VerifyWorkflowIdentity(workflow, nil, source)
/cc @ianlewis

[asraa]

TBD but we may want to move this under the Verifier type and have the signature take in the PublicKeyOrCertificate.

In the case of GCB/other keys, they will have different "identity" guarantees in the public key or cert.

Fine for now since this is just a refactor. It won't break more API to add a new method to the Verifier type

[laurentsimon]

Let me try to make a small change move this function under builderOpt.

[laurentsimon]

mhh, will leave as-is for now since VerifyWorkflowIdentity() is called within the main entry point VerifyArtifact(), so there's no need to expose it directly in this PR. Can refactor more in follow-up PRs