Signing commands

Four commands actually produce Sigstore signatures. The split is what you're signing (an OCI artifact in a registry vs. a local blob) and what you're producing (a raw signature vs. an in-toto attestation envelope).

Command	Signs	Output payload
cosign sign	OCI artifact (image, index)	Cosign signature attached to the registry, or a local protobuf bundle
cosign sign-blob	A local file / stdin	A signature alongside the file (and/or a bundle)
cosign attest	OCI artifact, with a predicate	DSSE-wrapped in-toto Statement attached to the registry
cosign attest-blob	Local file, with a predicate	DSSE-wrapped in-toto Statement next to the file

All four share the keyless / KMS / local-key plumbing via KeyOpts (cmd/cosign/cli/options/key.go).

cosign sign

cosign sign [--key path|kms-uri] [-a key=value]... [--upload=true|false]
            [--bundle out.sigstore.json] [--new-bundle-format=true|false]
            [--recursive] <image-digest>

Implementation lives in cmd/cosign/cli/sign.go (Cobra wiring) and cmd/cosign/cli/sign/sign.go (SignCmd, ~480 lines). The function flow:

1. Parse KeyOpts from o/flags. Choose a signer:
   • --key cosign.key → local key, password from prompt or COSIGN_PASSWORD.
   • --key <kms-uri> → KMS plugin (registered by import in cmd/cosign/main.go).
   • --sk → PIV smart card.
   • default → keyless via OIDC + Fulcio.
2. For each input ref, resolve the digest (name.ParseReference), then call into sigstore-go's Signer to:
   • get an OIDC token (via pkg/providers/),
   • obtain a Fulcio leaf cert (CSR + token → cert),
   • sign the simple-signing payload,
   • write the entry to Rekor (unless --tlog-upload=false),
   • optionally request an RFC3161 timestamp from a TSA.
3. Push the result. With the new bundle format, that's a sigstore protobuf bundle — pushed to the registry as the signature artifact, written to --bundle, or both. With the legacy format, signatures land at the deterministic sha256-<digest>.sig tag (see SIGNATURE_SPEC).

Notable PreRun guard added in #4785 (cmd/cosign/cli/sign.go):

if o.NewBundleFormat && !o.Upload && o.BundlePath == "" {
    return fmt.Errorf("must enable upload to the OCI registry or specify a local --bundle path with --new-bundle-format")
}

— forces the user to commit to either pushing the bundle or saving it locally; no silent loss.

-a key=value pairs are stored under optional in the simple-signing payload (pkg/oci/static/).

cosign sign-blob

cosign sign-blob [--key ...] --output-signature sig.txt --output-certificate cert.pem
                 [--bundle bundle.sigstore.json] [--yes] <file>

Implementation: cmd/cosign/cli/signblob.go + cmd/cosign/cli/sign/sign_blob.go. Same plumbing as sign, but:

• Input is a file path (or - for stdin); the payload is the file's bytes (or its sha256 digest, depending on flags).
• Output is one of:
  • a base64 detached signature on stdout / --output-signature,
  • a Fulcio cert on --output-certificate,
  • a self-contained protobuf bundle via --bundle.

--yes skips the keyless-signing privacy prompt (the Are you sure … text from internal/ui/prompt.go). CI usage almost always sets it.

cosign attest

cosign attest [--key ...] --type slsaprovenance|vuln|cyclonedx|spdx|link|<custom>
              --predicate file.json [--replace] [--upload=true|false] <image-digest>

Implementation: cmd/cosign/cli/attest.go + cmd/cosign/cli/sign/attest.go (pkg/cosign/attestation/attestation.go for the in-toto Statement assembly). Flow:

1. Read predicate from --predicate.
2. Wrap in an in-toto Statement using --type (the type → URI mapping is in cmd/cosign/cli/options/predicate.go::PredicateTypeMap).
3. DSSE-sign with the chosen key.
4. Push the DSSE envelope as a layer on the deterministic attestation tag (or as a protobuf bundle, depending on the bundle-format flag).

--replace removes any existing attestations of the same predicate type before pushing the new one, instead of accumulating.

cosign attest-blob

cosign attest-blob [--key ...] --predicate file.json --type ...
                   --output-attestation env.json [--bundle bundle.sigstore.json] <file>

Implementation: cmd/cosign/cli/attest_blob.go + cmd/cosign/cli/sign/attest_blob.go. Same shape as attest, but writes the DSSE envelope (or bundle) to disk instead of pushing it to a registry. Used for signing things that aren't OCI artifacts — release tarballs, SBOMs of source trees, etc.

Interaction with TLog and TSA

All four commands share these flags (declared once in cmd/cosign/cli/options/):

• --tlog-upload=true (default) — write to Rekor. Setting false produces a "trust me" signature that won't verify with default verifier policies.
• --rekor-url — override the Rekor endpoint.
• --timestamp-server-url — request an RFC3161 timestamp. Adds a bundle.RFC3161Timestamp to the signature.
• --use-signed-timestamps — embed the TSA timestamp into the new bundle format.
• --issue-certificate (verify-side equivalent for sign uses --issue-certificate=true) — request a Fulcio cert even with a non-keyless --key.

Key source files

File	Purpose
cmd/cosign/cli/sign.go	Cobra command for sign
cmd/cosign/cli/sign/sign.go	Core sign orchestration (~480 lines)
cmd/cosign/cli/signblob.go	Cobra command for sign-blob
cmd/cosign/cli/sign/sign_blob.go	Core blob-sign logic
cmd/cosign/cli/attest.go	Cobra command for attest
cmd/cosign/cli/sign/attest.go (in cmd/cosign/cli/)	Core attest logic (also under cmd/cosign/cli/sign/)
cmd/cosign/cli/attest_blob.go	attest-blob
pkg/cosign/attestation/attestation.go	Predicate → in-toto Statement assembly
pkg/cosign/bundle/sign.go	Build a protobundle from a signing event