1# Cosign Bundle Specification
2
3This document aims to describe how `cosign` attaches Sigstore attestation
4[bundles](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto)
5to container images.
6
7The goal is to specify the behavior well enough to promote other implementations
8and enable interoperability. Attestations attached with `cosign` should be
9retrievable in other tools, and vice-versa.
10
11This document focuses on the layout of attestations within an
12[OCI Image Manifest V1.1](https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md)
13object.
14
15This document makes no assumptions about the contents of the Sigstore bundle.
16Any attestation which can be represented as a Sigstore bundle (message
17signatures, DSSE-wrapped in-toto statements, etc) can be attached to a container
18image stored in an OCI registry.
19
20Multiple Attestations may be "attached" to one image.
21
22Attestations attached to a container image are generally assumed to refer to
23that image in some way.
24
25## Storage
26
27The approach for storing Sigstore bundles in an OCI registry follows the
28[guidelines for artifact usage](https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage)
29in the OCI
30[image spec](https://github.com/opencontainers/image-spec/blob/main/README.md).
31
32### Publishing
33
34First, the bundle itself is stored in its JSON-serialized form as a blob in the
35registry:
36
37```
38POST /v2/foo/blobs/uploads/?digest=cafed00d...
39Content-Type: application/octet-stream
40
41{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json", ...}
42```
43
44In this example “foo” is the name of the repository within the registry to which
45the artifact is being uploaded. The digest included as part of the POST is the
46hex-encoded SHA-256 digest of the raw bytes of the bundle itself.
47
48Once the blob has been created, the next step is to create a manifest that
49associates the bundle blob with the image it describes:
50
51```
52PUT /v2/foo/manifests/sha256:badf00d...
53Content-Type: application/vnd.oci.image.manifest.v1+json
54
55{
56 "mediaType": "application/vnd.oci.image.manifest.v1+json",
57 "schemaVersion": 2,
58 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
59 "config": {
60 "mediaType": "application/vnd.oci.empty.v1+json",
61 "digest": "sha256:44136fa3...",
62 "size": 2
63 },
64 "layers": [
65 {
66 "digest": "sha256:cafed00d...",
67 "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
68 "size": 4971
69 }
70 ],
71 "subject": {
72 "digest": "sha256:c00010ff...",
73 "mediaType": "application/vnd.oci.image.index.v1+json"
74 }
75}
76```
77
78The manifest must have an `artifactType` field which identifies the type of the
79artifact being referenced -- in this case, it's the Sigstore bundle media type.
80
81The `layers` collection will have a single entry that points to the bundle's
82blob by referencing its size, digest and media type.
83
84The `subject` field associates this artifact with some other artifact which
85already exists in this repository (in this case, an image with the digest
86`c00010ff`)
87
88Sigstore bundles don't require any additional configuration data, so the
89`config` field references the
90[empty descriptor](https://github.com/opencontainers/image-spec/blob/f5f87016de46439ccf91b5381cf76faaae2bc28f/manifest.md#guidance-for-an-empty-descriptor).
91
92At this point, any registry which supports the
93[referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)
94will automatically associate this manifest with the listed subject and make it
95available in the referrers index for that subject.
96
97If the registry DOES NOT support the referrers API, a referrers list must be
98manually created/updated using the
99[referrers tag scheme](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#referrers-tag-schema).
100
101```
102PUT /v2/foo/manifests/sha256-c00010ff...
103Content-Type: application/vnd.oci.image.index.v1+json
104
105{
106 "schemaVersion": 2,
107 "mediaType": "application/vnd.oci.image.index.v1+json",
108 "manifests": [
109 {
110 "mediaType": "application/vnd.oci.image.manifest.v1+json",
111 "digest": "sha256:badf00d..",
112 "size": 779,
113 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json"
114 }
115 ]
116}
117```
118
119This index is uploaded with a tag that references the digest of the image to
120which all of the listed artifacts are associated. Each of the items in the
121`manifests` collection points to some other related artifact.
122
123### Retrieval
124
125When a client wants to locate Sigstore bundles which may be associated with a
126given image, they would first make a request to
127[referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)
128with the image's digest:
129
130```
131GET /v2/foo/referrers/sha256:c000100ff...
132```
133
134A `404 Not Found` response indicates that the registry does not support the
135referrers API and the referrers tag scheme should be used as a fallback:
136
137```
138GET /v2/foo/manifests/sha256-c000100ff...
139```
140
141A `404` here would indicate that there are no artifacts associated with the
142image.
143
144Assuming there are artifacts present, one of the two above calls will return an
145image index listing the artifacts which have been associated with the specified
146image:
147
148```
149{
150 "schemaVersion": 2,
151 "mediaType": "application/vnd.oci.image.index.v1+json",
152 "manifests": [
153 {
154 "mediaType": "application/vnd.oci.image.manifest.v1+json",
155 "digest": "sha256:badf00d..",
156 "size": 779,
157 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json"
158 }
159 ]
160}
161```
162
163From this the client can identify any Sigstore bundles by looking at the
164`artifactType` field.
165
166Using the `digest` listed in the image index, the next step is to retrieve the
167manifest for the bundle:
168
169```
170GET /v2/foo/manifests/sha256:badf00d..
171```
172
173```
174{
175 "mediaType": "application/vnd.oci.image.manifest.v1+json",
176 "schemaVersion": 2,
177 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
178 "config": {
179 "mediaType": "application/vnd.oci.empty.v1+json",
180 "digest": "sha256:44136fa3...",
181 "size": 2
182 },
183 "layers": [
184 {
185 "digest": "sha256:cafed00d...",
186 "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
187 "size": 4971
188 }
189 ],
190 "subject": {
191 "digest": "sha256:c00010ff...",
192 "mediaType": "application/vnd.oci.image.index.v1+json"
193 }
194}
195```
196
197The final step is to use the `digest` from the first of the `layers` to retrieve
198the bundle blob:
199
200```
201GET /v2/foo/blobs/uploads/?digest=cafed00d...
202```
203
204```
205{
206 "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
207 "verificationMaterial": {...},
208 "messageSignature": {...}
209}
210```
211
212## Annotations
213
214For any given image, there may be any number of attached attestation bundles.
215When there are multiple Sigstore bundles associated with an image it may be
216difficult to identify which artifact is which in the image index:
217
218```json
219{
220 "mediaType": "application/vnd.oci.image.index.v1+json",
221 "schemaVersion": 2,
222 "manifests": [
223 {
224 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
225 "digest": "sha256:facefeed",
226 "mediaType": "application/vnd.oci.image.manifest.v1+json"
227 },
228 {
229 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
230 "digest": "sha256:d0d0caca",
231 "mediaType": "application/vnd.oci.image.manifest.v1+json"
232 }
233 ]
234}
235```
236
237To help disambiguate attestations, clients may add annotations to the items in
238the `manifests` list which indicate what is contained within each bundle and
239when it was created:
240
241- `dev.sigstore.bundle.content` - Must be one "message-signature" or
242 "dsse-envelope" and should match the type of content embedded in the Sigstore
243 bundle.
244- `dev.sigstore.bundle.predicateType` - When the bundle contains a DSSE-wrapped
245 in-toto statement, the statement's predicate can be reflected here.
246- `org.opencontainers.image.created` - Date and time when the attestation bundle
247 was created, conforming to
248 [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) (this is one of
249 the pre-defined annotation keys identified in the
250 [OCI spec](https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys)).
251
252These annotations should be included as part of the bundle manifest:
253
254```json
255{
256 "mediaType": "application/vnd.oci.image.manifest.v1+json",
257 "schemaVersion": 2,
258 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
259 "annotations": {
260 "dev.sigstore.bundle.content": "dsse-envelope",
261 "dev.sigstore.bundle.predicateType": "https://slsa.dev/provenance/v1",
262 "org.opencontainers.image.created": "2024-03-08T18:18:20.406Z"
263 },
264 "config": {
265 "mediaType": "application/vnd.oci.empty.v1+json",
266 "digest": "sha256:44136fa3...",
267 "size": 2
268 },
269 "layers": [
270 {
271 "digest": "sha256:cafed00d...",
272 "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
273 "size": 4971
274 }
275 ],
276 "subject": {
277 "digest": "sha256:c00010ff...",
278 "mediaType": "application/vnd.oci.image.index.v1+json"
279 }
280}
281```
282
283Registries which support the referrers API will automatically propagate any
284annotations on the referring manifest to the index. For registries which do NOT
285support the referrers API, the annotations should be added to the index when it
286is updated manually. In either case, the end result should look something like
287the following:
288
289```json
290{
291 "mediaType": "application/vnd.oci.image.index.v1+json",
292 "schemaVersion": 2,
293 "manifests": [
294 {
295 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
296 "digest": "sha256:facefeed",
297 "mediaType": "application/vnd.oci.image.manifest.v1+json",
298 "annotations": {
299 "dev.sigstore.bundle.content": "message-signature",
300 "org.opencontainers.image.created": "2024-03-07T18:17:38.000Z"
301 }
302 },
303 {
304 "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json",
305 "digest": "sha256:d0d0caca",
306 "mediaType": "application/vnd.oci.image.manifest.v1+json",
307 "annotations": {
308 "dev.sigstore.bundle.content": "dsse-envelope",
309 "dev.sigstore.bundle.predicateType": "https://slsa.dev/provenance/v1",
310 "org.opencontainers.image.created": "2024-03-08T18:18:20.406Z"
311 }
312 }
313 ]
314}
315```
View as plain text