Updating cosign signing docs by steiza · Pull Request #419 · sigstore/docs

steiza · 2026-03-06T19:32:50Z

Summary

Making progress on #418

Release Note

Updated cosign signing documentation to reflect Cosign v3 commands

Documentation

N/A

Signed-off-by: Zach Steindler <steiza@github.com>

netlify · 2026-03-06T19:32:57Z

✅ Deploy Preview for docssigstore ready!

Name	Link
🔨 Latest commit	`f5fccc4`
🔍 Latest deploy log	https://app.netlify.com/projects/docssigstore/deploys/69b97524ab9cb500086c445b
😎 Deploy Preview	https://deploy-preview-419--docssigstore.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Signed-off-by: Zach Steindler <steiza@github.com>

Hayden-IO

This looks great, thank you for cleaning this up!

Any updates we need to make to https://github.com/sigstore/docs/blob/main/content/en/quickstart/quickstart-cosign.md? You made an update here to not use ttl.sh, should we make the same change in the quickstart guide?

content/en/cosign/signing/signing_with_containers.md

Signed-off-by: Zach Steindler <steiza@github.com>

content/en/cosign/signing/overview.md

cmurphy · 2026-03-09T20:39:03Z

content/en/cosign/signing/other_types.md

 ## SBOMs (Software Bill Of Materials)

-SBOMs can also be stored in an OCI registry, using this [specification](https://github.com/sigstore/cosign/blob/main/specs/SBOM_SPEC.md).
+There's a couple of different approaches SBOMs, depending on if you're working with container images or not.


Suggested change

There's a couple of different approaches SBOMs, depending on if you're working with container images or not.

SBOMs can be treated as either standalone OCI objects, or as container image attestations.

What I wanted to get across here (and maybe you can help me wordsmith) is that you can use SBOMs with Cosign both if you're working with container images (sign, attest), as well as if you're using files on disk (sign-blob, attest-blob).

Oh I got it, how about just that:

You can use SBOMs with Cosign both if you're working with container images (sign, attest), as well as if you're using files on disk (sign-blob, attest-blob).

content/en/cosign/signing/other_types.md

cmurphy · 2026-03-09T20:46:48Z

content/en/cosign/signing/other_types.md

 {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef"},"Type":"cosign container image signature"},"Optional":null}
 ```

-## Tag signing


Why did we want these sections removed?

For tag signing the use case doesn't make a lot of sense to me. I think today if you want the release name to digest mapping to have integrity you'd use something like https://github.com/in-toto/attestation/blob/main/spec/predicates/release.md, which leads to a second point that I think if you find yourself doing cosign sign -a what you really should be doing is cosign attest --predicate, especially since now a Cosign OCI signature is an attestation (with predicate type https://sigstore.dev/cosign/sign/v1).

For base image signing there's no reason you couldn't do that, but I don't think it needs special mention - you would sign the base image URI. You definitely would not sign each layer - how the heck would you verify that? This is sort of typical of early Cosign "sign everything now, figure out verification later" approach.

Countersigning I was more on the fence. There's no reason why you can't cosign sign targeting a protobuf bundle in the registry, but I don't think that's a use-case we necessarily want to encourage. If you want to do it, and you know what you're doing, go ahead, but I'm not sure it needs to be part of our documentation.

content/en/cosign/signing/signing_with_blobs.md

cmurphy · 2026-03-09T20:51:40Z

content/en/cosign/signing/signing_with_containers.md

 $ cosign sign $IMAGE
 ```

-## Add annotations with a signature


It doesn't look like annotations are deprecated, why don't we want to include examples of it?

I mentioned this above, but I think it's difficult to answer "when should I use cosign sign -a vs when should I use cosign attest --predicate. I personally would strongly recommend people use cosign attest --predicate.

I might be wrong but I think one difference is people can verify that individual annotations are present, but for attestations you have to have more complex policy files to verify their contents. I lean slightly more on the side of keeping documentation and explaining the difference versus letting people discover it in the command line help and not have a good base for understanding it.

Fair enough! I added it back, but below Attesting an image 😅

cmurphy · 2026-03-09T21:43:05Z

content/en/cosign/signing/other_types.md

-  }
-}
+$ echo '{"sbom_path": "example.com/...", "sbom_hash": "sha256:0a1b2c..."}' > sbom.predicate.json
+$ cosign attest --type custom --predicate sbom.predicate.json $IMAGE


I'm curious why use a custom type with an arbitrary predicate instead of keeping the SPDX example for SBOMs?

I really want folks to move away from things like https://github.com/in-toto/attestation/blob/main/spec/predicates/cyclonedx.md and https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx2.md.

SBOMs range from 1 - 100 MBs, and if you stuff the entire SBOM into the Sigstore protobuf bundle (using those predicates) then your Sigstore bundle can be 100 MBs. Not only does this cause problems with Rekor (mostly v1 I think), this also means that anytime you want to verify the container image signature you might have to download 100 MBs of data.

Instead, I think folks should use https://github.com/in-toto/attestation/blob/main/spec/predicates/reference.md, and indeed, this is what we at GitHub are moving things like https://github.com/actions/attest-sbom to. Unfortunately, cosign attest today doesn't let you reference arbitrary predicate types.

Oh, I got it, that makes a lot of sense and I wasn't aware we were trying to move people off of the individual predicate types.

Should we be more explicit about why we're recommending using the custom predicate type and a hash instead of the whole SBOM? Or is there a place we could talk about the advantages (searchability) and disadvantages (size) of using the more explicit predicates?

steiza

Lots of great questions! I added some opinionated answers on my current perspective.

steiza · 2026-03-10T20:23:31Z

content/en/cosign/signing/other_types.md

 ## SBOMs (Software Bill Of Materials)

-SBOMs can also be stored in an OCI registry, using this [specification](https://github.com/sigstore/cosign/blob/main/specs/SBOM_SPEC.md).
+There's a couple of different approaches SBOMs, depending on if you're working with container images or not.


What I wanted to get across here (and maybe you can help me wordsmith) is that you can use SBOMs with Cosign both if you're working with container images (sign, attest), as well as if you're using files on disk (sign-blob, attest-blob).

content/en/cosign/signing/other_types.md

steiza · 2026-03-10T20:31:43Z

content/en/cosign/signing/other_types.md

-  }
-}
+$ echo '{"sbom_path": "example.com/...", "sbom_hash": "sha256:0a1b2c..."}' > sbom.predicate.json
+$ cosign attest --type custom --predicate sbom.predicate.json $IMAGE


I really want folks to move away from things like https://github.com/in-toto/attestation/blob/main/spec/predicates/cyclonedx.md and https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx2.md.

SBOMs range from 1 - 100 MBs, and if you stuff the entire SBOM into the Sigstore protobuf bundle (using those predicates) then your Sigstore bundle can be 100 MBs. Not only does this cause problems with Rekor (mostly v1 I think), this also means that anytime you want to verify the container image signature you might have to download 100 MBs of data.

Instead, I think folks should use https://github.com/in-toto/attestation/blob/main/spec/predicates/reference.md, and indeed, this is what we at GitHub are moving things like https://github.com/actions/attest-sbom to. Unfortunately, cosign attest today doesn't let you reference arbitrary predicate types.

steiza · 2026-03-10T20:43:01Z

content/en/cosign/signing/other_types.md

 {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef"},"Type":"cosign container image signature"},"Optional":null}
 ```

-## Tag signing


For tag signing the use case doesn't make a lot of sense to me. I think today if you want the release name to digest mapping to have integrity you'd use something like https://github.com/in-toto/attestation/blob/main/spec/predicates/release.md, which leads to a second point that I think if you find yourself doing cosign sign -a what you really should be doing is cosign attest --predicate, especially since now a Cosign OCI signature is an attestation (with predicate type https://sigstore.dev/cosign/sign/v1).

For base image signing there's no reason you couldn't do that, but I don't think it needs special mention - you would sign the base image URI. You definitely would not sign each layer - how the heck would you verify that? This is sort of typical of early Cosign "sign everything now, figure out verification later" approach.

Countersigning I was more on the fence. There's no reason why you can't cosign sign targeting a protobuf bundle in the registry, but I don't think that's a use-case we necessarily want to encourage. If you want to do it, and you know what you're doing, go ahead, but I'm not sure it needs to be part of our documentation.

content/en/cosign/signing/signing_with_blobs.md

steiza · 2026-03-10T20:46:41Z

content/en/cosign/signing/signing_with_containers.md

 $ cosign sign $IMAGE
 ```

-## Add annotations with a signature


I mentioned this above, but I think it's difficult to answer "when should I use cosign sign -a vs when should I use cosign attest --predicate. I personally would strongly recommend people use cosign attest --predicate.

Signed-off-by: Zach Steindler <steiza@github.com>

Hayden-IO · 2026-04-09T20:39:56Z

content/en/cosign/signing/gitsign.md

Should this still live somewhere?

Hayden-IO · 2026-04-09T20:40:46Z

content/en/cosign/signing/other_types.md

-```
+Note that there are also SBOM predicate types, but they are not recommended. Using a SBOM predicate type will result in the entire SBOM being included in the signature bundle, and so you will have to download the entire SBOM every time you want to verify the signature on the container.

 ## Tekton Bundles


I wonder if we should drop this - has anyone verified this still works with Tekton?

Hayden-IO · 2026-04-09T20:41:07Z

content/en/cosign/signing/other_types.md

-Pushing signature to: us.gcr.io/user-vmtest2/wasm:sha256-9e7a511fb3130ee4641baf1adc0400bed674d4afc3f1b81bb581c3c8f613f812.sig
 ```

 ## OCI artifacts


I'd bubble this up higher in the documentation

Hayden-IO · 2026-04-09T20:41:46Z

content/en/cosign/signing/other_types.md

-$ cosign verify --key cosign.pub user/demo:mysignature
-{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e"},"Type":"cosign container image signature"},"Optional":{"sig":"counter"}}
-```
+Web Assembly Modules can also be stored in an OCI registry, using this [specification](https://github.com/solo-io/wasm/tree/master/spec).


Not sure this example is that meaningful, we could remove it.

Hayden-IO · 2026-04-09T20:43:02Z

content/en/cosign/signing/signing_with_blobs.md

+$ cosign sign-blob --key cosign.key --bundle bundle.sigstore.json README.md
 Using payload from: README.md
 Enter password for private key:
 MEQCIAU4wPBpl/U5Vtdx/eJFgR0nICiiNCgyWPWarupH0onwAiAv5ycIKgztxHNVG7bzUjqHuvK2gsc4MWxwDgtDh0JINw==


Is this still the output when signing with the new bundle flags? I think this was old output where the signature was dumped to stdout

Hayden-IO · 2026-04-09T20:43:39Z

content/en/cosign/signing/signing_with_containers.md

+> NOTE: You will need access to a container registry for Cosign to work with. If you're not sure what container registry to use, you can set up a local one for testing.

-To create a test image to sign using [ttl.sh](https://ttl.sh), run the following commands:
+[google/go-containerregistry](https://github.com/google/go-containerregistry) allows you to run a container registry locally, and [ko-build/ko](https://github.com/ko-build/ko) lets you build an image:


Can we also reference https://github.com/project-zot/zot for local testing?

Updating cosign signing docs

af9961c

Signed-off-by: Zach Steindler <steiza@github.com>

Remove additional reference to gitsign

95c9755

Signed-off-by: Zach Steindler <steiza@github.com>

Hayden-IO reviewed Mar 9, 2026

View reviewed changes

content/en/cosign/signing/signing_with_containers.md Outdated Show resolved Hide resolved

Hayden-IO requested a review from cmurphy March 9, 2026 18:18

Add ko link; update Cosign quickstart to be consistent

7c4d7a9

Signed-off-by: Zach Steindler <steiza@github.com>

Hayden-IO previously approved these changes Mar 9, 2026

View reviewed changes

cmurphy reviewed Mar 9, 2026

View reviewed changes

steiza commented Mar 10, 2026

View reviewed changes

Add TSA to signing-config example

6194ae3

Signed-off-by: Zach Steindler <steiza@github.com>

steiza dismissed Hayden-IO’s stale review via 6194ae3 March 11, 2026 12:33

Update SBOM content and re-add annotations

f5fccc4

Signed-off-by: Zach Steindler <steiza@github.com>

Hayden-IO reviewed Apr 9, 2026

View reviewed changes

	There's a couple of different approaches SBOMs, depending on if you're working with container images or not.
	SBOMs can be treated as either standalone OCI objects, or as container image attestations.

Conversation

steiza commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Release Note

Documentation

Uh oh!

netlify bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docssigstore ready!

Uh oh!

Hayden-IO left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

steiza left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

steiza commented Mar 6, 2026 •

edited

Loading

netlify bot commented Mar 6, 2026 •

edited

Loading