Verify Component Versions

Goal

Validate a component version signature to ensure it is authentic and has not been tampered with. OCM supports multiple verification algorithms. Pick the tab that matches the algorithm the signature was made with — each tab is a self-contained walkthrough.

Verify an RSA signature using the matching public key configured in .ocmconfig.

To run this you need the signer’s public key on disk and pointed at by .ocmconfig (see prerequisites). With Sigstore (other tabs) you don’t install a public key at all — you just declare which identity you trust.

You’ll end up with

  • Confidence that a component version is authentic and hasn’t been tampered with

Estimated time: ~3 minutes

Prerequisites

Steps

  1. Verify the component version

    Run the verify command against your signed component:

    ocm verify cv <repository>//<component>:<version>

    Local CTF Archive:

    ocm verify cv /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0

    Remote OCI Registry:

    ocm verify cv ghcr.io/<your-namespace>//github.com/acme.org/helloworld:1.0.0
    Expected output
    time=2025-11-19T15:58:22.431+01:00 level=INFO msg="verifying signature" name=default
time=2025-11-19T15:58:22.435+01:00 level=INFO msg="signature verification completed" name=default duration=4.287541ms
time=2025-11-19T15:58:22.435+01:00 level=INFO msg="SIGNATURE VERIFICATION SUCCESSFUL"

    The command exits with status code 0 on success.

  2. Verify a specific signature (optional)

    If the component has multiple signatures, specify which one to verify:

    ocm verify cv --signature prod ghcr.io/<your-namespace>//github.com/acme.org/helloworld:1.0.0

    👉 Without the --signature flag, every signature on the descriptor is verified, not just one named default. Each is verified under its own name, so each needs a matching consumer entry.

  3. List available signatures (optional)

    View all signatures in a component version:

    ocm get cv ./tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | grep -A 10 signatures:

Troubleshooting (RSA)

Symptom: “signature verification failed”

Cause: Public key doesn’t match the signing private key, or the component was modified after signing.

Fix: Ensure you’re using the correct public key that corresponds to the private key used for signing:

# Check which signature names exist
ocm get cv /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | grep -A 3 "signatures:"

# Verify with the correct signature name
ocm verify cv --signature <name> /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0

Symptom: “no public key found”

Cause: OCM cannot find a matching verification configuration in .ocmconfig.

Fix: Ensure your .ocmconfig has a consumer entry with the matching signature name and public_key_pem_file path.

See Configure Signing Credentials.

Symptom: “invalid key format”

Cause: The public key file is not in PEM format.

Fix: Verify the key starts with -----BEGIN PUBLIC KEY-----:

head -n 1 /tmp/keys/public-key.pem

Verify a GPG (OpenPGP) signature using the public key configured in .ocmconfig. Verification takes the handler from the same .ocmconfig, so put the type: GPGSigningConfiguration/v1alpha1 you configured for signing under the verifier field as well.

To run this you need the signer’s public key on disk and pointed at by publicKeyPGPFile in .ocmconfig. With Sigstore (other tabs) you don’t install a public key at all — you just declare which identity you trust.

You’ll end up with

  • Confidence that a GPG-signed component version is authentic and hasn’t been tampered with

Estimated time: ~2 minutes

Prerequisites

Steps

  1. Point .ocmconfig at the signer’s public key

    If you signed locally, the same .ocmconfig you wrote on the sign page already works — skip to the next step.

    If you’re verifying a signature someone else produced, follow How-To: Configure Signing Credentials → GPG using only the signer’s public key (publicKeyPGPFile); the privateKeyPGPFile entry is not needed for verification.

    Add a verifier to the same signing.config.ocm.software/v1alpha1 entry you created as the signer in the sign how-to → GPG tab. RSA is the default when no verifier is configured, so this is what tells ocm verify to use GPG:

    - type: signing.config.ocm.software/v1alpha1
  signer:
    type: GPGSigningConfiguration/v1alpha1
  verifier:
    type: GPGSigningConfiguration/v1alpha1                     # added

    If you are only verifying, the signer field can be left out entirely:

    - type: signing.config.ocm.software/v1alpha1
  verifier:
    type: GPGSigningConfiguration/v1alpha1

    Give the entry a signature field to scope it to a single signature; without one it applies to every signature. Because the verifier is resolved per signature, a component carrying a GPG signature next to an RSA one can be verified in a single run, each with its own handler.

    signature: default applies to a signature named default; it is not a catch-all for an omitted --signature flag. If the signature was created with --signature <name>, set the same value in the consumer identity.

    Consumer identities are matched exactly. Credentials are looked up under the name of the signature being verified, so a signature: default entry does not serve a signature named prod, and an entry with no signature field at all matches nothing. Give every signature its own consumer entry, otherwise a run without --signature fails on the signatures that have no matching credential.

  2. Verify the component version

    Run the verify command. The GPG handler comes from the config entry you just added.

    ocm verify cv \
  /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0
    Expected output
    time=2026-06-15T12:03:39.929+02:00 level=INFO msg="verifying signature" name=default
time=2026-06-15T12:03:39.930+02:00 level=INFO msg="signature verification completed" name=default duration=894.458µs
time=2026-06-15T12:03:39.930+02:00 level=INFO msg="SIGNATURE VERIFICATION SUCCESSFUL"

    The command exits with status code 0 on success.

  3. Verify a specific signature (optional)

    If the component carries multiple signatures (e.g. a GPG signature alongside an RSA one), select the one to verify by name:

    ocm verify cv \
  --signature prod \
  /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0

    Without --signature, every signature on the descriptor is verified. Configuration and credentials are resolved separately for each one, under that signature’s own name.

Troubleshooting

Symptom: SIGNATURE VERIFICATION FAILED: gpg verify: openpgp: signature made by unknown entity

Cause: The public key in .ocmconfig doesn’t match the key that signed — most often because you exported a different key, or the signer rotated their key after signing.

Fix: Confirm publicKeyPGPFile points at the verifier-key file the signer actually shared. If you signed locally, re-run the export step from the sign how-to to regenerate verify-key.asc from the same fingerprint.

Symptom: SIGNATURE VERIFICATION FAILED: load GPG public key: load public key: open ...: no such file or directory

Cause: The publicKeyPGPFile path in .ocmconfig doesn’t exist on disk.

Fix: Check the path is correct and readable. Absolute paths avoid working-directory surprises.

Symptom: SIGNATURE VERIFICATION FAILED: no key matching fingerprint "..." found in keyring

Cause: The verifier contains a keyFingerprint that doesn’t match any key resolved from the public-key file.

Fix: Either remove keyFingerprint from the verifier (any key in the file will be tried) or correct it. Run gpg --show-keys /tmp/keys/verify-key.asc to confirm the actual fingerprint.

Verify a Sigstore keyless signature made by a person who logged in via a browser. There’s no public key to install on this side either — you tell OCM which identity you trust, and it checks the signature was made by that identity.

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

AspectRSASigstore
Before you startObtain the signer’s public key, configure .ocmconfigNothing — declare expected identity in .ocmconfig
What proves trustSignature decrypts with the public key you haveSignature ties back to an OIDC identity you’ve decided to trust
What the verifier needsThe signer’s public key (rotated and re-distributed)The expected OIDC identity and issuer — no long-lived key

For the conceptual picture (how Fulcio, Rekor, and OIDC fit together), see Identity-Based Trust (Sigstore).

You’ll end up with

  • Confidence that a component version was signed by an identity you trust

Estimated time: ~3 minutes

Prerequisites

For the end-to-end walkthrough including Fulcio certificate validation, Rekor inclusion proofs, and TUF trust roots, see Tutorial: Sigstore (Keyless). Design background lives in ADR 0017: Sigstore Integration.

Steps

  1. Declare which identity you trust

    In Sigstore, the verifier’s only job is to decide whose signatures to accept. You do that with a verifier entry in your .ocmconfig.

    Two values matter:

    • certificateIdentity — the email or workload identity of whoever signed (e.g. jane.doe@example.com)
    • certificateOIDCIssuer — which OIDC provider they logged in with (e.g. GitHub vs. Google — both could have a jane.doe@example.com)

    Add the entry to the configurations list of your .ocmconfig:

    - type: signing.config.ocm.software/v1alpha1
  verifier:
    type: SigstoreVerificationConfiguration/v1alpha1
    certificateOIDCIssuer: https://github.com/login/oauth
    certificateIdentity: jane.doe@example.com

    That’s the entire trust configuration. No public key to fetch, no certificate to install.

    Pick the right certificateOIDCIssuer value

    On public Sigstore (oauth2.sigstore.dev), the issuer recorded in the signing certificate is the upstream identity provider’s issuer URL — not the Sigstore Dex endpoint. Pick the one matching the provider the signer logged in with:

    Signer logged in viacertificateOIDCIssuer value
    Googlehttps://accounts.google.com
    GitHubhttps://github.com/login/oauth
    Microsofthttps://login.microsoftonline.com

    Both certificateOIDCIssuer and certificateIdentity are required. They’re what makes the signature meaningful — without them you’d be accepting any Sigstore signature from anyone.

    Read the identity from an existing signature

    Already have a signed component version and want the exact identity to paste into your spec? Decode the Fulcio certificate. The OIDC issuer is recorded under the Sigstore-defined OID 1.3.6.1.4.1.57264.1.1; for interactive (browser) logins the identity is the email: entry in the Subject Alternative Name. The cert is buried two base64 layers deep:

    REF=ctf::./ctf//github.com/acme.org/helloworld:1.0.0

ocm get cv "$REF" -o yaml \
  | yq '.[].signatures[]? | select(.signature.algorithm == "Sigstore/v1alpha1") | .signature.value' \
  | head -1 | base64 -d | jq -r '.verificationMaterial.certificate.rawBytes' \
  | base64 -d | openssl x509 -inform DER -noout -text \
  | awk '
    /1.3.6.1.4.1.57264.1.1:/ {flag="issuer"; next}
    /^[[:space:]]*X509v3 /    {san=0}
    /Subject Alternative Name/ {san=1}
    san && /^ *email:/ {sub(/^[ \t]*email:/,""); print "certificateIdentity:    " $0; next}
    flag=="issuer" {sub(/^[ \t]+/,""); print "certificateOIDCIssuer: " $0; flag=""}
  '

    Output is two lines you can paste straight under the verifier field. (CI/workload signatures use a URI: SAN instead — see the Sigstore (CI) tab.)

  2. Verify the component version

    Run the verify command. The Sigstore handler and the identity constraints both come from the config entry you just added.

    ocm verify cv \
  /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0
    ocm verify cv \
  ghcr.io/<my-namespace>//github.com/acme.org/helloworld:1.0.0
    Expected output
    time=2026-05-19T18:49:13.316+02:00 level=INFO msg="verifying signature" name=default
time=2026-05-19T18:49:13.856+02:00 level=INFO msg="signature verification completed" name=default duration=539.512209ms
time=2026-05-19T18:49:13.856+02:00 level=INFO msg="SIGNATURE VERIFICATION SUCCESSFUL"

  3. Verify a specific signature

    If the component carries multiple signatures (e.g. an RSA signature and a Sigstore signature), select one by name with --signature. The name is whatever was set at sign time — default if no --signature flag was passed when signing. Omitting the flag here verifies every signature rather than picking one:

    ocm verify cv \
  --signature default \
  ghcr.io/<your namespace>//github.com/acme.org/helloworld:1.0.0

    The verifier’s type field decides which algorithm/handler verifies the signature. The --signature flag picks which named signature on the component to verify (matched by name, not by algorithm).

    You can also scope a config entry itself to one signature by giving it a signature field. The verifier is then resolved per signature, so a run without --signature verifies every signature, each with the handler its own name resolves to.

Troubleshooting

Symptom: “no matching CertificateIdentity found”

Cause: The signature was made by a different identity than what your spec expects — or the same identity but via a different OIDC provider.

The full error names which side did not match. For an identity mismatch:

Error: SIGNATURE VERIFICATION FAILED: cosign verify-blob failed: exit status 1
stderr: Error: failed to verify certificate identity: no matching CertificateIdentity found, last error: expected SAN value "nobody@nowhere.invalid", got "john.doe@gmail.com"

For an issuer mismatch:

Error: SIGNATURE VERIFICATION FAILED: cosign verify-blob failed: exit status 1
stderr: Error: failed to verify certificate identity: no matching CertificateIdentity found, last error: expected issuer value "https://accounts.google.com", got "https://github.com/login/oauth"

Fix: Update certificateIdentity / certificateOIDCIssuer in your verifier config to match the identity actually recorded in the signature. Watch for trailing slashes and capitalization. To read the actual identity recorded in the signature, use the decode recipe in Step 1 (or see Tutorial: Sigstore (Keyless) — Inspect the signature).

Symptom: “keyless verification requires both an issuer constraint … and an identity constraint”

Cause: Your verifier config is missing certificateIdentity, certificateOIDCIssuer, or both.

The full error:

Error: SIGNATURE VERIFICATION FAILED: invalid verification config: keyless verification requires both an issuer constraint (CertificateOIDCIssuer or CertificateOIDCIssuerRegexp) and an identity constraint (CertificateIdentity or CertificateIdentityRegexp)

Fix: Both are mandatory — they’re how Sigstore knows whose signatures to accept. See Step 1 above.

Verify a Sigstore signature that was created in a CI pipeline. Verification works exactly like the interactive case — only the identity you trust is different. Instead of a person’s email and a consumer OIDC issuer (Google, GitHub, Microsoft), you trust a CI workflow’s identity issued by a CI-provider OIDC.

You’ll end up with

  • Confidence that a component version was signed by a specific CI workflow you trust

Estimated time: ~3 minutes

Prerequisites

Steps

  1. Identify what to trust

    Two values are still required: certificateOIDCIssuer (which IdP minted the workload-identity token) and certificateIdentity (the workflow URL the IdP stamps into the cert).

    For GitHub Actions the values are:

    FieldValue
    certificateOIDCIssuerhttps://token.actions.githubusercontent.com
    certificateIdentityhttps://github.com/<org>/<repo>/.github/workflows/<file>@refs/heads/<branch>
    Other CI providers (GitLab, Buildkite, self-hosted, …)

    The mechanism is the same; only the issuer URL and identity shape are provider-specific. Two ways to find them:

    • Read your provider’s OIDC discovery document at https://<provider>/.well-known/openid-configuration — the issuer field is what goes into certificateOIDCIssuer.

    • Decode an existing signature to read the values directly. The OIDC issuer is recorded in the Fulcio cert under the Sigstore-defined OID 1.3.6.1.4.1.57264.1.1 (the same OID is used by every Fulcio deployment — public Sigstore, scaffolding stacks, enterprise installs); the SAN identity is in the URI: line. Yes, this recipe is ugly — there’s no clean field for it on the OCM side, and the cert itself is buried two base64 layers deep:

      REF=ctf::./ctf//github.com/acme.org/helloworld:1.0.0

ocm get cv "$REF" -o yaml \
  | yq '.[].signatures[]? | select(.signature.algorithm == "Sigstore/v1alpha1") | .signature.value' \
  | head -1 | base64 -d | jq -r '.verificationMaterial.certificate.rawBytes' \
  | base64 -d | openssl x509 -inform DER -noout -text \
  | awk '
    /1.3.6.1.4.1.57264.1.1:/ {flag="issuer"; next}
    /^[[:space:]]*X509v3 /    {san=0}
    /Subject Alternative Name/ {san=1}
    san && /URI:/ {sub(/.*URI:[ \t]*/,""); print "certificateIdentity:    " $0; next}
    flag=="issuer" {sub(/^[ \t]+/,""); print "certificateOIDCIssuer: " $0; flag=""}
  '

      Output is two lines you can paste straight under the verifier field.

      Note: ocm get cv -o yaml also shows a signature.issuer field on the OCM signature object — don’t rely on it for verification. The cert is the authoritative source.

  2. Configure the verifier

    Add the entry to the configurations list of your .ocmconfig:

    - type: signing.config.ocm.software/v1alpha1
  verifier:
    type: SigstoreVerificationConfiguration/v1alpha1
    certificateOIDCIssuer: https://token.actions.githubusercontent.com
    certificateIdentity: https://github.com/acme/helloworld/.github/workflows/release.yml@refs/heads/main

    For GitHub Actions you often want to accept a release workflow on any ref (any branch, any tag). Use certificateIdentityRegexp instead of certificateIdentity:

    - type: signing.config.ocm.software/v1alpha1
  verifier:
    type: SigstoreVerificationConfiguration/v1alpha1
    certificateOIDCIssuer: https://token.actions.githubusercontent.com
    certificateIdentityRegexp: ^https://github\.com/acme/helloworld/\.github/workflows/release\.yml@refs/.*$

    Exactly one of certificateIdentity or certificateIdentityRegexp is required (same applies to issuer’s *Regexp form).

  3. Verify the component version

    ocm verify cv \
  /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0
    ocm verify cv \
  ghcr.io/<your-namespace>//github.com/acme.org/helloworld:1.0.0

    A successful run prints SIGNATURE VERIFICATION SUCCESSFUL. The same --signature <name> flag from the interactive tab applies if the component carries multiple signatures.

Troubleshooting

Symptom: identity mismatch with a long workflow URL

Cause: Subtle differences in the workflow path: ref type (refs/heads/ vs refs/tags/), branch name, file casing, or trailing slashes.

Fix: Decode the actual cert (recipe in Step 1) and copy the URI: line verbatim into certificateIdentity. For multi-ref signing, switch to certificateIdentityRegexp.

Issuer mismatch with a non-GitHub CI

Cause: Other CI providers — GitLab, Buildkite, self-hosted runners — issue tokens from their own URL, not https://token.actions.githubusercontent.com.

Fix: Set certificateOIDCIssuer to your provider’s issuer URL (find it under https://<provider>/.well-known/openid-configuration → issuer). The certificateIdentity shape is provider-specific too — decode an existing cert (recipe in Step 1) to read the actual SAN.

CLI Reference

CommandDescription
ocm verify component-versionVerify a component version signature
ocm get component-versionView component with signatures

Next Steps

Prev
Plugin System
Next
Ownership