Sign Component Versions

Sigstore (keyless)

Sign with Sigstore — no key pair to generate, no public key to distribute.

If you’ve done classical key-based signing, here’s what changes:

Mental model: your identity is the key. When you sign, you log in with your OIDC provider (Google, GitHub, Microsoft, …). Sigstore issues a short-lived certificate that binds the signature to that identity. The verifier doesn’t need a public key from you — they just check that the identity in the certificate is one they trust.

You’ll end up with#

• A component version signed with a Sigstore keyless signature, tied to your OIDC identity

Estimated time: ~5 minutes

Prerequisites#

• OCM CLI installed
• A browser on the same machine (signing opens a browser window to log you in)
• A component version in a CTF archive or OCI registry (we’ll use github.com/acme.org/helloworld:1.0.0 from the getting started guide; any component you can write to works)

Steps#

1. Tell OCM to use Sigstore for signing#

   Add this entry to your .ocmconfig. It says “for the signature named default, get an OIDC token instead of using a private key”:

   type: generic.config.ocm.software/v1
   configurations:
   - type: credentials.config.ocm.software
     consumers:
     - identity:
         type: SigstoreSigner/v1alpha1
         signature: default
       credentials:
       - type: OIDCIdentityTokenProvider/v1alpha1

   That’s all the credential configuration you need. No keys, no paths.

   signature: default matches the default name ocm sign uses. Add more entries with different signature names if you want multiple Sigstore signing identities.

2. Create a minimal signer spec#

   Until Sigstore is the default signing handler, create sigstore-sign.yaml with one line — this picks the Sigstore signing handler and uses public Sigstore defaults:

   # sigstore-sign.yaml
   type: SigstoreSigningConfiguration/v1alpha1

   That’s it. No URLs, no keys, no certificates. The handler uses public Sigstore (fulcio.sigstore.dev, rekor.sigstore.dev) automatically.

3. Sign the component version#

   Run the sign command with the signer spec:

   Local CTF Archive

   ocm sign cv \
     --signer-spec ./sigstore-sign.yaml \
     /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0

   Remote OCI Registry

   ocm sign cv \
     --signer-spec ./sigstore-sign.yaml \
     ghcr.io/<your-namespace>//github.com/acme.org/helloworld:1.0.0

   A browser window opens against your OIDC provider’s login page. Authenticate, and you’ll see the OCM “Signing identity verified!” page. Return to the terminal — signing continues automatically.

   That’s the whole signing flow. No private key was generated, none was loaded from disk, and nothing needs to be distributed to verifiers. Your OIDC identity is what the verifier will check.

   Expected output from signing

   digest:
     hashAlgorithm: SHA-256
     normalisationAlgorithm: jsonNormalisation/v4alpha1
     value: 91dd197868907487e62872695db1fa7b397fde300bcbae23e24abc188fb147ad
   name: default
   signature:
     algorithm: sigstore
     issuer: https://github.com/login/oauth
     mediaType: application/vnd.dev.sigstore.bundle.v0.3+json
     value: ...
   
   time=2026-05-19T17:43:28.524+02:00 level=INFO msg="signed successfully" name=default digest=91dd197868907487e62872695db1fa7b397fde300bcbae23e24abc188fb147ad hashAlgorithm=SHA-256 normalisationAlgorithm=jsonNormalisation/v4alpha1

   If the cosign binary is not on your PATH or its version to low, OCM will download and cache the binary into ~/.cache/ocm/cosign/.... Subsequent runs skip the download.

4. Verify the signature was added#

   Check that the signature is present in the component descriptor:

   ocm get cv /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml

   Look for the signatures section in the output:

   signatures:
     - name: default
       digest:
         hashAlgorithm: SHA-256
         normalisationAlgorithm: jsonNormalisation/v4alpha1
         value: 91dd197...
       signature:
         algorithm: sigstore
         mediaType: application/vnd.dev.sigstore.bundle.v0.3+json
         value: <base64-bundle>

   The value field contains the full Sigstore bundle (signature + Fulcio certificate + Rekor inclusion proof).

Troubleshooting#

Symptom: “browser did not open” or “timed out waiting for authentication callback”#

Cause: The OIDC flow needs a browser on the machine running ocm sign, plus a free loopback port (127.0.0.1) for the OAuth callback.

Fix: Run on a workstation with a graphical browser. Headless / CI environments need a different identity flow (e.g. workload identity tokens supplied via the credentials config) — the interactive flow is not designed for unattended use.

Symptom: “OIDC provider does not support PKCE S256”#

Cause: The OIDC provider you’re using doesn’t support a security feature the OCM CLI requires for browser-based login.

Fix: Use a provider that supports it — public Sigstore (Google/GitHub/Microsoft via sigstore.dev) does, and most modern enterprise IdPs do too. If you’re pointing at a custom enterprise provider, check with your platform team.

Symptom: “issuer mismatch in callback”#

Cause: Your OIDC provider returned a different issuer URL than the one configured.

Fix: Make sure the issuer in .ocmconfig matches your provider’s canonical issuer URL exactly (scheme, host, path — trailing slashes matter). If you’re using public Sigstore defaults, you don’t need to set issuer at all.

Symptom: Permission denied on registry#

Cause: Missing write access to the OCI registry.

Fix: Configure registry credentials in .ocmconfig. See How-To: Configure Credentials for Multiple Registries.