Add sign --sign-container-identity CLI

[saschagrunert]

Summary

The --sign-container-identity flag allows setting the critical.identity.docker-reference field in the signature to a different container image reference. This is particularly useful when using proxy mirrors like registry.k8s.io, where end-users have no chance to actually assume the underlying registry. This change allows signing images using the mirror/proxy identifier, while validation can then happen without requiring any additional remapping.

Refers to containers/image#1952, sigstore/sigstore#1166

Release Note

Added sign --sign-identity CLI flag.

Documentation

TBD.

[codecov]

Codecov Report

Merging #2984 (5aac8e4) into main (83c08ce) will increase coverage by 0.51%.
The diff coverage is 0.00%.

@@            Coverage Diff             @@
##             main    #2984      +/-   ##
==========================================
+ Coverage   30.45%   30.96%   +0.51%     
==========================================
  Files         152      153       +1     
  Lines        9586     9676      +90     
==========================================
+ Hits         2919     2996      +77     
- Misses       6210     6222      +12     
- Partials      457      458       +1     

Impacted Files	Coverage Δ
cmd/cosign/cli/options/sign.go	0.00% <0.00%> (ø)
cmd/cosign/cli/sign.go	0.00% <0.00%> (ø)
cmd/cosign/cli/sign/sign.go	14.52% <0.00%> (-0.11%)	⬇️

... and 4 files with indirect coverage changes

[mtrmac]

I strongly support this feature; it is necessary not only for proxies, but also for many staging workflows (creating an image signed with the production key, with a production identity, but not publishing it yet and storing it in an internal registry).

[mtrmac]

Skopeo names this parameter --sign-identity, and I think that captures the intent a bit more accurately; both in being more explicit about what the field means, and in not referring to a specific implementation. (The “simple signing” JSON payload field name should be viewed as a historical artifact.)

[saschagrunert]

I'm also happy with --sign-identity, what do the other maintainers think?

[haydentherapper]

It’s a little confusing to reuse identity, since we use identity already to refer to who is doing the signing. Maybe sign-container-identity?

[hectorj2f]

I agree with @haydentherapper here.

[saschagrunert]

Switched to --sign-container-identity naming.

[cpanato]

lgtm

we just need to remove the replace when the PR from sigstore/sigstore is merged

[znewman01]

This looks great, thanks for the change.

I see there's a little bit of worry about the flag name. I'm empathetic: it's a little weird to say the image has an identity, especially when there's also a signer identity in play.

I don't want to bikeshed too much further, but maybe the name is a little less important if we can make the help text a bit more explicit and to add an example to the cosign sign docs.

My way too wordy version, written to check my own understanding here, would be:

cosign sign uses the "simple signing" format for signatures, which links an image with a given digest to a docker-reference: basically, "image sha256@... is alpine:latest." By default, we infer the docker reference based on what you sign; this flag allows you to override that (for instance, to specify a tag instead of a digest, or when using a proxy).

Maybe something like:

--sign-identity: claim that the image being signed has the given identity (instead of inferring this from the provided image identifier): sign my-registry.io/foo@sha256:... as my-registry.io/foo:v1 or even other-registry.io/bar:latest.

And then add an example like:

# sign a container image, identifying it by tag
cosign sign --sign-identity registry.io/foo:latest my-proxy.io/foo@sha256:abcdef 

# sign a container image fetched via a proxy, identifying it by the upstream Docker reference.
cosign sign --sign-identity upstream-registry.io/foo:latest my-proxy.io/foo@sha256:abcdef 

Feel free to revise any of the above. But I think if the docs are really clear we can live with an imperfect name.

(This suggests that maybe we eventually want some sugar we'd want for using a tag as the --sign-identity: maybe --sign-identity :tag. But we can deal with that later).

[mtrmac]

All of the above makes sense to me.

For a bit more context to consider, separately from his PR, I’d afterwards like to replace/discourage the currently-recommended cosign sign repo@sha256:digest command, because the signature does not include a tag, and matching the tag is an important part of protecting the user against registries/proxies etc. substituting images (giving the user a correctly signed, but old known-vulnerable application version when the user asks for a recent version).

I’m a bit struggling with a good UI… one alternative is to make the --sign-identity option strongly recommended in all flows:

$ cosign sign --sign-identity registry.io/foo:latest my-proxy.io/foo@sha256:abcdef 

My preference would be, instead, to add yet another option:

$ cosign sign --digest sha256:abcdef registry.io/foo:latest

because that can be built “naturally”: a naive user says cosign sign …foo:latest, gets a warning/error “please pin what you want to sign, using cosign sign --digest … foo:latest”, and the user just adds one more option; vs. recommending the user to use --sign-identity, which would require reformulating more of the command line.

That would be an alternative for adding the --sign-identity :tag sugar; --sign-identity would almost exclusively be used when the registry/repo part differs, making the short-form unnecessary.

[znewman01]

All SGTM. I think this PR represents a great first step in that direction.

[hectorj2f]

I also find confusing a lot this flag --sign-identity. In a first look, I am thinking we are specifying the identity that signed the image instead of what is been discussed here. Could we choose a better or more descriptive flag sign-identity-docker-ref or similar ?

[saschagrunert]

Switched to --sign-container-identity for naming, we may want to wait for a sigstore/sigstore release as well.

[znewman01]

I think I'm happy modulo the request for additional examples in the docs (and maybe a slightly longer flag description)!