Download the PHP package k2gl/sigstore-verify without Composer

k2gl/sigstore-verify

Offline, fail-closed Sigstore bundle verifier for PHP. Give it a .sigstore.json bundle, a trust root, and the identity you expect; it verifies the evidence and returns the authenticated content, or throws. It passes Sigstore's official conformance suite in full, across Rekor v1 and v2, so its behaviour matches the reference clients.

It handles both bundle shapes: DSSE attestations (cosign attest, npm provenance, SLSA provenance) and message signatures (cosign sign-blob artifact signatures), with either signing identity: a keyless Fulcio certificate or a public key you supply out of band. The signing key may be ECDSA over NIST P-256/P-384/P-521, RSA, or — for DSSE — Ed25519. It answers "is this genuine, and did the identity I trust produce it?" in pure PHP, with no network calls during verification.

What it verifies

Every one of these must pass or verification throws:

1. Certificate chain (keyless bundles) — the Fulcio leaf certificate chains to a trusted CA from the supplied trusted root, every certificate in the path is valid at the signing time, and the leaf is issued for code signing (code-signing extended key usage). For a public-key bundle there is no certificate; trust rests on the key you supply, and the optional key hint must match if you pass one.
2. Signature — the DSSE envelope signature, or the artifact's message signature, verifies under the signing key (the leaf certificate's key, or the public key you supply).
3. Transparency log — each Rekor entry is proven by its signed entry timestamp and/or its Merkle inclusion proof (recomputed per RFC 6962, against a signed checkpoint), and the entry is bound to this bundle by its recorded hash.
4. Timestamp — when the bundle carries an RFC 3161 timestamp, the token must verify against a trusted Timestamp Authority from the trusted root (the token signature, its certificate chain valid at that time, and the imprint of the bundle signature), and its genTime becomes the signing time. With no timestamp, the Rekor integrated time stands in.
5. Certificate transparency (keyless bundles) — when the trusted root provides CT logs, the leaf certificate's embedded Signed Certificate Timestamp must verify (RFC 6962) under a trusted CT log whose operating window covers it, proving Fulcio publicly logged the certificate's issuance.
6. Identity policy (keyless bundles) — the certificate's subject alternative name and OIDC issuer match what you require.

There is no "best effort" path: anything missing, unsupported, or invalid raises a SigstoreException. A returned value always means every applicable check held.

Install

Requires PHP 8.1+, ext-openssl, and phpseclib/phpseclib (certificate parsing) — either the 3.x or the 4.x line, whichever your project already has; ext-sodium is needed for Ed25519 — DSSE Ed25519 keys and Rekor v2 checkpoint notes. Pulls in k2gl/in-toto-attestation, k2gl/signed-note (checkpoint parsing) and k2gl/dsse.

Command line

The package ships a dependency-free binary for pipelines and one-off checks. Given an artifact and its attestation bundle (plain JSON or the JSON Lines file written by gh attestation download), it verifies the signature, the transparency-log proof, the signer identity and the artifact digest in one call:

Exit code 0 means verified; any failure prints the fail-closed reason and exits 1. --trusted-root path/to/trusted_root.json makes the run fully offline; without it the public-good root is fetched via TUF. For non-GitHub signers pass the exact certificate identity instead: --san <value> --issuer <issuer>. With a JSON Lines file the command succeeds when any bundle verifies the artifact.

The trusted root

Verification runs against a Sigstore trusted_root.json. You can supply it three ways.

Supply it yourself with TrustedRoot::fromJson(). Obtain the JSON with the Sigstore CLI and keep it current — a stale or substituted trust root would silently undermine every verification:

Resolve it over TUF with TrustedRoot::fromTuf(), given a K2gl\Tuf\Updater you build. The TUF client refreshes the metadata and verifies the trusted_root.json target's length and hashes before it is parsed, so the repository keeps the root current under its own rotation rules. The verifier core stays offline — the network is reached only through the updater's fetcher.

For the public-good instance, TrustedRoot::fromSigstorePublicGood() is the convenience over fromTuf(): it points an updater at tuf-repo-cdn.sigstore.dev, using a bundled root.json as the trust-on-first-use anchor that TUF rotates forward.

Usage

If you already hold the bundle and trusted root as JSON strings, verifyFromJson() is the one-line shorthand:

Sigstore bundles carry in-toto Statement v0.1 and v1; authentication does not depend on the schema version, so the verifier hands back the envelope and leaves statement modelling to you.

Pinning the signing identity

The identity policy is mandatory for keyless bundles. Beyond an exact SAN you can match the signer with a pattern — useful because a CI signing identity embeds the ref or workflow, which changes between runs — or build the policy with a provider factory:

Binding the artifact

Pinning the identity proves who signed; it does not prove the attestation is about your artifact. Pass a SubjectPolicy to require the attestation's subject to include a specific digest — then one verify() call enforces both, fail-closed:

Reading SLSA provenance (Statement v1)

For the still-common Statement v0.1, decode the payload directly (json_decode($envelope->payload, true)) — the structure (subject, predicateType, predicate) is identical, only _type differs.

Verifying an artifact (message signature)

For a cosign sign-blob-style bundle, supply the artifact bytes; verifyArtifact() checks the digest, the signature and the Rekor entry, and returns nothing (it throws unless every step passes):

verifyArtifactFromJson() is the JSON-string shorthand. Use Bundle::isDsse() / Bundle::isMessageSignature() to pick the right method for an unknown bundle.

When the artifact bytes are unavailable — too large to load, or already hashed — verify from its digest instead. Sigstore's ECDSA and RSA schemes sign the artifact digest, so the bytes are not needed:

$algorithm (sha256 / sha384 / sha512) must match the one the bundle records. verifyArtifactDigestWithPublicKey() is the public-key counterpart, and both have ...FromJson() shorthands.

Verifying a public-key bundle

A bundle signed with your own key (cosign sign-blob --key / cosign attest --key, or a self-managed-key Sigstore) carries a key reference, not a Fulcio certificate. There is no chain to walk and no identity policy: trust rests on the key you pass in, so supply the public key you already trust. The Rekor transparency-log proof is still verified.

Pass expectedHint: to additionally require the bundle's key hint to match a value you expect. verifyWithPublicKeyFromJson() / verifyArtifactWithPublicKeyFromJson() are the JSON-string shorthands. Use Bundle::hasCertificate() / Bundle::isPublicKey() to pick between the keyless and public-key methods for an unknown bundle.

Scope

This release verifies, offline, both DSSE in-toto attestation bundles and message-signature (artifact) bundles, signed either by a keyless Fulcio certificate or by a public key you supply. The signing key may be ECDSA over NIST P-256/P-384/P-521, RSA (PKCS#1 v1.5), or — for DSSE — Ed25519. It verifies any RFC 3161 timestamp the bundle carries against a trusted Timestamp Authority, and (for keyless bundles) the certificate's embedded SCT against the trusted root's certificate-transparency logs when it provides them. The Rekor transparency-log entry is proven and bound to the bundle for both log generations — v1 (hashedrekord / dsse / intoto) and v2 (hashedrekord 0.0.2, whose checkpoint is Ed25519-signed and whose time comes from an RFC 3161 timestamp). The following are intentionally out of scope and are rejected with UnsupportedBundleException rather than skipped:

• Ed25519 message signatures (cosign signs the digest rather than the artifact, so the scheme is ambiguous), and RSASSA-PSS signatures.

The trusted root can be resolved over TUF — supply it yourself with TrustedRoot::fromJson(), or fetch and refresh it with TrustedRoot::fromTuf() / TrustedRoot::fromSigstorePublicGood() (see The trusted root).

Conformance

The verifier is exercised against the official sigstore-conformance suite on every push and passes it in full, signing as well as verifying — every verification case, across Rekor v1 and v2 transparency-log entries, keyless and public-key bundles, and artifact-bytes and bare-digest inputs, plus the signing cases run keyless against Sigstore staging. See Scope for what is verified versus rejected as unsupported.

The suite is pinned to an exact commit, so a weekly job checks that the pin is still the newest release and that the tag beside it is the one that commit really carries — a claim of "passes in full" is only worth what the newest suite says.

Exceptions

Everything thrown implements K2gl\Sigstore\Exception\SigstoreException:

• VerificationFailedException — a check failed; the bundle is not trustworthy.
• UnsupportedBundleException — a well-formed bundle using a feature this version does not verify.
• InvalidBundleException — the bundle is malformed.
• TrustRootException — the trusted root is malformed or unusable.

License

MIT — see LICENSE. Independent, clean-room implementation of the Sigstore bundle-verification specifications (Apache-2.0).