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 keyDiagram: 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
cdxgenorsyft. 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.
Sign with the PKCS#11-enabled Cosign (recommended)¶
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:
- Build an in-toto statement with the SBOM as predicate and the artifact digest as subject.
- Hash the statement's DSSE pre-authentication encoding (PAE).
- Submit the hash as an ordinary sign order.
- Assemble a Sigstore DSSE bundle from the payload and the returned signature.
- 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:
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 |
Related pages¶
- Approvals: how operation approval works
- Signature Formats: the
cmsformat's detached mode is an alternative for consumers without cosign tooling, and also works for an SPDX SBOM