[aaronlew02]

Summary

This change mandates the new bundle format for sign-blob.

This disables individual service inputs (i.e., outside of a signing config) and detached outputs.

Release Note

• BREAKING CHANGE: --use-signing-config=false disables the use of online services (certificate authorities, transparency logs, or timestamp authorities) for signing.

  • Previously, --use-signing-config=false without service configuration flags defaulted to signing with the public-good Fulcio and Rekor instances.
  • Now, key-based signing with --use-signing-config=false and no service configuration flags succeeds without uploading to a transparency log.

• 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 or explicitly provide an empty signing config via --signing-config (e.g., created with cosign signing-config create).

  • This applies to offline key-based signers.

• Several flags have been rendered obsolete:

  • Service configuration flags obsoleted by the signing config:
    • Removed: --rekor-url, --timestamp-server-url, --tlog-upload
    • Ignored with --use-signing-config=false (to be removed in Remove legacy flags and helpers #5145): --fulcio-url, --oidc-issuer
  • Flags obsoleted by the new bundle format (removed):
    • --new-bundle-format
    • Detached outputs: --rfc3161-timestamp, --b64, --output/--output-signature/--output-certificate

[codecov]

Codecov Report

❌ Patch coverage is 69.38776% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.11%. Comparing base (2ef6022) to head (f24e7f3).
⚠️ Report is 903 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/cosign/cli/sign/sign_blob.go	42.85%	8 Missing ⚠️
cmd/cosign/cli/signblob.go	71.42%	4 Missing ⚠️
cmd/cosign/cli/options/signblob.go	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5083      +/-   ##
==========================================
+ Coverage   40.10%   47.11%   +7.00%     
==========================================
  Files         155      209      +54     
  Lines       10044    11795    +1751     
==========================================
+ Hits         4028     5557    +1529     
- Misses       5530     6238     +708     
+ Partials      486        0     -486     

☔ 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

Blob signing & verification

# Sign a blob to generate a bundle
cosign sign-blob --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]

Key-based / Certificate-backed Operations

Key-based, certificate-backed signing & verification

# Sign a blob using local key and request Fulcio certificate using TUF signing config
cosign sign-blob --key cosign.key --issue-certificate --bundle blob.bundle [BLOB_FILE]

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

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 --bundle blob.bundle [BLOB_FILE]

# Verify the blob bundle (verifying the signature, log proof and RFC 3161 timestamp against TUF trusted root)
cosign verify-blob --key cosign.pub --use-signed-timestamps --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

Blob signing & verification

# Sign a blob using local signing config and trusted root files
cosign sign-blob --signing-config [PATH_TO_SIGNING_CONFIG] --trusted-root [PATH_TO_TRUSTED_ROOT] --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]

Key-based Operations

Key-based, certificate-backed signing & verification

# Sign a blob using local key and request Fulcio certificate using local signing config
cosign sign-blob --key cosign.key --issue-certificate --signing-config [PATH_TO_SIGNING_CONFIG] --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle blob.bundle [BLOB_FILE]

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

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] --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle blob.bundle [BLOB_FILE]

# Verify the blob bundle against local trusted root file (including the RFC 3161 timestamp)
cosign verify-blob --key cosign.pub --trusted-root [PATH_TO_TRUSTED_ROOT] --use-signed-timestamps --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; the certificate is checked against the current time, so run this within its validity window or add --use-signed-timestamps)
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 (No RFC 3161 timestamp in the bundle)

# 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 (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]

# 4. Verify the bundle requiring a signed timestamp (should FAIL due to missing timestamp)
cosign verify-blob --trusted-root [PATH_TO_TRUSTED_ROOT] --bundle blob-no-tsa.bundle --use-signed-timestamps --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 a blob using a private key and no signing config (generates a simple bundle without log/timestamp verification material)
cosign sign-blob --key cosign.key --use-signing-config=false --bundle blob.bundle [BLOB_FILE]

# Verify the blob using the public key and bundle (the bundle has no log entry, so the tlog check has to be skipped)
cosign verify-blob --key cosign.pub --insecure-ignore-tlog --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-blob --rekor-url [URL] --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --timestamp-server-url [URL] --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --tlog-upload=false --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --new-bundle-format --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --rfc3161-timestamp [TS_PATH] --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --output-signature [SIG_PATH] --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --output-certificate [CERT_PATH] --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --output [OUTPUT_PATH] --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --b64=false --bundle blob.bundle [BLOB_FILE]

# 2. Enforces a signing config with a Fulcio CA for keyless and certificate-based signing
#    (should fail with "keyless signing requires a signing config with a Fulcio certificate authority"
#    and "certificate-based signing requires a signing config with a Fulcio certificate authority", respectively)
cosign sign-blob --use-signing-config=false --bundle blob.bundle [BLOB_FILE]
cosign sign-blob --key cosign.key --issue-certificate --use-signing-config=false --bundle blob.bundle [BLOB_FILE]
# Same check with a signing config that has services but no Fulcio CA (should fail with the keyless message)
cosign signing-config create --with-default-services --no-default-fulcio --out signing-config-no-fulcio.json
cosign sign-blob --signing-config signing-config-no-fulcio.json --bundle blob.bundle [BLOB_FILE]

# 3. Enforces bundle for blob signing (should fail with "please specify --bundle")
cosign sign-blob [BLOB_FILE]
cosign sign-blob --key cosign.key [BLOB_FILE]

[cmurphy]

This looks great! This change is really digestible, I appreciate how focused it is. I left a few small suggestions (disclosure: AI helped me find some of these).

[cmurphy]

I left one minor nitpick but I think this is good to merge as-is. Unfortunately it looks like the e2e-registry test is broken and needs an update in scaffolding.

[Hayden-IO]

I'm working on the scaffolding fix now!