Proposal: Use the OCI Descriptor as a payload format

[dlorenc]

https://github.com/opencontainers/image-spec/blob/master/descriptor.md

All the other payload formats I've seen look roughly like this one with slightly different names and structures. We already have this one standardized with library support, why not use it directly?

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "size": 7682,
  "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
  "urls": [
    "https://example.com/example-manifest"
  ],
  "annotations": {
    "foo": "bar"
  }
}

The fields from this proposal can all be mapped in: https://github.com/notaryproject/nv2/tree/prototype-1/docs/signature

References can be placed in the "urls" field, and claims can be placed in the annotations field.

The only limitation is that annotations is string-string rather than an arbitrary JSON object. That's still sufficient for me, and I'd propose that if we actually need richer data here we extend the OCI spec rather than make a new one.

[dlorenc]

Hey,

Any interest in this? We're looking into firming up the payload/attestation format soon in sigstore and would like to use the descriptor. We'd really like to use the same thing as other efforts though.

What does it take to ratify something like this?

[justincormack]

The urls field has a very specific meaning in OCI (its for alternate locations, for foreign layers), and I don't think its appropriate to re-use it.

I do wish annotations were at least lists not strings, it means you can't eg have a list of references, which is why the proposal does have a list for references.

[dlorenc]

Actually looking at the usage in the current example, the references field is only used for x509 cert validation. I think that can actually just be dropped rather than reused. If a client wants to do things like inside the location of an image into the signed payload, that should be an annotation rather than a top level field.

I don't think I follow about the list/string part.

[justincormack]

Currently you can't use an annotation to provide a list of values (like the references/URLs) without inventing some microformat, as you can only use each label to provide a single value.

[dlorenc]

Ah I get it. So instead of list[string-string] you mean object{}, or at least list[list[string]-string]. That would be nice.

[justincormack]

I think going to object might be too much, but at least having (in effect) repeated headers is better.

[dlorenc]

@jonjohnsonjr WDYT?

[jonjohnsonjr]

The thing I care about most is that it conforms to the mediaType, size, digest descriptor fields. It would be convenient if everything could be stuffed in annotations, but I imagine we'd want more structure than that, which seems fine to add.

[dlorenc]

I think based on the last few meetings it sounds like we are heading this direction. Is there a good document location in here to update the status with?

[lachie83]

I'm not following what this issue is about. Is this issue still relevant and if so, could you please provide a little more context to help me understand?

[github-actions]

This issue is stale because it has been opened for 60 days with no activity. Remove stale label or comment. Otherwise, it will be closed in 30 days.

[github-actions]

Issue closed due to no activity in the past 30 days.