Chore: Refactor how we handle verification materials

[woodruffw]

Conceptually, there are three mandatory pieces of sigstore verification material, and one optional piece:

• The artifact's SHA256 hash (naive datatype: str)
• The artifact's signature (naive datatype: bytes, or str if base64-encoded)
• The artifact's PEM-formatted signing certificate (naive datatype: str)
• (Optionally) the offline Rekor entry (JSON, deserialized to RekorBundle or RekorEntry in #247)

Right now, the verify API takes these as independent parameters, along with some other options (which will grow over time, as we support different configurations and verification policies):

    def verify(
        self,
        input_: bytes,
        certificate: bytes,
        signature: bytes,
        expected_cert_email: Optional[str] = None,
        expected_cert_oidc_issuer: Optional[str] = None,
        offline_rekor_entry: Optional[RekorEntry] = None,
    ) -> VerificationResult:

This is going to become unwieldly, so we should probably rethink the top-level API here.

Related:

• #247
• The "sigstore bundle" design in https://github.com/sigstore/cosign/pull/2204, which will contain most (all?) of these inputs

[woodruffw]

One thought: a top-level verify API like this might be nice:

def verify(bundle: VerificationBundle, options: VerificationOptions) -> VerificationResult

...where VerificationBundle could be constructed from a Sigstore bundle, from individual inputs, etc., and VerificationOptions could contain settings for the expected OIDC issuer, etc.

[woodruffw]

More thinking out loud: VerificationBundle should be correct by construction, meaning that it should be impossible to create a VerificationBundle that includes an offline RekorEntry without checking that entry's relevancy to the rest of the verification materials.

[woodruffw]

Temporarily blocked on #289 and #288, since we want this functionality in before a more general refactor.

[mayaCostantini]

Was a verification bundle schema already discussed somewhere? I would be interested in taking up this issue if it has no assignee yet.

[di]

@mayaCostantini Yes, here: https://github.com/sigstore/cosign/issues/2131

[woodruffw]

Additionally, the protobuf definition for the bundle is being developed here: https://github.com/sigstore/protobuf-specs

[woodruffw]

I'm currently working on this refactor in ww/verify-api-refactor, although those changes won't include the bundle itself -- it'll only concern cleaning up the API surface and making it easier to consume bundles.

[mayaCostantini]

@di @woodruffw Thank you for the info, I will look into it soon :+1:

[woodruffw]

Working on this in #299.