From ec95fd976202601b17475884b4e79d1d34ff0547 Mon Sep 17 00:00:00 2001 From: Andrew Dunn Date: Thu, 16 Apr 2026 00:15:53 -0400 Subject: [PATCH] docs: add signing-config and trusted-root workflow for self-hosted infrastructure Expand the custom components page with documentation for the cosign v3 signing-config and trusted-root workflow. This covers creating signing configurations, assembling trusted roots, and the signing/verification flow for self-hosted Sigstore infrastructure. Tested with cosign v3.0.6 against self-hosted Fulcio v1.6.6 and Rekor v1.3.8. Signed-off-by: Andrew Dunn --- .../cosign/system_config/custom_components.md | 105 +++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) diff --git a/content/en/cosign/system_config/custom_components.md b/content/en/cosign/system_config/custom_components.md index 3a1630fd..f6cfdca1 100644 --- a/content/en/cosign/system_config/custom_components.md +++ b/content/en/cosign/system_config/custom_components.md @@ -15,7 +15,7 @@ There are several options to configure Cosign to verify against custom component 2. Create a TUF repository yourself, using [go-tuf](https://github.com/theupdateframework/go-tuf) or [python-tuf](https://github.com/theupdateframework/python-tuf)'s repository writers. Instructions for how to configure this root is in this [blog post](https://blog.sigstore.dev/sigstore-bring-your-own-stuf-with-tuf-40febfd2badd). This [script](https://gist.github.com/asraa/947f1a38afd03af57c7b71d893c36af0) can be used to create a TUF repository from the custom Fulcio, Rekor, and CT log verification material. -3. TUF is recommended because it makes it easy to distribute up-to-date key material to clients. However, if you aren't using TUF, you can manually assemble trusted key material into a trusted root file with `cosign trusted-root create ...`. You can then supply that trusted root file to `cosign verify` commands with `--trusted-root`. +3. TUF is recommended because it makes it easy to distribute up-to-date key material to clients. However, if you aren't using TUF, you can manually assemble trusted key material into a trusted root file with `cosign trusted-root create ...`. You can then supply that trusted root file to `cosign verify` commands with `--trusted-root`. See the [signing configuration and trusted root](#signing-configuration-and-trusted-root) section below for the complete workflow. 4. As a last resort, you may also use the following environment variables to configure custom keys out of band. @@ -24,3 +24,106 @@ There are several options to configure Cosign to verify against custom component | SIGSTORE_REKOR_PUBLIC_KEY | This specifies an out of band PEM-encoded public key to use for a custom Rekor. | | SIGSTORE_ROOT_FILE | This specifies an out of band PEM-encoded X.509 certificate for a custom Fulcio root certificate. | | SIGSTORE_CT_LOG_PUBLIC_KEY_FILE | This specifies an out of band PEM-encoded or DER formatted public key for a custom CT log. | + +## Signing configuration and trusted root + +For cosign v3, you can provide your self-hosted service endpoints and +trust material as configuration files instead of environment variables +or CLI flags. + +### Create a signing configuration + +The signing configuration specifies where cosign sends signing requests. + +```shell +cosign signing-config create \ + --fulcio="url=https://fulcio.internal:5555,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org" \ + --rekor="url=https://rekor.internal:3000,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org" \ + --rekor-config="ANY" \ + --oidc-provider="url=https://idp.internal,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org" \ + --out signing-config.json +``` + +Each service flag takes a comma-separated list of key-value pairs. +Required keys: `url`, `api-version`, `start-time`, `operator`. +Optional: `end-time`. + +The `--rekor-config` flag is required when `--rekor` is specified. +Values: `ANY`, `ALL`, or `EXACT:`. +The `--tsa-config` flag is required when `--tsa` is specified. + +When you specify only your own services, the output contains only those +endpoints. To include the public Sigstore defaults alongside your +services, add `--with-default-services`. + +### Create a trusted root + +The trusted root provides verification material for your services. + +> **Note:** The `trusted-root create` command accepts different keys +> than `signing-config create`. Use `certificate-chain` for Fulcio +> and `public-key` for Rekor and CT log entries. + +```shell +cosign trusted-root create \ + --fulcio="url=https://fulcio.internal:5555,certificate-chain=/path/to/fulcio-root.pem,start-time=2024-01-01T00:00:00Z" \ + --rekor="url=https://rekor.internal:3000,public-key=/path/to/rekor-pub.pem,start-time=2024-01-01T00:00:00Z" \ + --ctfe="url=https://ctfe.internal:6962,public-key=/path/to/ctfe-pub.pem,start-time=2024-01-01T00:00:00Z" \ + --out trusted-root.json +``` + +| Flag | Required keys | Optional keys | +|------|--------------|---------------| +| `--fulcio` | `url`, `certificate-chain` | `start-time`, `end-time` | +| `--rekor` | `url`, `public-key`, `start-time` | `end-time`, `origin` | +| `--ctfe` | `url`, `public-key`, `start-time` | `end-time`, `origin` | +| `--tsa` | `url`, `certificate-chain` | `start-time`, `end-time` | + +### Sign with configuration files + +```shell +cosign sign-blob \ + --signing-config=signing-config.json \ + --trusted-root=trusted-root.json \ + --oidc-client-id=my-client-id \ + --identity-token=$ID_TOKEN \ + --bundle=artifact.bundle \ + artifact.txt +``` + +The `--oidc-client-id` must match the client ID configured in your +Fulcio OIDC issuer. This flag is not yet part of the signing +configuration format. + +For container images, use `cosign sign` with the same flags. +For attestations, use `cosign attest` or `cosign attest-blob`. + +Both configuration files are static. Generate them once and distribute +to signing and verification hosts. + +### Verify with a trusted root + +```shell +cosign verify-blob \ + --trusted-root=trusted-root.json \ + --bundle=artifact.bundle \ + --certificate-oidc-issuer=https://idp.internal \ + --certificate-identity=https://expected-identity \ + artifact.txt +``` + +### Use URL flags with cosign v3 + +To use `--fulcio-url` and `--rekor-url` flags with cosign v3, disable +automatic signing configuration resolution: + +```shell +cosign sign-blob \ + --use-signing-config=false \ + --fulcio-url=https://fulcio.internal:5555 \ + --rekor-url=https://rekor.internal:3000 \ + ... +``` + +The `--use-signing-config` and `--signing-config` flags are mutually +exclusive.