Documentation
¶
Overview ¶
Package builders holds the registry of build platforms the verifier can bind to their signing identity: for each known builder, who must have signed the provenance for its builder.id to count as proven rather than merely claimed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Builder ¶
type Builder struct {
// ID is the builder id as provenance records it in builder.id, without
// the @ref the GitHub builders append.
ID string `yaml:"id"`
// IDMatch is how ID is compared with builder.id; exact by default.
IDMatch IDMatch `yaml:"idMatch,omitempty"`
// Title names the builder for people.
Title string `yaml:"title,omitempty"`
// Description explains what the builder is and how it is bound.
Description string `yaml:"description,omitempty"`
// Issuer is the OIDC issuer of the builder's signing certificate. With
// Signer unset, the signer identity is derived from it and ID: a
// sigstore identity from Issuer whose subject starts with ID (the
// builder's ref follows it after an @).
Issuer string `yaml:"issuer,omitempty"`
// Signer is the identity spec (see sapi.NewIdentityFromSpec) the
// provenance must be signed by, when it cannot be derived from
// Issuer and ID.
Signer string `yaml:"signer,omitempty"`
// Ref constrains the ref carried by the signer identity; any by
// default.
Ref RefPolicy `yaml:"ref,omitempty"`
// Delegated marks a builder that runs other builders: its certificate
// proves the delegator ran, while builder.id names the delegated
// builder, which is not expected to equal the signer identity.
Delegated bool `yaml:"delegated,omitempty"`
// Observer marks a watcher that attests runs it observed: its
// certificate proves the observer ran, and builder.id must name the
// workflow the certificate's build config URI says the observer ran
// for, which proves that workflow really ran.
Observer bool `yaml:"observer,omitempty"`
// SourceRepositoryBound asserts the signing certificate's source
// repository is the repository the artifact was built from, so it
// can be compared with the expected source.
SourceRepositoryBound bool `yaml:"sourceRepositoryBound,omitempty"`
// contains filtered or unexported fields
}
Builder describes a build platform and the identity that signs the provenance it produces.
func ParseBinding ¶
ParseBinding parses a builder given on the command line as "id=signer-spec" or "id=issuer": the value is an identity spec when it has a spec's shape (type(...)::..., spiffe://..., ref:...) and an OIDC issuer otherwise. The binding is exact on id, accepts any ref and, having no way to know, does not bind the source repository.
func (*Builder) MatchesID ¶
MatchesID reports whether builderID (its @ref ignored) names this builder.
func (*Builder) MatchesSigner ¶
MatchesSigner reports whether signer, an identity recorded on a verified signature, is this builder's signer.
func (*Builder) SignerSpec ¶
SignerSpec returns the identity spec the builder's provenance must be signed by: Signer when set, else one derived from Issuer and ID.
type IDMatch ¶
type IDMatch string
IDMatch says how a registry entry's id is compared with a provenance's builder.id (with its @ref removed).
const ( // IDMatchExact requires builder.id to be the entry's id. IDMatchExact IDMatch = "exact" // IDMatchPrefix accepts any builder.id starting with the entry's id, // for platforms where the builder is the workflow that ran and its // identity is what the certificate names. IDMatchPrefix IDMatch = "prefix" )
type RefPolicy ¶
type RefPolicy string
RefPolicy constrains the ref a signer identity carries after its @ (https://github.com/org/repo/.github/workflows/build.yml@refs/tags/v1.2.3).
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is an ordered set of builders. Exact-id entries take precedence over prefix entries in lookups, so a specific builder can be described alongside the platform pattern that would also match it.
func LoadEmbedded ¶
LoadEmbedded loads the builders compiled into the binary.
func New ¶
New returns a registry holding the given builders, validated. A later entry with the same id and idMatch replaces an earlier one, so user-supplied entries override the embedded ones.
func (*Registry) Add ¶
Add validates b and adds it to the registry, replacing an entry with the same id and idMatch.
func (*Registry) ForSigner ¶
ForSigner returns the builder whose signer identity signer is, or nil when no known builder signs with it.