Documentation
¶
Overview ¶
Package verifier verifies Sigstore signatures and attestations on OCI artifacts.
Two entry points cover the two trust flows:
- New builds a Sigstore verifier with a live TUF-refreshed trust root for verifying MCP server images against registry-declared provenance (Sigstore.VerifyServer).
- RetrieveBundles, VerifyBundle, VerifyBundleWithKey, and VerifyBundleOffline expose the bundle-level building blocks for consumers that manage their own trust decisions — retrieving the bundles attached to an artifact, verifying them against keyless (Fulcio) or key-pair material, binding an expected Identity into the verification policy, and re-verifying stored bundles offline against the embedded trust root.
Verifying a retrieved bundle ¶
bundles, err := verifier.RetrieveBundles(ctx, imageRef, keychain) // handle err; errors.Is(err, verifier.ErrNoBundles) means unsigned tm, _ := verifier.OfflineTrustedMaterial() opts, _ := verifier.DefaultVerifierOptions() result, err := verifier.VerifyBundle(bundles[0], tm, nil, opts...) // errors.Is(err, verifier.ErrVerificationFailed) means signed but invalid identity, _ := verifier.IdentityFromResult(result) // store bundles[0].Raw and identity; later: _, err = verifier.VerifyBundleOffline(storedRaw, "sha256:"+digestHex, &identity)
Key-signed bundles (Bundle.HasCertificate() == false, the "cosign sign --key" layout) carry no certificate identity; verify them with VerifyBundleWithKey at retrieval time and VerifyBundleOfflineWithKey for stored Raw bytes — both take the signer's PEM public key.
Stability ¶
This package is Alpha stability. The API may change without notice.
Package verifier provides a client for verifying artifacts using sigstore
Index ¶
- Constants
- Variables
- func DefaultVerifierOptions() ([]verify.VerifierOption, error)
- func OfflineTrustedMaterial() (root.TrustedMaterial, error)
- func PublicKeyMaterial(pubKeyPEM []byte) (root.TrustedMaterial, error)
- func VerifyBundle(b Bundle, tm root.TrustedMaterial, expected *Identity, ...) (*verify.VerificationResult, error)
- func VerifyBundleOffline(rawBundle []byte, artifactDigest string, expected *Identity) (*verify.VerificationResult, error)
- func VerifyBundleOfflineWithKey(rawBundle []byte, artifactDigest string, pubKeyPEM []byte) (*verify.VerificationResult, error)
- func VerifyBundleWithKey(b Bundle, pubKeyPEM []byte) (*verify.VerificationResult, error)
- type Bundle
- type Identity
- type Result
- type Sigstore
Constants ¶
const ( MediaTypeOCIEmptyV1JSON = "application/vnd.oci.empty.v1+json" MediaTypeCosignSimpleSigningV1JSON = "application/vnd.dev.cosign.simplesigning.v1+json" MediaTypeSigstoreBundleV03JSON = "application/vnd.dev.sigstore.bundle.v0.3+json" )
OCI and Sigstore media type constants used when inspecting referrer manifests.
const ( // TrustedRootSigstoreGitHub is the GitHub trusted root repository for sigstore (used for private repos, Enterprise) TrustedRootSigstoreGitHub = "tuf-repo.github.com" // TrustedRootSigstorePublicGoodInstance is the public trusted root repository for sigstore TrustedRootSigstorePublicGoodInstance = "tuf-repo-cdn.sigstore.dev" )
const DigestAlgorithmSHA256 = "sha256"
DigestAlgorithmSHA256 is the digest algorithm name used throughout the Sigstore bundle formats this package handles.
Variables ¶
var ( // ErrProvenanceNotFoundOrIncomplete is returned when there's no provenance info (missing .sig or attestation) or // has incomplete data ErrProvenanceNotFoundOrIncomplete = errors.New("provenance not found or incomplete") // ErrProvenanceServerInformationNotSet is returned when the provenance information for a server is not set ErrProvenanceServerInformationNotSet = errors.New("provenance server information not set") // ErrImageNotSigned is returned when no signatures or attestations are found for the image ErrImageNotSigned = errors.New("image is not signed") // ErrProvenanceMismatch is returned when the image is signed but no bundle matches the expected provenance ErrProvenanceMismatch = errors.New("image provenance does not match") // MaxAttestationsBytesLimit is the maximum number of bytes we're willing to read from the attestation endpoint // We'll limit this to 10mb for now MaxAttestationsBytesLimit int64 = 10 * 1024 * 1024 )
var ErrNoBundles = errors.New("no sigstore bundles found for artifact")
ErrNoBundles is returned by RetrieveBundles when the artifact carries no Sigstore signature or attestation in any supported layout — keyless (certificate-bearing), key-signed ("cosign sign --key"), or attestation — i.e. the artifact is unsigned as far as this package can tell.
var ErrVerificationFailed = errors.New("sigstore bundle verification failed")
ErrVerificationFailed wraps every cryptographic verification failure returned by the VerifyBundle* functions, so callers can distinguish "signed but failed verification" from malformed input with errors.Is instead of matching sigstore-go's (unstable) error strings.
Functions ¶
func DefaultVerifierOptions ¶ added in v0.0.35
func DefaultVerifierOptions() ([]verify.VerifierOption, error)
DefaultVerifierOptions returns the verifier options matching the Sigstore public-good instance trust root (SCT, transparency log, and observer timestamp requirements). Pass these to VerifyBundle together with OfflineTrustedMaterial (or the live public-good root).
func OfflineTrustedMaterial ¶ added in v0.0.35
func OfflineTrustedMaterial() (root.TrustedMaterial, error)
OfflineTrustedMaterial returns trusted material for the Sigstore public-good instance built entirely from the trusted root embedded in this package — no network access, no TUF refresh. The embedded root is a point-in-time snapshot: key rotations in the public-good instance require a package update to pick up. This cuts both ways — newly rotated-in keys are unknown (verification of fresh signatures fails until the snapshot is updated), and a key rotated out BECAUSE OF COMPROMISE keeps being trusted here until a new release ships and consumers bump. Callers that need live freshness or timely compromise revocation should use New (which performs a TUF fetch) instead; offline verification trades that for hermeticity. See tufroots/README.md for the snapshot's provenance.
func PublicKeyMaterial ¶ added in v0.0.35
func PublicKeyMaterial(pubKeyPEM []byte) (root.TrustedMaterial, error)
PublicKeyMaterial returns trusted material that verifies bundles signed with the private counterpart of the given PEM-encoded public key (the cosign key-pair flow, as opposed to keyless/Fulcio). The key is trusted without validity-period bounds: key-signed bundles carry no certificate whose lifetime could scope it.
func VerifyBundle ¶ added in v0.0.35
func VerifyBundle( b Bundle, tm root.TrustedMaterial, expected *Identity, verifierOpts ...verify.VerifierOption, ) (*verify.VerificationResult, error)
VerifyBundle verifies a retrieved bundle against the given trusted material. When expected is non-nil, the identity is bound into the Sigstore verification policy itself (certificate SAN and issuer must match) rather than compared after the fact; a nil expected — the trust-on-first-use case — verifies the chain of trust only, and the caller records the identity from the returned result.
verifierOpts configure the verifier and MUST match the trusted material: pass DefaultVerifierOptions() with public-good material (SCT + transparency log + observer timestamps), and verify.WithNoObserverTimestamps() with PublicKeyMaterial (key-signed bundles carry no certificate transparency or Fulcio timestamps). Requiring the options explicitly prevents public-good defaults being fed to a different root, which surfaces as confusing sigstore-go internals rather than a clear mismatch.
func VerifyBundleOffline ¶ added in v0.0.35
func VerifyBundleOffline( rawBundle []byte, artifactDigest string, expected *Identity, ) (*verify.VerificationResult, error)
VerifyBundleOffline re-verifies a stored bundle (the Raw form produced by RetrieveBundles or a signing flow) against the artifact digest ("sha256:<hex>"), using only the embedded trusted root — no network. See OfflineTrustedMaterial for the freshness trade-off. expected behaves as in VerifyBundle.
func VerifyBundleOfflineWithKey ¶ added in v0.0.35
func VerifyBundleOfflineWithKey( rawBundle []byte, artifactDigest string, pubKeyPEM []byte, ) (*verify.VerificationResult, error)
VerifyBundleOfflineWithKey re-verifies a stored key-signed bundle (the Raw form of a bundle whose HasCertificate is false) against the artifact digest ("sha256:<hex>") and the given PEM public key. Key verification needs no trust root or network in the first place; this entry point only adds the parse step for stored bundles.
func VerifyBundleWithKey ¶ added in v0.0.35
func VerifyBundleWithKey(b Bundle, pubKeyPEM []byte) (*verify.VerificationResult, error)
VerifyBundleWithKey verifies a bundle signed with a plain key pair (the cosign --key flow) against the given PEM public key. Key-signed bundles carry no certificate, so there is no identity to bind — trust is the key itself — and no transparency-log or timestamp material to require.
Types ¶
type Bundle ¶ added in v0.0.35
type Bundle struct {
// Parsed is the decoded bundle.
Parsed *bundle.Bundle
// Raw is the bundle's canonical JSON serialization.
Raw []byte
// DigestAlgo is the algorithm of the artifact digest the bundle signs
// (e.g. "sha256").
DigestAlgo string
// DigestHex is the hex-encoded artifact digest the bundle signs.
DigestHex string
}
Bundle is a Sigstore bundle retrieved for an artifact, in both parsed and serialized form. Raw is the canonical JSON encoding, suitable for durable storage and later re-verification — with VerifyBundleOffline for keyless (certificate-bearing) bundles, or VerifyBundleOfflineWithKey for bundles reconstructed from the key-signed cosign layout (HasCertificate tells the two apart; key-signed bundles carry a "cosign-keypair" public-key hint instead of a certificate).
func RetrieveBundles ¶ added in v0.0.35
func RetrieveBundles(ctx context.Context, imageRef string, keychain authn.Keychain) ([]Bundle, error)
RetrieveBundles fetches the Sigstore bundles attached to imageRef, trying both layouts this package understands: a cosign-style signature manifest (the "sha256-<hex>.sig" tag) and attestation manifests. It returns ErrNoBundles when the artifact has no discoverable signature material — the caller's signal that the artifact is unsigned.
func (Bundle) HasCertificate ¶ added in v0.0.35
HasCertificate reports whether the bundle carries a signing certificate — i.e. it came from a keyless (Fulcio) flow and verifies with VerifyBundle; a false result is the key-signed layout, verifying with VerifyBundleWithKey / VerifyBundleOfflineWithKey.
type Identity ¶ added in v0.0.35
type Identity struct {
// SignerIdentity is the certificate's subject identity. For
// certificates issued through GitHub Actions tokens this is the
// workflow path relative to the repository (see
// signerIdentityFromCertificate); otherwise it is the certificate SAN
// verbatim (a URI, email, or SPIFFE ID).
SignerIdentity string
// CertIssuer is the OIDC issuer that authenticated the signer.
CertIssuer string
// SourceRepositoryURI is the source repository recorded in the Fulcio
// certificate extensions, when present.
SourceRepositoryURI string
}
Identity is the signer identity extracted from a verified Sigstore bundle.
func IdentityFromResult ¶ added in v0.0.35
func IdentityFromResult(r *verify.VerificationResult) (Identity, error)
IdentityFromResult extracts the signer Identity from a verification result.
type Result ¶
type Result struct {
IsSigned bool `json:"is_signed"`
IsVerified bool `json:"is_verified"`
verify.VerificationResult
}
Result is the result of the verification
type Sigstore ¶
type Sigstore struct {
// contains filtered or unexported fields
}
Sigstore is the sigstore verifier
func (*Sigstore) GetVerificationResults ¶
func (s *Sigstore) GetVerificationResults( imageRef string, ) ([]*verify.VerificationResult, error)
GetVerificationResults returns the verification results for the given image reference
func (*Sigstore) VerifyServer ¶
func (s *Sigstore) VerifyServer(imageRef string, provenance *registry.Provenance) error
VerifyServer verifies the server information for the given image reference
Source Files