Add COSIGN_OCI_EXPERIMENTAL, push .sig/.sbom using OCI 1.1+ digest tag #2684

jdolitsky · 2023-02-01T16:24:49Z

Please see https://github.com/opencontainers/distribution-spec/blob/main/spec.md#referrers-tag-schema

This begins publishing/fetching/verifying signatures and SBOM attachments using the proper OCI defined referrers tag schema, if COSIGN_OCI_EXPERIMENTAL=1 is set in the environment. If the digest tag is not found, download/verify commands will fallback to try the cosign-defined tags (sha256-<hash>.sig / sha256-<hash>.sbom).

This means all attached entities will be able to be located via the tag sha256-<hash>, which should be formatted as an OCI image index. Manifests defining signatures and SBOMs also add the subject field also newly defined by OCI to point to a reference.

This also follows guidance by OCI to start using unique mediatypes for config.mediaType to surface as an artifactType:

application/vnd.dev.cosign.artifact.sbom.v1+json
application/vnd.dev.cosign.artifact.sig.v1+json

Setup

Note: I've made the repo ghcr.io/jdolitsky/cosign-pr-demo public if anybody wants to inspect the tags, manifests, etc.

Get a base image to start attaching to:

crane cp cgr.dev/chainguard/wolfi-base ghcr.io/jdolitsky/cosign-pr-demo

Set the new experimental env var:

export COSIGN_OCI_EXPERIMENTAL=1

SBOM flow

Create a fake SBOM:

echo '{"hello": "world"}' > sbom.json

Attach it:

cosign attach sbom --sbom sbom.json --type spdx ghcr.io/jdolitsky/cosign-pr-demo

View repo tags (notice no .sbom tag):

crane ls ghcr.io/jdolitsky/cosign-pr-demo

latest
sha256-97d731da806109c4f61ac32e8830e13952ca2c65bc7fbfe32babd7d267e633bf

View the digest tag:

crane manifest ghcr.io/jdolitsky/cosign-pr-demo:sha256-97d731da806109c4f61ac32e8830e13952ca2c65bc7fbfe32babd7d267e633bf | jq

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 539,
      "digest": "sha256:e952330096c5349c253bb11c09a25c546ca35d4b2a1bfaac805fee90cbe8fde1",
      "artifactType": "application/vnd.dev.cosign.artifact.sbom.v1+json"
    }
  ]
}

View the manifest for the SBOM artifact:

crane manifest ghcr.io/jdolitsky/cosign-pr-demo@sha256:e952330096c5349c253bb11c09a25c546ca35d4b2a1bfaac805fee90cbe8fde1 | jq

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.dev.cosign.artifact.sbom.v1+json",
    "size": 233,
    "digest": "sha256:2d3e57b4f854275fc6f727dddf42be516b4f133ea164004de18bf90054d95e9b"
  },
  "layers": [
    {
      "mediaType": "text/spdx+json",
      "size": 19,
      "digest": "sha256:44aff4ab2d7c3250525675a08f0cfa9591168cffe51791c5f5bbc417c15a6c38"
    }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "size": 491,
    "digest": "sha256:97d731da806109c4f61ac32e8830e13952ca2c65bc7fbfe32babd7d267e633bf"
  }
}

Fetch the raw SBOM contents:

cosign download sbom ghcr.io/jdolitsky/cosign-pr-demo

{"hello": "world"}

Signature flow

Sign the image (keyless):

cosign sign ghcr.io/jdolitsky/cosign-pr-demo

View repo tags (notice no .sig tag):

crane ls ghcr.io/jdolitsky/cosign-pr-demo

latest
sha256-97d731da806109c4f61ac32e8830e13952ca2c65bc7fbfe32babd7d267e633bf

View the digest tag (now updated with and second manifest):

crane manifest ghcr.io/jdolitsky/cosign-pr-demo:sha256-97d731da806109c4f61ac32e8830e13952ca2c65bc7fbfe32babd7d267e633bf | jq

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 5825,
      "digest": "sha256:478cf2f3284811b500cc3aee71b7d8c3a744917e863a78922674211c75b1e36c",
      "artifactType": "application/vnd.dev.cosign.artifact.sig.v1+json"
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 539,
      "digest": "sha256:e952330096c5349c253bb11c09a25c546ca35d4b2a1bfaac805fee90cbe8fde1",
      "artifactType": "application/vnd.dev.cosign.artifact.sbom.v1+json"
    }
  ]
}

View the manifest for the signature artifact:

crane manifest ghcr.io/jdolitsky/cosign-pr-demo@sha256:478cf2f3284811b500cc3aee71b7d8c3a744917e863a78922674211c75b1e36c | jq

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.dev.cosign.artifact.sig.v1+json",
    "size": 245,
    "digest": "sha256:231b8f1c59b2adb759b9c3b6d08ed448a8ef1e9561daf0488834a0b415a00bf9"
  },
  "layers": [
    {
      "mediaType": "application/vnd.dev.cosign.simplesigning.v1+json",
      "size": 248,
      "digest": "sha256:c9f14cf696ee3df0a6b88ddbc8fab86fba1fa85c7bfef7e8ff1275d8058ac3d8",
      "annotations": {
        "dev.cosignproject.cosign/signature": "...",
        "dev.sigstore.cosign/bundle": "...",
        "dev.sigstore.cosign/certificate": "...",
        "dev.sigstore.cosign/chain": "..."
      }
    }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "size": 491,
    "digest": "sha256:97d731da806109c4f61ac32e8830e13952ca2c65bc7fbfe32babd7d267e633bf"
  }
}

Verify the signature:

cosign verify ghcr.io/jdolitsky/cosign-pr-demo --certificate-identity-regexp=".*"  --certificate-oidc-issuer-regexp=".*"

dlorenc · 2023-02-01T16:29:57Z

Amazing!

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

codecov-commenter · 2023-02-01T16:49:55Z

Codecov Report

Merging #2684 (d337642) into main (a505400) will decrease coverage by 0.43%.
The diff coverage is 7.85%.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

@@            Coverage Diff             @@
##             main    #2684      +/-   ##
==========================================
- Coverage   30.11%   29.68%   -0.43%     
==========================================
  Files         150      151       +1     
  Lines        9483     9670     +187     
==========================================
+ Hits         2856     2871      +15     
- Misses       6190     6360     +170     
- Partials      437      439       +2

Impacted Files	Coverage Δ
cmd/cosign/cli/attach.go	`0.00% <0.00%> (ø)`
cmd/cosign/cli/options/attach.go	`0.00% <0.00%> (ø)`
cmd/cosign/cli/options/registry.go	`0.00% <0.00%> (ø)`
cmd/cosign/cli/options/sign.go	`0.00% <0.00%> (ø)`
cmd/cosign/cli/sign/sign.go	`14.74% <0.00%> (-0.15%)`	⬇️
pkg/cosign/verify.go	`37.22% <0.00%> (-2.04%)`	⬇️
pkg/oci/remote/write.go	`14.18% <0.00%> (-12.14%)`	⬇️
pkg/oci/remote/remote.go	`36.91% <23.25%> (-5.55%)`	⬇️
pkg/oci/remote/referrers.go	`100.00% <100.00%> (ø)`

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

imjasonh

Super excited about this change!

When COSIGN_OCI_EXPERIMENTAL=1, we should search for SBOMs etc in both the OCI fallback tag, and the legacy cosign <digest>.sbom tag, since folks may have uploaded an SBOM using an old version of cosign, or without the env set.

cmd/cosign/cli/attach/sbom.go

imjasonh · 2023-02-01T17:35:08Z

pkg/oci/remote/referrers.go

+)
+
+// Referrers fetches references using registry options.
+func Referrers(d name.Digest, artifactType string, opts ...Option) (*v1.IndexManifest, error) {


Can we move this to an internal package? I don't think we want folks outside of cosign to use this.

I wasn't able to figure out a way to make this method non-public. It is used outside of this package, and unfortunately the options parser (makeOptions) is unavailable outside this package... so this will not reliably pass along registry options etc.

I'm open to other solutions, maybe even panicking if the method is called and the env var is unset 🤷

The rot runs deep.

I think I'm okay with a "this is subject to change, don't use this" in the docstring

pkg/oci/remote/remote.go

jdolitsky · 2023-02-01T18:01:21Z

When COSIGN_OCI_EXPERIMENTAL=1, we should search for SBOMs etc in both the OCI fallback tag, and the legacy cosign .sbom tag, since folks may have uploaded an SBOM using an old version of cosign, or without the env set.

Yes, it does this! In the PR description I mention it: "If the digest tag is not found, download/verify commands will fallback to try the cosign-defined tags (sha256-<hash>.sig / sha256-<hash>.sbom)."

In the code you will see that if an err is returned from one of these experimental methods on fetch, it just prints something to the effect of "Unable to locate attachment using digest tag, trying older scheme"

jdolitsky · 2023-02-01T18:06:46Z

FYI - once this PR is in, we just need a go.mod bump to start using the Referrers API endpoint: google/go-containerregistry#1546

…-tag Signed-off-by: Josh Dolitsky <josh@dolit.ski>

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

jdolitsky · 2023-02-03T23:04:29Z

After pulling in the latest GGCR, and running a local instance of zot, the SBOM and signature flows above work using the referrers API! No digest tag, no .sbom/.sig tags, nothing!

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

jdolitsky · 2023-02-03T23:29:55Z

pkg/oci/remote/write.go

+
+// WriteSignaturesExperimentalOCI publishes the signatures attached to the given entity
+// into the provided repository (using OCI 1.1 methods).
+func WriteSignaturesExperimentalOCI(d name.Digest, se oci.SignedEntity, opts ...Option) error {


this method also suffers the same problem as Referrers, needing to use makeOptions

znewman01

This is awesome, thanks for your patience with the review.

One big question I have: is there a fallback story?

I'd expect there to be an awkward transition period where during this transition"

to write, we attempt to figure out if a repository supports the Referrers API, and use that if so. otherwise use the old trick
to read, we attempt to read from Referrers. if that doesn't exist (regardless of whether the repo supports it, we try the old trick

So maybe instead of a boolean UseReferrers we have a ReferencesMode enum with values REFERRERS_ONLY, TAG_HACK_ONLY, REFERRERS_WITH_FALLBACK.

The other thing is...there seems to be some missing abstraction here. I see a lot of logic duplicated between SBOMs, signatures, and attachments. Maybe that would hurt more than it helps though.

pkg/cosign/verify.go

znewman01 · 2023-02-07T14:48:21Z

pkg/cosign/verify.go

@@ -461,6 +464,14 @@ func (fos *fakeOCISignatures) Get() ([]oci.Signature, error) {
 // VerifyImageSignatures does all the main cosign checks in a loop, returning the verified signatures.
 // If there were no valid signatures, we return an error.
 func VerifyImageSignatures(ctx context.Context, signedImgRef name.Reference, co *CheckOpts) (checkedSignatures []oci.Signature, bundleVerified bool, err error) {
+	if b, err := strconv.ParseBool(env.Getenv(env.VariableOCIExperimental)); err == nil && b {


My preference is actually to make experimental solely a CLI concern. Then, we can add a field OciReferrers: bool or something to CheckOpts and rely on that.

Or even better to oci.Options (aka co.RegistryClientOpts)!

znewman01 · 2023-02-07T14:49:33Z

cmd/cosign/cli/sign/sign.go

@@ -311,6 +313,11 @@ func signDigest(ctx context.Context, digest name.Digest, payload []byte, ko opti
 		ui.Infof(ctx, "Pushing signature to: %s", repo.RepositoryStr())
 	}

+	// Publish the signatures associated with this entity (using OCI 1.1+ behavior)
+	if b, err := strconv.ParseBool(env.Getenv(env.VariableOCIExperimental)); err == nil && b {


Use exprimental.EnableOciWhatever()?

znewman01 · 2023-02-07T14:52:18Z

pkg/oci/remote/referrers.go

+)
+
+// Referrers fetches references using registry options.
+func Referrers(d name.Digest, artifactType string, opts ...Option) (*v1.IndexManifest, error) {


The rot runs deep.

I think I'm okay with a "this is subject to change, don't use this" in the docstring

znewman01 · 2023-02-07T14:53:04Z

pkg/oci/remote/remote.go

@@ -146,6 +149,13 @@ func attestations(digestable digestable, o *options) (oci.Signatures, error) {

 // attachment is a shared implementation of the oci.Signed* Attachment method.
 func attachment(digestable digestable, attName string, o *options) (oci.File, error) {
+	if b, err := strconv.ParseBool(env.Getenv(env.VariableOCIExperimental)); err == nil && b {


Same comment: I'd prefer nothing in pkg/ to know about experimental features, so this should just be an option (in options?)

znewman01 · 2023-02-08T16:38:45Z

pkg/cosign/verify.go

+			return nil, false, fmt.Errorf("unable to locate reference with artifactType %s", artifactType)
+		} else if numResults > 1 {
+			// TODO: if there is more than 1 result.. what does that even mean?
+			fmt.Printf("WARNING: there were a total of %d references with artifactType %s\n", numResults, artifactType)


Maybe: "expected only 1" in the warning?

This isn't a terribly actionable warning right now sadly. I guess because we don't know why the heck it would happen, ha

pkg/cosign/verify.go

pkg/oci/remote/write.go

znewman01 · 2023-02-08T16:46:39Z

cmd/cosign/cli/attach/sbom.go

@@ -60,6 +72,67 @@ func SBOMCmd(ctx context.Context, regOpts options.RegistryOptions, sbomRef strin
 	return remote.Write(dstRef, img, regOpts.GetRegistryClientOpts(ctx)...)
 }

+func sbomCmdOCIExperimental(ctx context.Context, regOpts options.RegistryOptions, sbomRef string, sbomType ocitypes.MediaType, imageRef string) error {


This is a bit long for the cmd/ package. Can we move some of it into pkg/?

There's also a fair bit of overlap with SBOMCmd. I bet if we reorder things you can actually stick the if EnableOCIExperimental() at the end of SBOMCmd and call this something like writeSBOM.

sudo-bmitch · 2023-02-10T15:55:04Z

I still need to give this a test drive, so forgive the uninformed suggestion. I'd recommend consuming both the old and new format regardless of the experimental flag, without any warnings. Make the experimental flag change how the signatures are produced. That results in a smoother transition for orgs with older clients that don't want to simultaneously set the experimental flag on every consumer.

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

znewman01 · 2023-02-13T23:18:56Z

e2e tests failing, otherwise LGTM

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

sigstore#2684) * Add COSIGN_OCI_EXPERIMENTAL, push .sig/.sbom using OCI 1.1+ digest tag Signed-off-by: Josh Dolitsky <josh@dolit.ski> * upgrade to latest ggcr with referrers API support Signed-off-by: Josh Dolitsky <josh@dolit.ski> * unexport methods whereever possible Signed-off-by: Josh Dolitsky <josh@dolit.ski> * Use ui logger wherever possible Signed-off-by: Josh Dolitsky <josh@dolit.ski> * add TODO about using created annotations Signed-off-by: Josh Dolitsky <josh@dolit.ski> * remove logging about unable to to find new type of attachment Signed-off-by: Josh Dolitsky <josh@dolit.ski> * fixes from review Signed-off-by: Josh Dolitsky <josh@dolit.ski> * push the config blob Signed-off-by: Josh Dolitsky <josh@dolit.ski> * run docgen Signed-off-by: Josh Dolitsky <josh@dolit.ski> * fix for e2e tests Signed-off-by: Josh Dolitsky <josh@dolit.ski> --------- Signed-off-by: Josh Dolitsky <josh@dolit.ski>

Add COSIGN_OCI_EXPERIMENTAL, push .sig/.sbom using OCI 1.1+ digest tag

d118235

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

jdolitsky force-pushed the oci-1-1-digest-tag branch from bba1b7f to d118235 Compare February 1, 2023 16:45

jdolitsky mentioned this pull request Feb 1, 2023

Plan for Reference Types Work! #1397

Open

imjasonh reviewed Feb 1, 2023

View reviewed changes

This was referenced Feb 1, 2023

Update cosign to v2.0.2 fluxcd/source-controller#979

Closed

[Feature] Tracking Issue for Referrers API in Cosign kyverno/kyverno#5655

Open

dlorenc mentioned this pull request Feb 2, 2023

Remove artifact manifest opencontainers/image-spec#999

Merged

jdolitsky mentioned this pull request Feb 3, 2023

Adding oci artifacts draft chainguard-dev/edu#334

Merged

jdolitsky added 2 commits February 3, 2023 16:36

Merge branch 'main' of github.com:sigstore/cosign into oci-1-1-digest…

9dee558

…-tag Signed-off-by: Josh Dolitsky <josh@dolit.ski>

upgrade to latest ggcr with referrers API support

42868b1

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

jdolitsky force-pushed the oci-1-1-digest-tag branch from 12e5542 to 42868b1 Compare February 3, 2023 23:00

unexport methods whereever possible

a2542ea

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

jdolitsky commented Feb 3, 2023

View reviewed changes

znewman01 reviewed Feb 8, 2023

View reviewed changes

jdolitsky and others added 7 commits February 13, 2023 14:33

Merge branch 'sigstore:main' into oci-1-1-digest-tag

4c18c95

Use ui logger wherever possible

6120b11

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

add TODO about using created annotations

af86ae9

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

remove logging about unable to to find new type of attachment

4bd1d04

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

fixes from review

2ce0564

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

push the config blob

e899a84

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

run docgen

e79a1c2

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

znewman01 previously approved these changes Feb 13, 2023

View reviewed changes

fix for e2e tests

d337642

Signed-off-by: Josh Dolitsky <josh@dolit.ski>

jdolitsky dismissed znewman01’s stale review via d337642 February 13, 2023 23:24

znewman01 approved these changes Feb 13, 2023

View reviewed changes

znewman01 merged commit 2b3ff73 into sigstore:main Feb 14, 2023

github-actions bot added this to the v1.14.0 milestone Feb 14, 2023

ChristianCiach mentioned this pull request Feb 15, 2023

Adopt OCI distribution spec v1.1.0 goharbor/harbor#17928

Closed

znewman01 mentioned this pull request Mar 31, 2023

COSIGN_OCI_EXPERIMENTAL still uses old cosign tag #2854

Closed

MinerYang mentioned this pull request Dec 19, 2023

Integrate cosign accessory with distribution spec 1.1 goharbor/harbor#19732

Closed

haydentherapper mentioned this pull request Mar 12, 2024

Sigstore Bundle as OCI Artifact #3577

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add COSIGN_OCI_EXPERIMENTAL, push .sig/.sbom using OCI 1.1+ digest tag #2684

Add COSIGN_OCI_EXPERIMENTAL, push .sig/.sbom using OCI 1.1+ digest tag #2684

jdolitsky commented Feb 1, 2023 •

edited

Loading

dlorenc commented Feb 1, 2023

codecov-commenter commented Feb 1, 2023 •

edited

Loading

imjasonh left a comment

imjasonh Feb 1, 2023

jdolitsky Feb 3, 2023

znewman01 Feb 7, 2023

jdolitsky commented Feb 1, 2023

jdolitsky commented Feb 1, 2023

jdolitsky commented Feb 3, 2023

jdolitsky Feb 3, 2023

znewman01 left a comment

znewman01 Feb 7, 2023

znewman01 Feb 7, 2023

znewman01 Feb 7, 2023

znewman01 Feb 7, 2023

znewman01 Feb 8, 2023

znewman01 Feb 8, 2023

znewman01 Feb 8, 2023

sudo-bmitch commented Feb 10, 2023

znewman01 commented Feb 13, 2023

Add COSIGN_OCI_EXPERIMENTAL, push .sig/.sbom using OCI 1.1+ digest tag #2684

Add COSIGN_OCI_EXPERIMENTAL, push .sig/.sbom using OCI 1.1+ digest tag #2684

Conversation

jdolitsky commented Feb 1, 2023 • edited Loading

Setup

SBOM flow

Signature flow

dlorenc commented Feb 1, 2023

codecov-commenter commented Feb 1, 2023 • edited Loading

Codecov Report

imjasonh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdolitsky commented Feb 1, 2023

jdolitsky commented Feb 1, 2023

jdolitsky commented Feb 3, 2023

Choose a reason for hiding this comment

znewman01 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sudo-bmitch commented Feb 10, 2023

znewman01 commented Feb 13, 2023

jdolitsky commented Feb 1, 2023 •

edited

Loading

codecov-commenter commented Feb 1, 2023 •

edited

Loading