attestation

type Envelope ¶

type Envelope = cdattestation.Envelope

Envelope is an in-toto attestation envelope (bare statement, DSSE, or Sigstore bundle). Re-exported from the carabiner attestation package as a type alias so callers of this library don't need a separate import for the envelope abstraction.

func Select(envs []Envelope, sel *Selection) (Envelope, error)

type Selection ¶

type Selection struct {
	// Kind names what is being looked for, for messages ("build
	// provenance", "VSA").
	Kind string

	// PredicateTypes are the predicate types the caller verifies. Empty
	// accepts any.
	PredicateTypes []string

	// Subjects, when given, must all be subjects of the attestation.
	Subjects []*subject.Expected

	// NoGitDigestAliases matches subject digests by exact algorithm
	// name; see subject.WithGitDigestAliases.
	NoGitDigestAliases bool

	// Prefer breaks a tie among candidates of different predicate
	// types: the first type listed that any candidate has wins.
	Prefer []string
}

Selection says which of the attestations in a file a verification is about. Files often hold several: a commit's git note accumulates the source provenance, tag provenance and VSAs sourcetool pushes, and a release's attestations file may carry provenance next to other attestations.

type SignatureOptions ¶

type SignatureOptions struct {
	// Keys is the set of public-key providers used to verify DSSE
	// signatures on the envelope. Sigstore bundles verify against an
	// embedded trust root regardless and do not require entries here.
	Keys []key.PublicKeyProvider

	// RekorVerification enables verifying keyless DSSE envelopes — ones
	// carrying a Sigstore certificate on their signatures — against the
	// Rekor transparency log at RekorURL (the signer's default instance
	// when empty). An unreachable log records the envelope as
	// unverifiable rather than failing the call.
	RekorVerification bool

	// RekorURL is the transparency log to query; empty means the
	// signer's default.
	RekorURL string

	// Required, when true, makes VerifySignatures return
	// ErrSignatureRequired if the envelope carries zero signatures,
	// ErrSignatureUnverifiable if it carries signatures the verifier
	// had no material to check, and ErrSignatureUnverified if the
	// signatures were checked and did not verify. Use this to enforce
	// a "must be signed and verified" policy.
	Required bool
}

SignatureOptions parameterizes VerifySignatures. Keys are passed to the envelope's Verify implementation; Required toggles the "unsigned → error" policy independent of any keys.

type Statement ¶

type Statement = cdattestation.Statement

Statement is an in-toto statement (subject + predicate). Re-exported from the carabiner attestation package.

type VSACheck ¶

type VSACheck struct {
	// Name is a human-readable description of what was checked
	// (e.g. `Verifier == "https://verify.example.com"`).
	Name string

	// Pass reports whether the check succeeded.
	Pass bool

	// Message is populated on failure with the observed value
	// (e.g. `verifier.id = "..."`). Empty when Pass is true.
	Message string
}

VSACheck is the result of one hardcoded VSA check.

type VSAOptions ¶

type VSAOptions struct {
	Verifiers    []VerifierBinding
	Signers      []*sapi.Identity
	AllowUnbound bool
	// Registry binds verifier ids to their signers, for accepted
	// verifiers given without one; see verifiers.Registry.
	Registry           *verifiers.Registry
	Subjects           []*subject.Expected
	NoGitDigestAliases bool
	Levels             []string
	Resource           string
	Policy             string
	Dependencies       []string
}

VSAOptions configures the hardcoded checks VerifyVSA runs against an attestation's normalized VSA representation.

Field semantics:

• Verifiers lists the accepted verifiers, OR-matched on ID against VSA.Verifier.ID. At least one is required; a VSA with no asserted verifier identity carries very weak trust value.
• Signers are wildcard identities authorized to sign for every accepted verifier. A verifier's own Signers add to them.
• The signer check binds the matched verifier to who actually signed the envelope: the envelope's verified signature must match one of the identities authorized for that verifier. It runs whenever the matched verifier has any authorized signer.
• Registry supplies the signer of an accepted verifier given without one, when it knows the id, along with the ref policy that signer must satisfy.
• AllowUnbound permits verifiers with no authorized signer at all, in which case only the ID is matched. Off by default, VerifyVSA returns ErrVerifierUnbound instead.
• Subjects are the artifacts the caller holds and expects the VSA to be about. Every one must match a VSA subject (sharing at least one digest algorithm and agreeing on every shared one) or the result fails; each outcome is reported in VSAResult.Subjects. Empty binds the VSA to nothing. By default a sha1 or sha256 digest meets a git object digest of the same hash; NoGitDigestAliases requires the exact algorithm names (see subject.WithGitDigestAliases).
• Levels is OR-matched against VSA.VerifiedLevels — at least one listed level must be satisfied. For canonical SLSA level strings (e.g. SLSA_BUILD_LEVEL_3) the match is "at-or-above": a VSA verifiedLevel of SLSA_BUILD_LEVEL_4 satisfies a want of SLSA_BUILD_LEVEL_3 within the same track. Non-canonical strings only match exactly. Skipped when empty.
• Resource and Policy are exact-match against ResourceURI and Policy.URI respectively. Skipped when empty.
• Dependencies is AND-matched: every key must appear in VSA.DependencyLevels (count values are not consulted). Skipped when empty.

type VSAResult ¶

type VSAResult struct {
	// VSA is the normalized VSA predicate parsed from the envelope.
	// Available to callers that want to display additional fields
	// (e.g. dependency-level counts) alongside the check results.
	VSA *vsa.VSA

	// Checks is the per-check outcome. Always includes the always-on
	// checks (result, verifier); optional checks appear when the
	// corresponding VSAOptions field is non-empty.
	Checks []VSACheck

	// Signers lists the principals of the envelope's verified signers,
	// when the envelope records them, for display alongside the
	// verifier it vouched for. Empty for unsigned or unverified
	// envelopes.
	Signers []string

	// Subjects holds the outcome of binding the VSA to the artifacts
	// the caller holds, one entry per VSAOptions.Subjects entry in
	// order. Empty when none were expected.
	Subjects []subject.Match
}

VSAResult is what VerifyVSA returns. VSA is the normalized version-neutral predicate; Checks is the per-check outcome in display order — exactly the entries needed to render a result table for the user.

func (r *VSAResult) Pass() bool

type Verifier ¶

type Verifier struct{}

Verifier orchestrates attestation verification. Methods on the Verifier split into two groups:

• Generic primitives — Load, VerifySignatures, VerifyIdentity — reusable across every supported attestation type.
• Per-predicate-family checks — VerifyVSA (and, in time, VerifyBuild / VerifySource) — run the semantic checks for that family against an already-loaded, signature-verified envelope.

The zero value is not usable; construct with New.

func New() *Verifier

func (*Verifier) Fetch(ctx context.Context, path string) ([]Envelope, error)

func (v *Verifier) Load(path string) (Envelope, error)

func (*Verifier) VerifyIdentity(env Envelope, expected []*sapi.Identity) error

func (*Verifier) VerifySignatures(env Envelope, opts SignatureOptions) error

func (*Verifier) VerifyVSA(_ context.Context, env Envelope, opts *VSAOptions) (*VSAResult, error)

type VerifierBinding ¶

type VerifierBinding struct {
	// ID is matched exactly against VSA.Verifier.ID.
	ID string

	// Signers are identities allowed to sign VSAs from this verifier,
	// on top of any wildcard signers in VSAOptions.Signers. A verifier
	// with neither is unbound: see VSAOptions.AllowUnbound.
	Signers []*sapi.Identity
}

VerifierBinding names an accepted verifier and the signer identities authorized to issue VSAs on its behalf.