Documentation
¶
Overview ¶
Package sigstore verifies keyless Sigstore (cosign) signatures in process.
A released extension is code flynn is about to execute, so the question "who produced this binary" has to be answered before it runs, from inside the binary that will run it. Shelling out to a cosign executable is not an option: it would make verification depend on a tool most users do not have, and the failure mode of a missing tool is to skip the check, which is precisely backwards.
Keyless means there is no long-lived public key to pin. Instead the release workflow exchanges its OIDC token for a short-lived certificate that Fulcio issues, and the certificate names the workflow. So what gets pinned is an *identity*: this exact workflow, from this exact repository, attested by this exact issuer, under a certificate chaining to Sigstore's root. Forging that means controlling the release workflow itself.
What this verifies:
- the certificate chains to the pinned Fulcio root
- it was issued for the pinned workflow identity (its SAN URI)
- the OIDC issuer is the pinned one, so an identity string minted by some other issuer cannot satisfy the check
- the source repository recorded in the certificate is the pinned one
- the signature verifies over the payload under the certificate's key
What it does not verify: inclusion in the Rekor transparency log, and the embedded SCT. Those prove a certificate was publicly logged. They are a defence against a compromised or coerced Fulcio issuing a certificate nobody can see, and they are worth adding. They are not what stands between an attacker and this check today: to obtain a certificate that satisfies the identity, issuer and repository pins above, an attacker must already be able to make Fulcio believe they are our release workflow, which means holding our workflow's OIDC token. At that point they can publish a genuinely logged release too. The pin is deliberately stated in terms of what it proves, not what it feels like.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Verify ¶
Verify checks a detached keyless signature over payload and reports whether it was made by the pinned identity. It returns nil only when every pin holds.
sig is the base64 signature and certPEM the certificate, exactly as cosign writes them beside the artifact (`--output-signature`, `--output-certificate`).
Types ¶
type Identity ¶
type Identity struct {
// Workflow is the certificate's SAN URI: the workflow that requested the signature.
// For a release built by a reusable workflow this is the *reusable* workflow's ref,
// not the caller's, because that is what Sigstore binds the signature to.
Workflow string
// Issuer is the OIDC issuer that authenticated the workflow.
Issuer string
// SourceRepo is the "owner/name" the workflow ran for.
SourceRepo string
}
Identity is what a signature must prove about its origin before the artifact it covers is trusted. Every field is required: a zero-valued Identity verifies nothing, so a caller cannot accidentally accept any signature by forgetting to pin.
type Verifier ¶
type Verifier struct {
// Roots is a PEM bundle to trust instead of the embedded Fulcio chain.
Roots []byte
}
Verifier is Verify with the trust anchor made explicit. The zero value uses the embedded Fulcio roots, which is what production always wants; a caller supplies its own only to verify against a different Sigstore instance.
Source Files