Documentation
Getting started
On this page
j / k move between sections.
Docs / Publisher trust
Publisher trust
Choose who may publish build data and verify the evidence available for Cache, Artifacts, and Registry.
Publisher trust for Cache, Artifacts and Registry
A BoringCache signature records what the service accepted. A publisher attestation lets your own policy decide who produced the bytes. A checksum proves that bytes match a digest; it does not identify the producer.
| Feature | Content check | Protected BoringCache read |
|---|---|---|
| Cache | Archive, OCI, GitHub Actions cache, and compiler/KV content digests. | Restore verifies the configured publisher for the exact manifest or KV batch subject under your pinned policy. |
| Artifacts | Representation SHA-256 and a BoringCache-signed custody receipt. | Native pull and the BoringCache GitHub Actions Artifact service verify a separate publisher attestation before returning content. |
| Registry | Manifest and blob digests. | boringcache docker pull verifies the publisher, then pulls the exact image digest. Standard Docker and OCI pulls do not use this policy. |
Require a publisher
Put the policy in .boringcache.toml. Choose the publisher method used by your CI. Both examples allow a push to one repository's main branch from one workflow. Replace every identity with values from your own run.
BoringBuild: pin the issuer's public RSA key from <issuer>/_boringbuild/oidc/jwks and the forge origin. If the JWKS endpoint requires operator access, obtain the public key from that operator before setting the protected policy pin. The signing job needs id-token: write. Set workflow-ref to the exact signed claim. For a GitHub workflow, BoringBuild signs the resolved commit SHA, so update the protected policy pin when that workflow commit changes. Its path can differ on another connected forge. The key ID, modulus, and exponent must identify the same key. Keep old keys in the policy while you still need to restore entries signed by them.
[trust]
version = 1
attestor = "boringbuild-oidc"
verifier = "boringbuild-oidc"
on-failure = "miss"
[[trust.publishers]]
type = "boringbuild-oidc"
issuer = "https://ci.example.com"
forge-origin = "https://github.com"
repository-id = "12345678"
source-refs = ["refs/heads/main"]
events = ["push"]
workflow-ref = "acme/widgets/.github/workflows/ci.yml@0123456789abcdef0123456789abcdef01234567"
public-key = { kid = "<JWKS key ID>", n = "<JWKS RSA modulus>", e = "AQAB" }
GitHub Actions: use a Sigstore bundle backed by Fulcio and Rekor.
[trust] version = 1 attestor = "sigstore" verifier = "sigstore" on-failure = "miss" [[trust.publishers]] type = "sigstore-keyless" issuer = "https://token.actions.githubusercontent.com" repository-id = "12345678" source-refs = ["refs/heads/main"] events = ["push"] workflow-ref = "acme/widgets/.github/workflows/ci.yml@refs/heads/main"
Keep the SHA-256 of the complete policy file in protected organization, workflow, or runner configuration that repository contributors cannot change. Pass it as BORINGCACHE_TRUST_POLICY_SHA256, or as the Action's trust-policy-sha256 input. A missing or changed policy then fails before restore. A restore-only job may omit attestor. Publication with a CI identity provider requires the selected issuer through the Action or boringcache ci run.
The same publisher list applies to Cache, compiler/KV, Artifacts, and protected Registry pulls. With on-failure = "miss", an unverified Cache or tool-cache entry is a miss and an unverified GitHub Actions Artifact is hidden. An explicit Artifact or Registry pull fails without approved evidence because it has no alternate entry to use. With on-failure = "fail", verification failures stop the operation. Cache values produced within the same local proxy process remain available to that process.
boringcache docker pull services/web:latest --workspace acme/widgets
Use BoringCache commands or the BoringCache GitHub Actions compatibility service for protected reads. A direct API request, standard docker pull, or another client that bypasses these channels must verify publisher evidence itself.
Use your own signing key
The CLI can use cosign with a local private key for Cache, compiler/KV, Artifacts and Registry. Install cosign on publishing and restoring machines. Put the complete public key in the policy and protect the policy hash as described above.
[trust] version = 1 attestor = "cosign" verifier = "cosign" on-failure = "fail" [[trust.publishers]] type = "cosign-key" public-key-pem = '''-----BEGIN PUBLIC KEY----- <your complete public key> -----END PUBLIC KEY----- '''
On trusted publishing machines, set BORINGCACHE_TRUST_COSIGN_KEY to the absolute path of your local private key. Set COSIGN_PASSWORD if it is encrypted. Restore-only machines need only the pinned public key and may omit attestor. This method does not require OIDC or boringcache ci run.
Keep each approved key in a separate publisher entry during rotation. Removing a key from the protected policy rejects evidence signed only by that key. A key entry cannot also specify CI identity rules; choose the existing CI provider when you need those claims checked.
This method verifies the signed product kind and digest offline. It makes no transparency-log or timestamp claim. It does not upload standard OCI signatures for cosign verify IMAGE or Notation, and it does not support KMS URIs. Use the separate boringcache docker sign command for standard OCI signatures.
Trust a publisher certificate
Notation can verify publisher evidence for Cache, compiler/KV, Artifacts and protected Registry pulls. Install Notation 1.3.2 on publishing and restoring machines. Embed the approved CA certificate and permitted signer identities in the independently pinned policy.
[trust] version = 1 attestor = "notation" verifier = "notation" on-failure = "fail" [[trust.publishers]] type = "notation-certificate" certificate-pem = ''' -----BEGIN CERTIFICATE----- YOUR_APPROVED_CA_CERTIFICATE -----END CERTIFICATE----- ''' trusted-identities = ["x509.subject:C=US,ST=WA,O=Example,CN=Build Publisher"] revocation = "skip"
Set BORINGCACHE_TRUST_NOTATION_KEY and BORINGCACHE_TRUST_NOTATION_CERTIFICATE to absolute local paths on the publishing machine. The key must be an unencrypted PEM file; the certificate file contains the signing certificate and chain. Restore-only machines need only the pinned policy. Verification checks the certificate chain, signer identity, expiry, product kind and digest. It runs offline, so the policy must explicitly set revocation = "skip". Revoked certificates are not detected by this mode. Keep old approved roots in separate publisher entries while their evidence must remain readable.
This shared policy stores a product publisher bundle. To publish a signature discoverable by standard notation verify IMAGE, also run boringcache docker sign IMAGE --signer notation --key publisher.key --certificate publisher.crt.
Verify evidence outside BoringCache
Cache: an authorized client can read attestation summaries in a cache restore response, then fetch one bundle from GET /v2/workspaces/:namespace/:workspace/caches/:cache_entry_id/attestations/:id. Decode its bundle_data base64 field. Fetch the exact manifest or pointer bytes from the restore request and hash them locally. Compare the subject kind and digest with the evidence before applying the configured issuer, repository, ref, event, and workflow policy.
curl -fsS \ -H "Authorization: Bearer $BORINGCACHE_RESTORE_TOKEN" \ "https://api.boringcache.com/v2/workspaces/acme/widgets/caches/$ENTRY_ID/attestations/$ATTESTATION_ID" \ | jq -r '.bundle_data' | openssl base64 -d -A > cache.sigstore.json shasum -a 256 cache.sigstore.json
The command above names a Sigstore bundle. For BoringBuild, save the decoded bundle as cache.oidc.jwt. Compare its hash with bundle_sha256 in the attestation summary. The restore response also contains the exact manifest storage request; keep its returned headers when downloading the bytes.
For the candidate cosign-key method, the bundle signs a product statement. Hash the downloaded product bytes first. Write the exact compact JSON below to subject.json without a trailing newline, replacing both artifact values with the product kind and the digest placeholder with that SHA-256. Export publisher.pub from your independently pinned policy, not from the downloaded evidence.
{"_type":"https://in-toto.io/Statement/v1","predicate":{"kind":"artifact"},"predicateType":"https://boringcache.com/attestation/publisher-subject/v1","subject":[{"digest":{"sha256":"<64 lowercase hex characters>"},"name":"artifact"}]}
cosign verify-blob --key publisher.pub --bundle cache.sigstore.json --offline --insecure-ignore-tlog subject.json
cosign verify-blob-attestation \ --bundle cache.sigstore.json \ --certificate-identity 'https://github.com/acme/widgets/.github/workflows/ci.yml@refs/heads/main' \ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \ manifest.bin
For keyless Sigstore, read the verified in-toto statement as well. Its subject name must match the product kind, its digest must match the exact signed subject bytes, and its predicate type must be https://boringcache.com/attestation/publisher-subject/v1. The Cosign command checks the signature and subject digest; separately apply the repository ID, source ref, event, and workflow rules to the authenticated certificate.
For BoringBuild, verify the JWT's RS256 signature with the public key pinned in your policy. Its aud must equal urn:boringcache:publisher:v1:<kind>:sha256:<digest>; also check iss, forge_origin, repository_id, ref, event_name, workflow_ref, boringbuild_source_trust = trusted, and boringbuild_ingress = forge. An unverified JWT payload is not evidence.
Cache signs manifest or pointer bytes. KV signs a batch manifest that lists namespace, key, blob digest, and size. Artifacts sign the stored representation digest. Registry signs the OCI manifest digest. Authorized clients can fetch KV batch manifests from GET /v2/workspaces/:namespace/:workspace/cache-kv-publisher-batches/:id and Artifact or Registry bundles from GET /v2/workspaces/:namespace/:workspace/publisher-attestations/:id. Save the bundle, signed subject bytes, and pinned public key if verification must remain possible after access to BoringCache ends.
Artifacts: pull by immutable Artifact ID. The CLI checks the stored representation SHA-256 and extracted content digest before publishing the destination. The BoringCache GitHub Actions Artifact service downloads and verifies the complete Artifact before issuing a local download URL, which adds a wait before large protected downloads begin. The BoringCache-signed receipt records custody; the separate publisher bundle records the approved producer. A compressed directory's representation digest differs from the digest of its extracted files.
Registry: boringcache docker pull resolves a tag, verifies its signed manifest digest, and asks Docker to pull by that digest. Stock Docker and OCI clients can still pull without this policy. OCI referrers can hold other signatures, but their presence alone is not verification.
What the checks do not establish
A publisher attestation authenticates a subject digest and publisher. It does not bind a mutable tag or prove that the service returned the newest publication. A service can omit a cache entry or replay an older, correctly signed cache entry under a mutable tag. The same limit applies to a Registry tag that points to an older signed manifest. Require an independent record of the expected digest when freshness matters.
Public Sigstore transparency logs expose signing identity and subject digest metadata. BoringBuild OIDC evidence uses a pinned issuer key and has no public Rekor record. Decide which evidence and disclosure model your organization requires.
Publisher trust verifies the identity and signed subject. It does not establish that the build was reproducible, that dependencies were safe, or that the publisher's workflow was correct.
Need help or found something unclear? Open an issue or browse the CLI repo.