Require new bundle format for signing and verification

[aaronlew02]

Summary

This change mandates the new bundle format for signing and verification.

For verification, this enables the exclusive use of sigstore-go and requires a trusted root. For signing, this disables individual service inputs (i.e., outside of a signing config) and detached outputs.

Release Note

• Signers requiring services MUST use a signing config (either from TUF via --use-signing-config [true by default] or explicitly provided via --signing-config).

  • This applies to ALL keyless signers.
  • This applies to key-based signers requesting a certificate, RFC 3161 timestamp, and/or transparency log entry.

• Signers NOT requiring services MUST set --use-signing-config=false.

  • This applies to offline key-based signers.

• Verifiers validating service-provided verification material MUST use a trusted root (either fetched from TUF automatically or explicitly provided via --trusted-root).

  • This applies to ALL keyless verifiers.
  • This applies to key-based verifiers with a certificate, RFC 3161 timestamp, and/or transparency log entry.

• Several flags have been removed:

  • Service configuration flags obsoleted by the signing config and trusted root:
    • --rekor-url (for signing, attestation, and verification only), --fulcio-url, --oidc-issuer, --timestamp-server-url, --timestamp-certificate-chain, --ca-roots, --ca-intermediates, --certificate-chain, --certificate, --tlog-upload, --offline
  • Flags obsoleted by the new bundle format:
    • --new-bundle-format
    • --rekor-entry-type
    • Input overrides: --record-creation-timestamp, --signature/--signature-path, --payload
    • Detached outputs: --sct, --rfc3161-timestamp/--rfc3161-timestamp-bundle, --b64, --output/--output-signature/--output-payload/--output-attestation/--output-certificate
  • Flags obsoleted by the shift to OCI 1.1 Referrers:
    • --replace, --attachment, --experimental-oci11, --sign-container-identity
  • Protocol and verification flow adjustments:
    • --insecure-skip-verify (SCT verification is no longer performed during signing)
    • --private-infrastructure (Obsoleted in favor of --insecure-ignore-tlog)

• Service configuration environment variables are no longer used in production (but remain used in testing):

  • SIGSTORE_ROOT_FILE, SIGSTORE_REKOR_PUBLIC_KEY, SIGSTORE_CT_LOG_PUBLIC_KEY_FILE, SIGSTORE_TSA_CERTIFICATE_FILE

• ALL signers using a signing config containing at least one transparency log must agree to the immutable record privacy statement.

Documentation

[codecov]

Codecov Report

❌ Patch coverage is 33.71648% with 173 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.55%. Comparing base (2ef6022) to head (aeb5a8b).
⚠️ Report is 807 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/cosign/cli/attest.go	9.09%	20 Missing ⚠️
cmd/cosign/cli/attest_blob.go	23.07%	20 Missing ⚠️
cmd/cosign/cli/signcommon/common.go	0.00%	17 Missing ⚠️
cmd/cosign/cli/signblob.go	38.09%	13 Missing ⚠️
cmd/cosign/cli/verify/verify_blob_attestation.go	65.78%	7 Missing and 6 partials ⚠️
cmd/cosign/cli/attest/attest.go	0.00%	12 Missing ⚠️
cmd/cosign/cli/sign.go	7.69%	12 Missing ⚠️
cmd/cosign/cli/verify.go	0.00%	12 Missing ⚠️
cmd/cosign/cli/verify/verify.go	28.57%	10 Missing ⚠️
cmd/cosign/cli/sign/sign.go	0.00%	9 Missing ⚠️
... and 7 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4959      +/-   ##
==========================================
- Coverage   40.10%   39.55%   -0.56%     
==========================================
  Files         155      209      +54     
  Lines       10044    11441    +1397     
==========================================
+ Hits         4028     4525     +497     
- Misses       5530     6330     +800     
- Partials      486      586     +100     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[aaronlew02]

Testing

The following commands can be used to test the changes in this PR.

Setup

Before running the tests, ensure that you have generated a local test keypair (which is used for key-based tests):

# Generate a keypair (writes to cosign.key and cosign.pub)
cosign generate-key-pair

1. TUF-provided Signing Config & Trusted Root

Verify that a TUF-provided signing config and trusted root are resolved correctly for keyless operations and key-based, certificate-backed operations:

Keyless Operations

Image signing & verification

# Sign using TUF signing config
cosign sign --use-signing-config=true [IMAGE_URI]

# Verify using TUF trusted root
cosign verify --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [IMAGE_URI]

Blob signing & verification

# Sign a blob to generate a bundle
cosign sign-blob --use-signing-config=true --bundle blob.bundle [BLOB_FILE]

# Verify the blob using the bundle and TUF trusted root
cosign verify-blob --bundle blob.bundle --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [BLOB_FILE]

Image attestation & verification

# Attest the image
cosign attest --use-signing-config=true --predicate [PREDICATE_FILE] [IMAGE_URI]

# Verify the attestation
cosign verify-attestation --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [IMAGE_URI]

Blob attestation & verification

# Attest a blob to generate a bundle
cosign attest-blob --use-signing-config=true --predicate [PREDICATE_FILE] --bundle attest.bundle [BLOB_FILE]

# Verify the blob attestation
cosign verify-blob-attestation --bundle attest.bundle --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [BLOB_FILE]

Key-based / Certificate-backed Operations

Key-based, certificate-backed signing & verification

# Sign using local key and request Fulcio certificate using TUF signing config
cosign sign --key cosign.key --issue-certificate --use-signing-config=true [IMAGE_URI]

# Verify using TUF trusted root and identity checks
cosign verify --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [IMAGE_URI]

Key-based signing with transparency log and RFC 3161 timestamp

# Sign a blob using key and request log entry/timestamp
cosign sign-blob --key cosign.key --use-signing-config=true --bundle blob.bundle [BLOB_FILE]

# Verify the blob bundle (verifying the signature, log proof, and timestamp against TUF trusted root)
cosign verify-blob --key cosign.pub --bundle blob.bundle [BLOB_FILE]

---

2. Explicit Local Signing Config & Trusted Root

Verify that explicitly provided local config and trusted root files are loaded and utilized correctly:

Keyless Operations

Image signing & verification

# Sign using a local signing config file
cosign sign --signing-config [PATH_TO_SIGNING_CONFIG] [IMAGE_URI]

# Verify using an explicit trusted root file
cosign verify --trusted-root [PATH_TO_TRUSTED_ROOT] --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [IMAGE_URI]

Blob signing & verification

# Sign a blob using a local signing config file
cosign sign-blob --signing-config [PATH_TO_SIGNING_CONFIG] --bundle blob.bundle [BLOB_FILE]

# Verify the blob using an explicit trusted root file
cosign verify-blob --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle blob.bundle --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [BLOB_FILE]

Image attestation & verification

# Attest the image using a local signing config file
cosign attest --signing-config [PATH_TO_SIGNING_CONFIG] --predicate [PREDICATE_FILE] [IMAGE_URI]

# Verify the attestation using an explicit trusted root file
cosign verify-attestation --trusted-root [PATH_TO_TRUSTED_ROOT] --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [IMAGE_URI]

Blob attestation & verification

# Attest a blob using a local signing config file
cosign attest-blob --signing-config [PATH_TO_SIGNING_CONFIG] --predicate [PREDICATE_FILE] --bundle attest.bundle [BLOB_FILE]

# Verify the blob attestation using an explicit trusted root file
cosign verify-blob-attestation --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle attest.bundle --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [BLOB_FILE]

Key-based Operations

Key-based, certificate-backed signing & verification

# Sign using local key and request Fulcio certificate using local signing config
cosign sign --key cosign.key --issue-certificate --signing-config [PATH_TO_SIGNING_CONFIG] [IMAGE_URI]

# Verify using local trusted root file and identity checks
cosign verify --trusted-root [PATH_TO_TRUSTED_ROOT] --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [IMAGE_URI]

Key-based signing with transparency log and RFC 3161 timestamp

# Sign a blob using key and request log entry/timestamp via local signing config
cosign sign-blob --key cosign.key --signing-config [PATH_TO_SIGNING_CONFIG] --bundle blob.bundle [BLOB_FILE]

# Verify the blob bundle against local trusted root file
cosign verify-blob --key cosign.pub --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle blob.bundle [BLOB_FILE]

Service Omission Tests (Config-driven behavior)

Verify that omitting specific services in the signing config successfully skips their use during signing:

Omitting Rekor (Skips log upload)

# 1. Generate a signing config file without Rekor configured
cosign signing-config create --with-default-services --no-default-rekor --out signing-config-no-rekor.json

# 2. Sign a blob (succeeds without attempting log upload; generated bundle will not contain a log entry)
cosign sign-blob --signing-config signing-config-no-rekor.json --bundle blob-no-rekor.bundle [BLOB_FILE]

# 3. Verify the bundle (should FAIL by default due to missing log entry/SET proof)
cosign verify-blob --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle blob-no-rekor.bundle --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [BLOB_FILE]

# 4. Verify the bundle with tlog bypassed (should SUCCEED)
cosign verify-blob --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle blob-no-rekor.bundle --insecure-ignore-tlog --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [BLOB_FILE]

Omitting TSA (Skips RFC 3161 timestamping)

# 1. Generate a signing config file without TSA configured
cosign signing-config create --with-default-services --no-default-tsa --out signing-config-no-tsa.json

# 2. Sign a blob (succeeds without requesting timestamp; generated bundle will not contain a timestamp)
cosign sign-blob --signing-config signing-config-no-tsa.json --bundle blob-no-tsa.bundle [BLOB_FILE]

# 3. Verify the bundle (should SUCCEED; falls back to using the tlog integrated time to verify certificate expiry)
cosign verify-blob --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle blob-no-tsa.bundle --certificate-identity [IDENTITY] --certificate-oidc-issuer [ISSUER] [BLOB_FILE]

---

3. Simple Key-based Signing & Verification (No services)

Verify that simple key-based operations (which do not interact with Fulcio, Rekor, or a timestamp authority) work cleanly:

# Sign an image using a private key (no signing config or OCI upload)
cosign sign --key cosign.key [IMAGE_URI]

# Verify the image using the public key
cosign verify --key cosign.pub [IMAGE_URI]

# Sign a blob using a private key (generates a simple bundle without log/timestamp verification material)
cosign sign-blob --key cosign.key --bundle blob.bundle [BLOB_FILE]

# Verify the blob using the public key and bundle
cosign verify-blob --key cosign.pub --bundle blob.bundle [BLOB_FILE]

---

4. CLI Flag Validations (Negative Testing)

Verify that the CLI rejects removed flags and enforces mandatory new arguments:

# 1. Rejects removed flags (should fail with unknown flag errors)
cosign sign --rekor-url [URL] [IMAGE_URI]
cosign sign --timestamp-server-url [URL] [IMAGE_URI]
cosign verify --rekor-url [URL] [IMAGE_URI]
cosign verify --signature [SIG_PATH] --payload [PAYLOAD_PATH] [IMAGE_URI]
cosign verify-blob --signature [SIG_PATH] [BLOB_FILE]

# 2. Enforces signing configuration for keyless and certificate-based signing/attestation (should fail with specific keyless or certificate-based error messages)
cosign sign --use-signing-config=false [IMAGE_URI]
cosign sign --key cosign.key --issue-certificate --use-signing-config=false [IMAGE_URI]
cosign sign-blob --use-signing-config=false --bundle blob.bundle [BLOB_FILE]
cosign attest --use-signing-config=false [IMAGE_URI]
cosign attest-blob --use-signing-config=false --bundle attest.bundle [BLOB_FILE]

# 3. Enforces bundle for blob signing and attestation (should fail with error requiring bundle)
cosign sign-blob [BLOB_FILE]
cosign attest-blob [BLOB_FILE]