From de811190883388f11b1046da9b7209ad83281e14 Mon Sep 17 00:00:00 2001 From: Ronen Slavin Date: Sun, 20 Sep 2026 12:14:52 +0300 Subject: [PATCH] docs: scope keyless-only inputs and correct KMS backend support The timestamp and transparency-log inputs are forwarded to the CLI only when `keyless: true`, and the CLI applies them only in keyless mode, but the README inputs table and the action.yml descriptions presented them as generally applicable. The air-gapped section recommends `sign-key` immediately above that table, so the combination read as supported. - Mark tlog-upload, include-timestamp, fulcio-server-url, rekor-server-url, timestamp-server-url and allow-submit-data-to-public-sigstore as keyless-only in both the README table and the action.yml input descriptions. - Add the previously undocumented include-timestamp input to the table. - Note in the air-gapped section that signatures produced with sign-key or a KMS provider carry no timestamp. - Correct the KMS bullet: Vault transit is the only implemented backend, so drop the awskms example. Documentation only. action.yml is read directly by the Actions runtime, so no dist rebuild is required. Co-Authored-By: Claude Opus 5 --- attest/README.md | 24 +++++++++++++++++------- attest/action.yml | 10 +++++----- 2 files changed, 22 insertions(+), 12 deletions(-) diff --git a/attest/README.md b/attest/README.md index b4e8bed..194c69b 100644 --- a/attest/README.md +++ b/attest/README.md @@ -47,14 +47,23 @@ If your environment cannot submit to the public Sigstore transparency log (e.g. customers in the USA / EU with data-residency requirements), use one of: -- **KMS signing**: `--kms vault://` (HashiCorp Vault transit) or - `--kms awskms://` (AWS KMS) — signature stays in your control. +- **KMS signing**: `--kms vault://` (HashiCorp Vault transit). + The signature stays in your control. Vault transit is the only KMS + backend implemented today. - **Keyed signing with checked-in private key**: `sign-key: private-key.pem`. - **Private Sigstore**: deploy your own Fulcio + Rekor and pass `fulcio-server-url` + `rekor-server-url`. See the inputs section below for the full list. +> **RFC 3161 timestamping is not available with keyed or KMS signing.** +> `include-timestamp` and `timestamp-server-url` are forwarded to the +> CLI only when `keyless: true`, and the CLI itself applies timestamping +> only in keyless mode. A signature produced with `sign-key` or a KMS +> provider carries no timestamp, so it has no time anchor proving it was +> made before the key was rotated or compromised. This is a known gap +> and we intend to close it. + ## Inputs | Name | Description | Default | @@ -64,11 +73,12 @@ See the inputs section below for the full list. | `skip-source-tree-check` | Skip verifying the source tree matches the recorded commit | `false` | | `sign-key` | Path to a private ECDSA/RSA/ED25519 PEM key | — | | `keyless` | Use keyless (Sigstore) signing | `false` | -| `tlog-upload` | Upload signature to Rekor transparency log | `true` | -| `fulcio-server-url` | Fulcio server URL | `https://fulcio.sigstore.dev` | -| `rekor-server-url` | Rekor server URL | `https://rekor.sigstore.dev` | -| `timestamp-server-url` | RFC3161 timestamp server URL | — | -| `allow-submit-data-to-public-sigstore` | Required when using public Sigstore | `false` | +| `tlog-upload` | **Keyless only.** Upload signature to Rekor transparency log | `true` | +| `include-timestamp` | **Keyless only.** Request an RFC 3161 timestamp and embed it in the signature | `false` | +| `fulcio-server-url` | **Keyless only.** Fulcio server URL | `https://fulcio.sigstore.dev` | +| `rekor-server-url` | **Keyless only.** Rekor server URL | `https://rekor.sigstore.dev` | +| `timestamp-server-url` | **Keyless only.** RFC3161 timestamp server URL. Not forwarded to the CLI unless `keyless: true` | — | +| `allow-submit-data-to-public-sigstore` | **Keyless only.** Required when using public Sigstore | `false` | | `provenance-output` | Path for unsigned provenance | `provenance.intoto.jsonl` | | `signed-provenance-output` | Path for signed provenance | `provenance.intoto.jsonl.sig` | | `report-job-summary` | Render provenance in the workflow job summary | `true` | diff --git a/attest/action.yml b/attest/action.yml index 098c4e6..2102c97 100644 --- a/attest/action.yml +++ b/attest/action.yml @@ -48,23 +48,23 @@ inputs: required: false default: 'false' tlog-upload: - description: Allow the creation of a Rekor transparency log (TLog) entry. + description: 'Keyless signing only: allow the creation of a Rekor transparency log (TLog) entry. Ignored unless keyless is true.' required: false default: 'true' include-timestamp: - description: Allow timestamping of the artifact signature against a timestamping authority. + description: 'Keyless signing only: allow RFC 3161 timestamping of the artifact signature against a timestamping authority. Ignored unless keyless is true.' required: false default: 'false' fulcio-server-url: - description: Fulcio server URL + description: 'Keyless signing only: Fulcio server URL' required: false default: 'https://fulcio.sigstore.dev' rekor-server-url: - description: Rekor server URL + description: 'Keyless signing only: Rekor server URL' required: false default: 'https://rekor.sigstore.dev' timestamp-server-url: - description: Timestamp server URL + description: 'Keyless signing only: timestamp server URL. Not forwarded to the CLI unless keyless is true.' required: false allow-submit-data-to-public-sigstore: description: Agree to submit data to an immutable public transparency log (Needed for public Sigstore)