add oci bundle spec

[bdehamer]

Closes: #3577

Summary

Adds a new spec doc which describes the scheme for publishing/retrieving Sigstore bundles to/from an OCI registry.

Rendered version

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 40.41%. Comparing base (2ef6022) to head (8892db3).
Report is 60 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3622      +/-   ##
==========================================
+ Coverage   40.10%   40.41%   +0.31%     
==========================================
  Files         155      155              
  Lines       10044    10087      +43     
==========================================
+ Hits         4028     4077      +49     
+ Misses       5530     5517      -13     
- Partials      486      493       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[cpanato]

great work here!

lgtm

[haydentherapper]

Looks great, thanks for contributing this!

[vaikas]

Just jotting this down here. Wondering if it would be useful to have a an example out there demonstrating a fully compliant spec?

[bdehamer]

I don't know that I want to reference this in the spec, but I do have an example at index.docker.io/bdehamer/hello:latest.

You can poke at this with the oras CLI. Look-up an referring artifacts:

oras discover index.docker.io/bdehamer/hello:latest

Discovered 1 artifact referencing latest
Digest: sha256:01b2325c7cae9939e4484061c37d36e0b95fb3f5e66f80ff924582ba5939e831

Artifact Type                                   Digest
application/vnd.dev.sigstore.bundle.v3.0+json   sha256:30bb112189b0070d8c440fb0c9ef13d4ff25014ccc64d90e5839f90b99c81779

Fetch the bundle manifest:

oras manifest fetch index.docker.io/bdehamer/hello@sha256:30bb112189b0070d8c440fb0c9ef13d4ff25014ccc64d90e5839f90b99c81779

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.dev.sigstore.bundle.v3.0+json",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2,
    "data": "e30="
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar",
      "digest": "sha256:0e6245a3f020384b3b10aa2f4fe838ce5e87a71038e710938875cc22d6adb917",
      "size": 10097,
      "annotations": {
        "org.opencontainers.image.title": "bundle.json"
      }
    }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "digest": "sha256:01b2325c7cae9939e4484061c37d36e0b95fb3f5e66f80ff924582ba5939e831",
    "size": 855
  },
  "annotations": {
    "dev.sigstore.bundle.predicateType": "https://slsa.dev/provenance/v1",
    "dev.sigstore.cosign.bundle.content": "dsse-envelope",
    "org.opencontainers.image.created": "2024-03-28T19:44:17Z"
  }
}

Fetch the bundle:

oras blob fetch index.docker.io/bdehamer/hello@sha256:0e6245a3f020384b3b10aa2f4fe838ce5e87a71038e710938875cc22d6adb917 --output -

{"mediaType":"application/vnd.dev.sigstore.bundle.v3.0+json"...}

[sudo-bmitch]

Love seeing the progress from sigstore on this! Some general feedback from the OCI perspective on this.

[sudo-bmitch]

Other fields I'd recommend including are the creation/signing date, and the identity of the signer. This is useful for quickly finding the most recently signed content from a trusted identity. OCI already has an annotation for the creation date that I'd recommend reusing: org.opencontainers.image.created.

[bdehamer]

@sudo-bmitch I like the idea of an annotation to identify the signer. Is there an pre-defined annotation key you'd recommend for this or should we define our own?

[sudo-bmitch]

I'm not aware of anything predefined, so making your own under the sigstore namespace makes sense to me.

[bdehamer]

Update the list of recommended annotations to include:

• org.opencontainers.image.created

[rchincha]

Ideally, would stick to OCI annotations - just makes it more portable. If you expect images and their signatures to move around, then a arbitrary registry implementation doesn't need to know about dev.sigstore.* namespace.

[sudo-bmitch]

For the signer details, the concept I was thinking of would include details used by certificate-identity, certificate-oidc-issuer, etc, so that a cosign verify command could quickly find the matching signature. That could end up being more than one annotation.

[haydentherapper]

I'd worry that would get used to build a verification policy rather than that policy be provided from the caller. I also don't want the annotations to become a duplicate of what's in the envelope/certificate.

[sudo-bmitch]

There may be multiple signatures uploaded for a given digest (hundreds if someone has reproducible builds or runs something daily). Ideally, each of those wouldn't need to be pulled separately to find the one matching the verification policy the user is asking for. This would be an API efficiency, and security would still be provided by validating the envelope/certificate itself.

[bdehamer]

If we have multiple attestations for the same digest (some recurring, reproducible build) it's likely that the predicate, cert identity, OIDC issuer will be the same for all of them -- surfacing that info as an annotation probably isn't gonna be that useful.

I was chatting w/ @codysoyland who is working on bundle support in the policy-controller and his primary requirement was that the predicate-type be available (as this is a required part of the policy definition).

At this point, I'm inclined to trim the specified annotation list to just the content, predicateType and the created values. Leaving open the option to add more annotations in the future as specific use cases arise.

[haydentherapper]

I'd worry that would get used to build a verification policy rather than that policy be provided from the caller. I also don't want the annotations to become a duplicate of what's in the envelope/certificate.

[haydentherapper]

@bdehamer, great work on this, LGTM! I'll leave it open til mid next week in case there's any other comments.

[haydentherapper]

Merging now, thanks all for the discussion, and thanks @bdehamer for authoring the spec!