Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add oci bundle spec #3622

Merged
merged 8 commits into from
Apr 5, 2024
Merged

add oci bundle spec #3622

Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5f5cd94
add oci bundle spec
bdehamer Mar 22, 2024
701fcc3
Update specs/BUNDLE_SPEC.md
bdehamer Mar 26, 2024
c92d9c3
Update specs/BUNDLE_SPEC.md
bdehamer Mar 26, 2024
5d63cb1
Update specs/BUNDLE_SPEC.md
bdehamer Mar 26, 2024
c12d0c1
clarify annotation scheme
bdehamer Mar 26, 2024
c7042a1
add signer annotation
bdehamer Mar 26, 2024
8b769d5
update bundle media type
bdehamer Mar 28, 2024
8892db3
remove reference to signer annotation
bdehamer Mar 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
320 changes: 320 additions & 0 deletions specs/BUNDLE_SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,320 @@
# Cosign Bundle Specification

This document aims to describe how `cosign` attaches Sigstore attestation
[bundles](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto)
to container images.

The goal is to specify the behavior well enough to promote other implementations
and enable interoperability. Attestations attached with `cosign` should be
retrievable in other tools, and vice-versa.

This document focuses on the layout of attestations within an
[OCI Image Manifest V1.1](https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md)
object.

This document makes no assumptions about the contents of the Sigstore bundle.
Any attestation which can be represented as a Sigstore bundle (message
signatures, DSSE-wrapped in-toto statements, etc) can be attached to a container
image stored in an OCI registry.

Multiple Attestations may be "attached" to one image.

Attestations attached to a container image are generally assumed to refer to
that image in some way.

## Storage

The approach for storing Sigstore bundles in an OCI registry follows the
[guidelines for artifact usage](https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage)
in the OCI
[image spec](https://github.com/opencontainers/image-spec/blob/main/README.md).

### Publishing

First, the bundle itself is stored in its JSON-serialized form as a blob in the
registry:

```
POST /v2/foo/blobs/uploads/?digest=cafed00d...
Content-Type: application/octet-stream

{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json", ...}
```

In this example “foo” is the name of the repository within the registry to which
the artifact is being uploaded. The digest included as part of the POST is the
hex-encoded SHA-256 digest of the raw bytes of the bundle itself.

Once the blob has been created, the next step is to create a manifest that
associates the bundle blob with the image it describes:

```
PUT /v2/foo/manifests/sha256:badf00d...
Content-Type: application/vnd.oci.image.manifest.v1+json

{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"schemaVersion": 2,
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"config": {
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa3...",
"size": 2
},
"layers": [
{
"digest": "sha256:cafed00d...",
"mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"size": 4971
}
],
"subject": {
"digest": "sha256:c00010ff...",
"mediaType": "application/vnd.oci.image.index.v1+json"
}
}
```

The manifest must have an `artifactType` field which identifies the type of the
artifact being referenced -- in this case, it's the Sigstore bundle media type.

The `layers` collection will have a single entry that points to the bundle's
blob by referencing its size, digest and media type.

The `subject` field associates this artifact with some other artifact which
already exists in this repository (in this case, an image with the digest
`c00010ff`)

Sigstore bundles don't require any additional configuration data, so the
`config` field references the
[empty descriptor](https://github.com/opencontainers/image-spec/blob/f5f87016de46439ccf91b5381cf76faaae2bc28f/manifest.md#guidance-for-an-empty-descriptor).

At this point, any registry which supports the
[referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)
will automatically associate this manifest with the listed subject and make it
available in the referrers index for that subject.

If the registry DOES NOT support the referrers API, a referrers list must be
manually created/updated using the
[referrers tag scheme](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#referrers-tag-schema).

```
PUT /v2/foo/manifests/sha256-c00010ff...
Content-Type: application/vnd.oci.image.index.v1+json

{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.index.v1+json",
"manifests": [
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:badf00d..",
"size": 779,
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json"
}
]
}
```

This index is uploaded with a tag that references the digest of the image to
which all of the listed artifacts are associated. Each of the items in the
`manifests` collection points to some other related artifact.

### Retrieval

When a client wants to locate Sigstore bundles which may be associated with a
given image, they would first make a request to
[referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)
with the image's digest:

```
GET /v2/foo/referrers/sha256:c000100ff...
```

A `404 Not Found` response indicates that the registry does not support the
referrers API and the referrers tag scheme should be used as a fallback:

```
GET /v2/foo/manifests/sha256-c000100ff...
```

A `404` here would indicate that there are no artifacts associated with the
image.

Assuming there are artifacts present, one of the two above calls will return an
image index listing the artifacts which have been associated with the specified
image:

```
{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.index.v1+json",
"manifests": [
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:badf00d..",
"size": 779,
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json"
}
]
}
```

From this the client can identify any Sigstore bundles by looking at the
`artifactType` field.

Using the `digest` listed in the image index, the next step is to retrieve the
manifest for the bundle:

```
GET /v2/foo/manifests/sha256:badf00d..
```

```
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"schemaVersion": 2,
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"config": {
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa3...",
"size": 2
},
"layers": [
{
"digest": "sha256:cafed00d...",
"mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"size": 4971
}
],
"subject": {
"digest": "sha256:c00010ff...",
"mediaType": "application/vnd.oci.image.index.v1+json"
}
}
```

The final step is to use the `digest` from the first of the `layers` to retrieve
the bundle blob:

```
GET /v2/foo/blobs/uploads/?digest=cafed00d...
```

```
{
"mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"verificationMaterial": {...},
"messageSignature": {...}
}
```

## Annotations

For any given image, there may be any number of attached attestation bundles.
When there are multiple Sigstore bundles associated with an image it may be
difficult to identify which artifact is which in the image index:

```json
{
"mediaType": "application/vnd.oci.image.index.v1+json",
"schemaVersion": 2,
"manifests": [
{
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"digest": "sha256:facefeed",
"mediaType": "application/vnd.oci.image.manifest.v1+json"
},
{
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"digest": "sha256:d0d0caca",
"mediaType": "application/vnd.oci.image.manifest.v1+json"
}
]
}
```

To help disambiguate attestations, clients may add annotations to the items in
the `manifests` list which indicate what is contained within each bundle and
when it was created:

- `dev.sigstore.bundle.content` - Must be one "message-signature" or
"dsse-envelope" and should match the type of content embedded in the Sigstore
bundle.
bdehamer marked this conversation as resolved.
Show resolved Hide resolved
- `dev.sigstore.bundle.predicateType` - When the bundle contains a DSSE-wrapped
in-toto statement, the statement's predicate can be reflected here.
- `dev.sigstore.bundle.signer` - Identity of the application which generated the
attestation bundle.
- `org.opencontainers.image.created` - Date and time when the attestation bundle
was created, conforming to
[RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) (this is one of
the pre-defined annotation keys identified in the
[OCI spec](https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys)).

These annotations should be included as part of the bundle manifest:

```json
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"schemaVersion": 2,
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"annotations": {
"dev.sigstore.bundle.content": "dsse-envelope",
"dev.sigstore.bundle.predicateType": "https://slsa.dev/provenance/v1",
"dev.sigstore.bundle.signer": "cosign/v2.2.3 (darwin; arm64)",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

bdehamer marked this conversation as resolved.
Show resolved Hide resolved
"org.opencontainers.image.created": "2024-03-08T18:18:20.406Z"
},
"config": {
"mediaType": "application/vnd.oci.empty.v1+json",
"digest": "sha256:44136fa3...",
"size": 2
},
"layers": [
{
"digest": "sha256:cafed00d...",
"mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"size": 4971
}
],
"subject": {
"digest": "sha256:c00010ff...",
"mediaType": "application/vnd.oci.image.index.v1+json"
}
}
```

Registries which support the referrers API will automatically propagate any
annotations on the referring manifest to the index. For registries which do NOT
support the referrers API, the annotations should be added to the index when it
is updated manually. In either case, the end result should look something like
the following:

```json
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@bdehamer bdehamer Mar 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"...}

{
"mediaType": "application/vnd.oci.image.index.v1+json",
"schemaVersion": 2,
"manifests": [
{
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"digest": "sha256:facefeed",
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"annotations": {
"dev.sigstore.bundle.content": "message-signature",
"dev.sigstore.bundle.signer": "cosign/v2.2.3 (darwin; arm64)",
"org.opencontainers.image.created": "2024-03-07T18:17:38.000Z"
}
},
{
"artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
"digest": "sha256:d0d0caca",
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"annotations": {
"dev.sigstore.bundle.content": "dsse-envelope",
"dev.sigstore.bundle.predicateType": "https://slsa.dev/provenance/v1",
"dev.sigstore.bundle.signer": "cosign/v2.2.3 (darwin; arm64)",
"org.opencontainers.image.created": "2024-03-08T18:18:20.406Z"
}
}
]
}
```
Loading