Documentation
¶
Overview ¶
Package trust manages Sigstore trusted root material for offline attestation verification.
Trusted Root Resolution ¶
The trusted root (trusted_root.json) contains Fulcio CA certificates and Rekor public keys needed to verify Sigstore attestation bundles. Resolution follows three layers in priority order:
- Local cache (~/.sigstore/root/) — written by Update(), read by GetTrustedMaterial() with ForceCache. No network access.
- Embedded TUF root — compiled into the binary via sigstore-go's //go:embed directive. Used to bootstrap the TUF update chain when no local cache exists. Updated when the sigstore-go dependency is updated.
- TUF update — Update() contacts the Sigstore TUF CDN (tuf-repo-cdn.sigstore.dev), verifies the update chain cryptographically from the embedded root, and writes the latest trusted_root.json to the local cache.
Verification (GetTrustedMaterial) is always fully offline. Trust material is updated only when the user explicitly runs "aicr trust update".
Key Rotation ¶
Sigstore rotates keys a few times per year. When rotation causes verification to fail (signing certificate chains to a CA not in the local root), the verifier detects this and surfaces an actionable error directing the user to run "aicr trust update".
Index ¶
- func GetSigningConfig() (*root.SigningConfig, error)
- func GetTrustedMaterial() (root.TrustedMaterial, error)
- func LoadTrustedMaterialFromFile(path string) (root.TrustedMaterial, error)
- func ResolveSigningConfig(ctx context.Context) (*root.SigningConfig, error)
- func SigningConfigJSON() ([]byte, error)
- func Update(ctx context.Context) (root.TrustedMaterial, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetSigningConfig ¶ added in v0.17.0
func GetSigningConfig() (*root.SigningConfig, error)
GetSigningConfig returns the Sigstore signing config that targets Rekor v2, read from the local TUF cache (ForceCache, no network). The cache is populated by Update ("aicr trust update"). It is the sign-side counterpart to GetTrustedMaterial: the trusted root answers "is this signature valid?", the signing config answers "which Rekor/TSA endpoints do I sign to?". Both are resolved offline and refreshed only on explicit update.
func GetTrustedMaterial ¶
func GetTrustedMaterial() (root.TrustedMaterial, error)
GetTrustedMaterial returns Sigstore trusted material for offline verification. Uses the sigstore-go TUF client with ForceCache to avoid network calls. Falls back to the embedded TUF root if no cache exists.
func LoadTrustedMaterialFromFile ¶ added in v0.16.0
func LoadTrustedMaterialFromFile(path string) (root.TrustedMaterial, error)
LoadTrustedMaterialFromFile reads a sigstore-go trusted_root.json from a user-supplied path and returns its TrustedMaterial, for verifying bundles signed against a private Fulcio/Rekor (aicr verify --trust-root). The read is bounded by defaults.MaxTrustedRootBytes so an attacker-influenced path cannot OOM the process, and the path must be a regular file so a FIFO or device node cannot block the read indefinitely. A missing/unreadable/non-regular/oversized/ malformed file is a user error (ErrCodeInvalidRequest), unlike the TUF-cache path which is Internal.
func ResolveSigningConfig ¶ added in v0.17.0
func ResolveSigningConfig(ctx context.Context) (*root.SigningConfig, error)
ResolveSigningConfig returns the Rekor v2 signing config, preferring the local TUF cache (offline) and falling back to a bounded network TUF fetch when the cache is cold. Because AICR signs to Rekor v2 by default, signers must succeed without a prior explicit "aicr trust update"; signing is already an online operation, so a one-time fetch of the endpoint config is acceptable and it also warms the cache for next time. Bounded by defaults.TUFUpdateTimeout.
func SigningConfigJSON ¶ added in v0.17.0
SigningConfigJSON returns the raw, TUF-verified bytes of the Rekor v2 signing config from the local cache (ForceCache, no network). Use this to materialize the config to a file for tools that take a signing-config path (e.g. `cosign attest-blob --signing-config`); GetSigningConfig returns the parsed form for in-process signing. The cache is populated by Update.
func Update ¶
func Update(ctx context.Context) (root.TrustedMaterial, error)
Update fetches the latest Sigstore trusted root via TUF CDN and updates the local cache. Bounded by defaults.TUFUpdateTimeout (longer than a single-request HTTPClientTimeout because TUF refreshes download multiple metadata files from a CDN).
Known limitation: the underlying tuf.New / client.Refresh calls do not accept context, so on ctx.Done() we return an error but the goroutine continues running in the background until the network operation completes naturally. This is acceptable for the CLI-only call sites today (the goroutine is reaped on process exit). If callers from a long-running daemon are added, switch to a TUF client that supports context cancellation.
Types ¶
This section is empty.
Source Files