Skip to content

How-To: Sign SBOMs as Cosign Attestations

Produce a cosign-verifiable attestation that binds a Software Bill of Materials (SBOM) to an artifact digest, signed by a key held in the Keyserver. The SBOM itself is not modified. The recommended path uses the PKCS#11-enabled Cosign and takes one command.

For what the EU Cyber Resilience Act requires of SBOMs, see SBOMs and Supply-Chain Regulation.

Internal Authserver for Testing Only

On the trial environment the internal Authserver may be used for testing. Production signing must authenticate through an external OAuth2/OIDC provider, such as Azure Entra ID or GitLab OIDC. See the Authentication Model.

How it works

sequenceDiagram
    participant C as cosign (PKCS11 module)
    participant M as libpkcs11ks.so
    participant K as Keyserver
    participant R as Registry

    C->>C: build in-toto statement (subject = digest, predicate = SBOM)
    C->>C: encode DSSE payload, compute PAE, hash it
    C->>M: sign the PAE hash
    M->>K: POST /api/signorders (hash)
    K-->>M: signature (DER ECDSA)
    M-->>C: signature
    C->>R: push DSSE attestation as an OCI referrer
    Note over C,R: verify later with stock cosign + the public key

Diagram: cosign (PKCS11 module); libpkcs11ks.so; Keyserver; Registry; build in-toto statement (subject = digest, predicate = SBOM); encode DSSE payload, compute PAE, hash it; sign the PAE hash; POST /api/signorders (hash); signature (DER ECDSA); signature; push DSSE attestation as an OCI referrer; verify later with stock cosign + the public key

cosign builds an in-toto statement whose subject names the artifact by digest and whose predicate is the SBOM JSON, unchanged. That statement is the DSSE payload. The Keyserver signs the SHA-256 of its pre-authentication encoding (PAE), not the SBOM or the artifact. The PAE covers the payload type and the payload, so changing either the SBOM or the digest breaks verification. For a file ("blob"), cosign writes the signed bundle locally; for a container image, it pushes the bundle to the registry as an OCI referrer. The private key never reaches this machine: cosign sends only the hash, and the Keyserver returns the signature. This holds for KEYSTORE keys too: such a key leaves the Keyserver only through an explicit export.

Prerequisites

  • A PKCS#11-enabled Cosign build for signing. Verification uses stock cosign (v3.x) or the same build.
  • The Keyserver PKCS#11 module libpkcs11ks.so. See Getting the library.
  • curl, jq, openssl
  • An OAuth2 client whose subject has a role built from the fwsigner nature scoped to the signing key. See Manage Roles in the Keyserver.
  • The signing key's ID: a normal Keyserver FW key. This guide uses an EC/SHA-256 key, fw-quickstart.
  • An SBOM file in CycloneDX JSON format from your SBOM generator, for example cdxgen or syft. The SBOM is used byte-for-byte as the attestation predicate.
  • The artifact being attested: a container image (referenced by manifest digest) or a file

Set the base URL and authenticate as in Sign Container Images with Cosign:

export KSC_API_SERVER="https://keyserver.<UNIQUE-ID>.cryptera-security.io"
export AUTH_CREDS=$(printf '%s' "<CLIENT_ID>:<CLIENT_SECRET>" | base64 | tr -d '\n')

export TOKEN=$(
  curl -sS --tlsv1.3 \
    -X POST \
    -H "Authorization: Basic $AUTH_CREDS" \
    -d "grant_type=client_credentials" \
    https://authserver.<UNIQUE-ID>.cryptera-security.io/oauth2/token \
    | jq -r .access_token
)

[ -n "$TOKEN" ] && [ "$TOKEN" != null ] && echo "token OK (${#TOKEN} chars)"

Expected output: token OK ( followed by the token length. If it prints nothing, the credentials or the Authserver URL are wrong.

The Keyserver PKCS#11 module reads its connection from the environment. See the PKCS#11 Library Reference. The PKCS#11-enabled Cosign also needs a dummy, non-empty PIN (pin-value=1234 in the URI, or COSIGN_PKCS11_PIN) and COSIGN_PKCS11_IGNORE_CERTIFICATE=1, so it emits a plain key signature. See Configuration in the cosign guide.

Step 1: Get the public key (for verification)

curl -sS --tlsv1.3 \
  -H "Authorization: Bearer $TOKEN" \
  "$KSC_API_SERVER/api/keys/<KEYID>" | jq -r .certificate > cert.pem

openssl x509 -in cert.pem -noout -pubkey > pubkey.pem

Step 2: Create and approve a signing operation

Create and approve an operation for <KEYID> as in Step 3: Create and Approve a Signing Operation of the cosign guide, then export the module's environment:

export KSC_ID_TOKEN="$TOKEN"
export KSC_OPERATION_ID="<approved-operation-id>"
export COSIGN_PKCS11_IGNORE_CERTIFICATE=1

Step 3: Attest the SBOM

Keep both transparency-log flags

The commands below pass --use-signing-config=false --tlog-upload=false. With either flag missing, cosign uploads attestation metadata to the public Sigstore transparency log. See the transparency-log warning under Sign in the cosign guide.

For a plain-HTTP local test registry, add --allow-http-registry to the attest and verify commands. See the warning under Step 6: Attach the Signature to the Image of the cosign guide. Never use it with a production registry.

For a container image, cosign signs and pushes the attestation as an OCI referrer in one step:

cosign attest \
  --key "pkcs11:token=KEYSERVER;object=<KEYID>;type=private?module-path=/path/to/libpkcs11ks.so&pin-value=1234" \
  --predicate sbom.cdx.json --type cyclonedx \
  --use-signing-config=false --tlog-upload=false \
  <REGISTRY>/<IMAGE>@<DIGEST>

For a file or firmware image, cosign writes the signed bundle locally:

cosign attest-blob \
  --key "pkcs11:token=KEYSERVER;object=<KEYID>;type=private?module-path=/path/to/libpkcs11ks.so&pin-value=1234" \
  --predicate sbom.cdx.json --type cyclonedx \
  --use-signing-config=false --tlog-upload=false \
  --bundle bundle.json firmware.bin

Step 4: Verify

For a container image:

cosign verify-attestation \
  --key pubkey.pem \
  --insecure-ignore-tlog=true \
  --type cyclonedx \
  <REGISTRY>/<IMAGE>@<DIGEST>

For a file or firmware image:

cosign verify-blob-attestation \
  --key pubkey.pem \
  --bundle bundle.json \
  --insecure-ignore-tlog=true \
  --type cyclonedx \
  firmware.bin

--insecure-ignore-tlog=true is required because nothing was uploaded to the log. See Step 7: Verify of the cosign guide.

Doing it without the PKCS#11 cosign

Stock cosign and a normal Keyserver sign order can produce an equivalent attestation, verified the same way, without the PKCS#11 build. In outline:

  1. Build an in-toto statement with the SBOM as predicate and the artifact digest as subject.
  2. Hash the statement's DSSE pre-authentication encoding (PAE).
  3. Submit the hash as an ordinary sign order.
  4. Assemble a Sigstore DSSE bundle from the payload and the returned signature.
  5. For a container image, push the bundle as an OCI referrer with OCI-aware tooling such as oras.

Verification is the same as in Step 4. This route has more parts to build and maintain, so prefer the PKCS#11 path. See Sign Code Using the REST API for the sign-order mechanics.

What a Verification Failure Means

Any change to a single byte of the SBOM, including re-serializing it with different key order or whitespace, changes the DSSE payload and therefore the PAE, so the signature no longer matches. cosign verify-attestation and cosign verify-blob-attestation both report this the same way:

error: no matching signatures:
accepted signatures do not match threshold, Found: 0, Expected 1

The message is the same for tampering, a wrong SBOM, or a stale attestation. Re-attest with the exact SBOM bytes and verify again.

If something fails

Symptom Cause and fix
Token check prints nothing Wrong credentials or Authserver URL (see the cosign guide's prerequisites)
cosign attest fails with an authorization or sign-order error Operation not created or approved, key not part of the operation, usage count exhausted, validms expired, or the subject lacks the fwsigner permission for the key (see Error Codes)
cosign attest fails with CKR_ARGUMENTS_BAD Empty PIN. Pass a non-empty dummy pin-value (see the PKCS#11-enabled Cosign build)
Verify reports "Found: 0, Expected 1" The SBOM or predicate changed after signing, or the wrong pubkey.pem. Re-attest with the exact SBOM and check the key
cosign verify-attestation finds no attestation for the image Attestation pushed to the wrong digest, or (manual route) the bundle was never pushed as an OCI referrer
  • Approvals: how operation approval works
  • Signature Formats: the cms format's detached mode is an alternative for consumers without cosign tooling, and also works for an SPDX SBOM