options

package
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 7, 2026 License: Apache-2.0 Imports: 15 Imported by: 3

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultSign = Sign{
	PayloadType: "application/octet-stream",
}
View Source 
var DefaultSigner = Signer{
	SigstoreRootsData: sigstore.DefaultRoots,
}
View Source 
var DefaultSigstore = Sigstore{
	Instance: sigstore.Instance{
		Timestamp:     true,
		AppendToRekor: true,

		TufOptions: tuf.TufOptions{
			TufRootURL: "https://tuf-repo-cdn.sigstore.dev",
		},

		HideOIDCOptions: true,

		OIDCConfig: sigstore.OIDCConfig{
			RedirectURL: "http://localhost:0/auth/callback",
			ClientID:    "sigstore",
		},

		VerifierConfig: sigstore.VerifierConfig{
			RequireCTlog:             true,
			RequireTlog:              true,
			RequireObserverTimestamp: true,
		},
	},
}
View Source 
var DefaultVerification = Verification{}
View Source 
var DefaultVerifier = Verifier{
	Verification:      DefaultVerification,
	SigstoreRootsData: sigstore.DefaultRoots,
}

DefaultVerifier default options to configure the verifier

Functions

This section is empty.

Types

type Backend added in v0.5.0 

type Backend string

Backend selects which signing backend the Signer uses. Three independent implementations:

  • BackendSigstore: a Fulcio-issued cert + DSSE + optional Rekor/TSA, produced as a sigstore bundle. signingState auto-builds a sigstore.CredentialProvider from this Options struct on first use when Signer.Credentials is nil.
  • BackendSpiffe: an X.509-SVID + DSSE produced as a sigstore bundle, including the SPIRE upstream intermediates. Requires Signer.Credentials to be pre-populated with a *spiffe.CredentialProvider — signingState cannot build SPIFFE credentials from Options alone.
  • BackendKey: raw private-key signing producing a bare DSSE envelope (no cert chain, no Rekor, no TSA). Uses Signer.Options.Keys.

At the polymorphic layer (Signer.SignStatement / Signer.SignMessage), Sigstore and Spiffe both yield *BundleArtifact; Key yields *EnvelopeArtifact.

Specialized methods on Signer behave as follows w.r.t. this field:

  • SignStatementBundle / SignMessageBundle work for either bundle backend (Sigstore or Spiffe) — they read Backend via signingState to know which CredentialProvider to use, and error if Backend is Key.
  • SignStatementToDSSE / SignMessageToDSSE work regardless of Backend; they only need keys (via per-call options.WithKey or Signer.Options.Keys).
const (
	// BackendSigstore signs through Fulcio + sigstore-go.
	// Default when Backend is left unset.
	BackendSigstore Backend = "sigstore"

	// BackendKey signs against raw private keys held in Signer.Keys,
	// producing a bare DSSE envelope.
	BackendKey Backend = "key"

	// BackendSpiffe signs with an X.509-SVID from the SPIFFE Workload
	// API. The signer.Signer's Credentials must be set to a
	// *spiffe.CredentialProvider — the runtime cannot yet build SPIFFE
	// credentials from Options alone.
	BackendSpiffe Backend = "spiffe"
)

type BundleVerifier added in v0.3.0 

type BundleVerifier struct {
	// RootsFile path to roots file
	RootsFile string
}

type KeyVerification added in v0.3.0 

type KeyVerification struct {
	// PubKeys are the public-key providers used as a fallback when the
	// per-call keys argument to VerifyParsedDSSE is empty. Lets a CLI
	// wire its --key flag into the verifier once and call VerifyDSSE
	// without re-passing the keys.
	PubKeys []key.PublicKeyProvider
}

KeyVerification options

type KeysSign added in v0.5.0 

type KeysSign struct {
	// PrivateKeyPaths are filesystem paths to private signing keys.
	// Bound to --signing-key (repeatable).
	PrivateKeyPaths []string

	// PassphraseEnvVar names an environment variable whose value (when
	// set and non-empty) is used to decrypt encrypted signing keys
	// (currently only encrypted GPG private keys). Bound to
	// --signing-key-passphrase-env.
	PassphraseEnvVar string
	// contains filtered or unexported fields
}

KeysSign is a command.OptionsSet for sign-side private-key configuration. It is the sister of upstream carabiner-dev/command/keys.Options (which handles verify-side public keys): both let CLI tools wire flag-driven key-file paths into their command surface.

When the resolved Signer.Options.Backend is BackendKey, the keys produced by KeysSign.ParseSigningKeys feed into Signer.Options.Keys, at which point Signer.SignStatement / SignMessage produce DSSE envelopes via the key backend.

func DefaultKeysSign added in v0.5.0 

func DefaultKeysSign() *KeysSign

DefaultKeysSign returns a KeysSign ready to bind flags. The passphrase env-var name defaults to SIGNING_KEY_PASSPHRASE; users who export that variable get encrypted-key support out of the box, users who don't see no behavior change.

func (*KeysSign) AddFlags added in v0.5.0 

func (k *KeysSign) AddFlags(cmd *cobra.Command)

AddFlags registers the KeysSign flags on cmd.

func (*KeysSign) AddKeys added in v0.5.0 

func (k *KeysSign) AddKeys(providers ...key.PrivateKeyProvider)

AddKeys appends pre-parsed providers. They are returned by ParseSigningKeys ahead of any keys loaded from PrivateKeyPaths. Useful for tests and for callers that already hold the key material and want to feed it to the same plumbing as the file-based keys.

func (*KeysSign) BuildSigner added in v0.5.0 

func (k *KeysSign) BuildSigner() (*Signer, error)

BuildSigner returns a *Signer wired for the key backend: Backend set to BackendKey and Keys populated from ParseSigningKeys. Errors when no keys are configured (a key-backend signer with no keys can't sign).

func (*KeysSign) Config added in v0.5.0 

func (k *KeysSign) Config() *command.OptionsSetConfig

Config returns the flag configuration for KeysSign.

func (*KeysSign) ParseSigningKeys added in v0.5.0 

func (k *KeysSign) ParseSigningKeys() ([]key.PrivateKeyProvider, error)

ParseSigningKeys reads and parses every entry in PrivateKeyPaths and returns the resulting providers prepended with AddKeys-supplied extras. Encrypted GPG keys are decrypted using the passphrase read from PassphraseEnvVar when set.

func (*KeysSign) Validate added in v0.5.0 

func (k *KeysSign) Validate() error

Validate checks that every configured signing-key path exists. It does not parse the key material — that happens lazily in ParseSigningKeys so flag-time errors stay cheap and parsing errors surface with file context at use time.

type KeysVerify added in v0.5.0 

type KeysVerify struct {
	*keys.Options
}

KeysVerify is a command.OptionsSet for verify-side public-key configuration. It composes the upstream github.com/carabiner-dev/command/keys.Options (which supplies the --key flag, repeatable, plus AddKeys and ParseKeys) with this package's verifier-side ApplyToVerifier / BuildVerifier so the set fits the same shape as SigstoreVerifySet and SpiffeVerifySet.

Composition over duplication: the upstream package owns --key, we own the wiring into options.Verifier so the keys flow into Verification.PubKeys and VerifyParsedDSSE picks them up via the fallback added when the per-call keys argument is empty.

func DefaultKeysVerify added in v0.5.0 

func DefaultKeysVerify() *KeysVerify

DefaultKeysVerify constructs a KeysVerify wrapping a fresh upstream keys.Options ready to bind flags.

func (*KeysVerify) Active added in v0.5.0 

func (k *KeysVerify) Active() bool

Active reports whether the user has configured this set with any public keys via the --key flag. Active=false means the bundled VerifierSet skips this child during Validate / ApplyToVerifier so a CLI verifying a sigstore- or SPIFFE-only bundle isn't forced to pass --key.

Programmatically-added keys (via the embedded keys.Options.AddKeys) are not visible here because the upstream extraKeys field is unexported. Callers who only use AddKeys should construct the verifier directly via BuildVerifier rather than relying on the bundled VerifierSet's active-child filtering.

func (*KeysVerify) ApplyToVerifier added in v0.5.0 

func (k *KeysVerify) ApplyToVerifier(target *Verifier) error

ApplyToVerifier parses every configured public-key file (and any programmatic providers added via AddKeys on the embedded Options) and stores them on target.Verification.PubKeys. VerifyParsedDSSE reads PubKeys as a fallback when its keys argument is empty, so a CLI can wire --key once and call VerifyDSSE without re-passing.

func (*KeysVerify) BuildVerifier added in v0.5.0 

func (k *KeysVerify) BuildVerifier() (*Verifier, error)

BuildVerifier returns a *Verifier populated from the resolved public-key configuration. Empty key configuration is allowed and yields a Verifier whose PubKeys slice is empty — callers that require keys must check before calling VerifyDSSE.

type Sign 

type Sign struct {
	// PayloadType is the payload type to be declared in DSSE envelopes
	PayloadType string

	// PrivateKeys for DSSE envelope signing. These will be honored later
	// to reuse in bundle signing
	Keys []key.PrivateKeyProvider
}

Sign options (not to be confused with signer options) are options that control each signing operation behavior.

type SignOptFn 

type SignOptFn = func(*Sign) error

func WithKey added in v0.2.0 

func WithKey(keys ...key.PrivateKeyProvider) SignOptFn

WithKey adds one or more key providers that will be used to sign

func WithPayloadType 

func WithPayloadType(t string) SignOptFn

WithPayloadType sets the DSSE payload type

type Signer 

type Signer struct {
	Sigstore
	Token             *oauthflow.OIDCIDToken
	SigstoreRootsData []byte

	// Backend selects which signing path the polymorphic Sign methods
	// take. Empty defaults to BackendBundle.
	Backend Backend

	// Keys are the private keys the key backend will sign with. Only
	// consulted when Backend == BackendKey AND no per-call
	// options.WithKey(...) is supplied. Per-call WithKey replaces (does
	// not augment) these keys for the single invocation that passes it.
	Keys []key.PrivateKeyProvider
	// contains filtered or unexported fields
}

Signer is the stateful sign-side configuration for the top-level signer.Signer. It selects the backend and carries the material that backend needs.

func (*Signer) BuildSigstoreCredentials added in v0.5.0 

func (so *Signer) BuildSigstoreCredentials() *sigstore.CredentialProvider

BuildSigstoreCredentials constructs a sigstore.CredentialProvider from the options, forwarding the DisableSTS flag and any pre-provided OIDC token. Used by the outer Signer to default-construct a provider when none was injected.

func (*Signer) ParseRoots added in v0.3.2 

func (so *Signer) ParseRoots() error

ParseRoots parses the root information and assigns the instance data in the sigstore options

func (*Signer) Validate 

func (so *Signer) Validate() error

Validate checks the signer options

type SignerSet added in v0.5.0 

type SignerSet struct {
	// Backend selects which child set Validate/BuildSigner consult.
	// Bound to --signing-backend. Empty resolves to BackendSigstore, matching
	// the runtime signer's default.
	Backend string

	// Timestamp controls whether the resulting bundle carries an RFC
	// 3161 timestamp. Bound to --signing-timestamp; the flag is the
	// single user-facing knob across backends so each per-backend
	// child has its own --<prefix>-timestamp suppressed (via
	// ManagedTimestamp on the child) when bundled here. BuildSigner
	// propagates this value into the dispatched child's
	// *options.Signer.Timestamp, overriding any per-backend default.
	// Applies to sigstore and SPIFFE (whose BuildSigner attaches a
	// TSA-only SigningConfig); the key backend ignores it because
	// DSSE envelopes carry no timestamps.
	Timestamp bool

	Keys     *KeysSign
	Sigstore *SigstoreSignSet
	Spiffe   *SpiffeSignSet
	// contains filtered or unexported fields
}

SignerSet is the top-level sign-side OptionsSet that bundles every backend-specific child set behind a single --signing-backend discriminator flag. AddFlags registers --signing-backend plus every child's flags so the CLI's --help shows the full surface; Validate and BuildSigner act only on the child selected by --signing-backend, so non-selected children are inert.

Typical use: 

set := DefaultSignerSet()
set.AddFlags(cmd)
// ... after cobra parses ...
if err := set.Validate(); err != nil { ... }
opts, err := set.BuildSigner()
creds, err := set.BuildCredentialProvider()
runtime := signer.NewSigner()
runtime.Options = *opts
if creds != nil {
    runtime.Credentials = creds
}

SPIFFE is the only backend that needs a separate credential provider; for sigstore and key BuildCredentialProvider returns (nil, nil) and the runtime signer's auto-build / unused-credentials behavior takes over.

func DefaultSignerSet added in v0.5.0 

func DefaultSignerSet() *SignerSet

DefaultSignerSet builds a SignerSet with every child constructed under its conventional flag prefix ("sigstore", "spiffe"; KeysSign uses its own --signing-key namespace). Backend is left empty so resolveBackend can auto-detect from the populated child flags; users who want a specific backend can override --signing-backend.

func (*SignerSet) AddFlags added in v0.5.0 

func (s *SignerSet) AddFlags(cmd *cobra.Command)

AddFlags registers --signing-backend and every non-nil child's flags. Order is fixed (signing-backend → keys → sigstore → spiffe) so --help output is stable across runs.

func (*SignerSet) BuildCredentialProvider added in v0.5.0 

func (s *SignerSet) BuildCredentialProvider() (*spiffe.CredentialProvider, error)

BuildCredentialProvider returns the *spiffe.CredentialProvider needed to arm signer.Signer.Credentials for the SPIFFE backend. Returns (nil, nil) for backends that don't need an externally- supplied provider — sigstore lazy-builds from Options on first signing call; key has no credentials concept.

func (*SignerSet) BuildSigner added in v0.5.0 

func (s *SignerSet) BuildSigner() (*Signer, error)

BuildSigner dispatches on --signing-backend and returns the populated *Signer for that backend. SPIFFE callers must additionally call BuildCredentialProvider and assign the result to signer.Signer.Credentials before any Sign* call.

func (*SignerSet) Config added in v0.5.0 

func (s *SignerSet) Config() *command.OptionsSetConfig

Config returns the flag config for the --signing-backend flag itself. Children expose their own Config() and remain the authoritative source for their flag namespaces.

func (*SignerSet) Validate added in v0.5.0 

func (s *SignerSet) Validate() error

Validate checks --signing-backend is recognized and validates the selected child only. Non-selected children are not consulted, so their flags can be left unset without failing validation. Nil-safe.

type Sigstore added in v0.3.0 

type Sigstore struct {
	sigstore.Instance
}

Sigstore options to control how signer handles signing with sigstore

func (*Sigstore) AddFlags added in v0.3.0 

func (s *Sigstore) AddFlags(cmd *cobra.Command)

AddFlags adds flags to a spf13/cobra command exposing the sigstore signing options. Not all options are yet exposed as CLI flags.

func (*Sigstore) Validate added in v0.3.1 

func (s *Sigstore) Validate() error

Validate checks the integrity of the sigstore options

func (*Sigstore) ValidateOIDC added in v0.3.1 

func (s *Sigstore) ValidateOIDC() error

Ensure the options have the required OIDC fields

func (*Sigstore) ValidateSigner added in v0.3.1 

func (s *Sigstore) ValidateSigner() error

ValidateSigner check the options required to sign

func (*Sigstore) ValidateTimestamps added in v0.3.1 

func (s *Sigstore) ValidateTimestamps() error

ValidateTimestamps

func (*Sigstore) ValidateVerifier added in v0.3.1 

func (s *Sigstore) ValidateVerifier() error

type SigstoreCommon added in v0.5.0 

type SigstoreCommon struct {
	// RootsPath is the filesystem path to a sigstore-roots.json file.
	// Empty means use RootsData if set, otherwise sigstore.DefaultRoots.
	RootsPath string

	// RootsData is the raw JSON of a sigstore-roots file when callers
	// want to inject it programmatically. Empty falls back to RootsPath
	// (then to sigstore.DefaultRoots).
	RootsData []byte
	// contains filtered or unexported fields
}

SigstoreCommon holds the flag-bound sigstore roots configuration shared between SigstoreSign and SigstoreVerify. Tools that expose both operations should construct one *SigstoreCommon, share it via pointer in their SigstoreSign and SigstoreVerify, and call SigstoreCommon.AddFlags(cmd) once so --sigstore-roots is registered exactly once.

func DefaultSigstoreCommon added in v0.5.0 

func DefaultSigstoreCommon() *SigstoreCommon

DefaultSigstoreCommon returns a SigstoreCommon configured to use the embedded sigstore.DefaultRoots until the caller overrides it.

func (*SigstoreCommon) AddFlags added in v0.5.0 

func (c *SigstoreCommon) AddFlags(cmd *cobra.Command)

AddFlags registers the SigstoreCommon flags on cmd.

func (*SigstoreCommon) Config added in v0.5.0 

func (c *SigstoreCommon) Config() *command.OptionsSetConfig

Config returns the flag configuration for SigstoreCommon.

func (*SigstoreCommon) Instance added in v0.5.0 

func (c *SigstoreCommon) Instance(name string) (*sigstore.InstanceConfig, error)

Instance returns the InstanceConfig whose ID matches name. When name is empty, returns the first instance in file order (Roots[0]).

func (*SigstoreCommon) Instances added in v0.5.0 

func (c *SigstoreCommon) Instances() []sigstore.InstanceConfig

Instances returns every parsed instance configuration, in file order. Returns nil if LoadRoots failed.

func (*SigstoreCommon) LoadRoots added in v0.5.0 

func (c *SigstoreCommon) LoadRoots() error

LoadRoots reads and parses the roots data into a SigstoreRoots struct. Subsequent calls are no-ops. Resolution order:

  1. RootsPath (file)
  2. RootsData (inline JSON)
  3. sigstore.DefaultRoots (embedded)

func (*SigstoreCommon) Validate added in v0.5.0 

func (c *SigstoreCommon) Validate() error

Validate parses the roots data (if not already parsed) and confirms at least one instance is defined.

type SigstoreSign added in v0.5.0 

type SigstoreSign struct {
	*SigstoreCommon

	// InstanceName selects which instance from the roots file to sign
	// against. Empty resolves to Roots[0].
	InstanceName string

	// OIDC overrides — applied on top of the selected instance's
	// OIDCConfig at ResolveInstance time. Empty fields leave the roots
	// file's value in place.
	OIDCClientID     string
	OIDCRedirectURL  string
	OIDCClientSecret string

	// OIDCTokenFile is an optional path to a pre-issued OIDC ID token,
	// for non-interactive (CI) flows. Read at ResolveInstance time.
	OIDCTokenFile string

	// Sign-time toggles.
	RekorAppend bool
	Timestamp   bool
	DisableSTS  bool

	// HideOIDCOptions marks the --oidc-* flags as hidden on the CLI.
	HideOIDCOptions bool

	// ManagedTimestamp, when true, suppresses registration of the
	// --<prefix>-timestamp flag in AddFlags. Set by SignerSet so the
	// bundled --signing-timestamp can be the single user-facing knob;
	// standalone callers leave this false (default) and get
	// --sigstore-timestamp under the standard prefix.
	ManagedTimestamp bool
	// contains filtered or unexported fields
}

SigstoreSign is the OptionsSet for the signing side of a sigstore workflow. It pinpoints a specific instance from SigstoreCommon, holds the client-side OIDC overrides, and the sign-time toggles.

func DefaultSigstoreSign added in v0.5.0 

func DefaultSigstoreSign(common *SigstoreCommon) *SigstoreSign

DefaultSigstoreSign builds a SigstoreSign with sensible defaults (OIDC ClientID "sigstore", localhost callback, Rekor and TSA enabled, OIDC flags hidden). Pass nil for common to allocate a fresh one.

func (*SigstoreSign) AddFlags added in v0.5.0 

func (s *SigstoreSign) AddFlags(cmd *cobra.Command)

AddFlags registers SigstoreSign flags on cmd. Assumes the caller registers SigstoreCommon's flags separately so --sigstore-roots is not registered twice.

func (*SigstoreSign) ApplyToSigner added in v0.5.0 

func (s *SigstoreSign) ApplyToSigner(target *Signer) error

ApplyToSigner populates the legacy *options.Signer with the resolved sigstore.Instance held on this SigstoreSign. Tools migrating to the new OptionsSet layer call this immediately before handing the legacy Signer to signer.NewSigner. Marks the target's roots as already parsed so the runtime ParseRoots is a no-op and doesn't overwrite the resolved instance.

OIDC token-file loading is the caller's responsibility — they should read s.OIDCTokenFile, decode the wrapper into an *oauthflow.OIDCIDToken, and set target.Token before signing.

func (*SigstoreSign) Config added in v0.5.0 

func (s *SigstoreSign) Config() *command.OptionsSetConfig

Config returns the flag configuration for SigstoreSign.

func (*SigstoreSign) ResolveInstance added in v0.5.0 

func (s *SigstoreSign) ResolveInstance() (*sigstore.Instance, error)

ResolveInstance returns a fresh sigstore.Instance populated from the selected roots entry overlaid with the OIDC + toggle overrides held on this SigstoreSign. Empty OIDC override fields leave the roots file value unchanged. Returns an error if the selected instance can't be resolved.

func (*SigstoreSign) Validate added in v0.5.0 

func (s *SigstoreSign) Validate() error

Validate ensures the embedded SigstoreCommon is populated, the roots file loads cleanly, and the selected instance exists.

type SigstoreSignSet added in v0.5.0 

type SigstoreSignSet struct {
	Common *SigstoreCommon
	Sign   *SigstoreSign
}

SigstoreSignSet bundles a SigstoreCommon and a SigstoreSign sharing the same flag prefix — the typical shape needed by a CLI signing tool. AddFlags registers the common flags (--<prefix>-roots) and the sign flags (--<prefix>-instance, --<prefix>-oidc-*, etc.) in one call. Validate runs the signing-side validation. BuildSigner produces a populated *Signer ready to hand to signer.NewSigner.

func DefaultSigstoreSignSet added in v0.5.0 

func DefaultSigstoreSignSet(flagPrefix string) *SigstoreSignSet

DefaultSigstoreSignSet builds a SigstoreSignSet with the default embedded sigstore roots and signing toggles, and the supplied flag prefix applied to both the Common and Sign Config(). Empty prefix produces bare flag names (e.g. --roots, --instance).

func (*SigstoreSignSet) AddFlags added in v0.5.0 

func (s *SigstoreSignSet) AddFlags(cmd *cobra.Command)

AddFlags registers both Common and Sign flags. Common goes first so the shared --<prefix>-roots flag is registered exactly once.

func (*SigstoreSignSet) BuildSigner added in v0.5.0 

func (s *SigstoreSignSet) BuildSigner() (*Signer, error)

BuildSigner returns a *Signer populated by the resolved sigstore.Instance held on this set, ready to assign to signer.Signer.Options. Nil-safe.

func (*SigstoreSignSet) Config added in v0.5.0 

func (s *SigstoreSignSet) Config() *command.OptionsSetConfig

Config returns the SigstoreSign Config — the bundle's primary flag-namespace identity. Common's Config() is registered separately via the embedded *SigstoreCommon when AddFlags runs.

func (*SigstoreSignSet) Validate added in v0.5.0 

func (s *SigstoreSignSet) Validate() error

Validate runs the signing-side validation. Returns an error if the set was zero-valued (nil receiver or nil Sign) rather than panicking, so callers can detect "constructed" vs "zero" reliably.

type SigstoreVerification added in v0.3.0 

type SigstoreVerification struct {
	// ExpectedIssuer and ExpectedSan define the issuer and SAN to look for in
	// the fulcio cert. For a broader matching behavior, choose the *Regex
	// alternatives.
	//
	// Verification will fail if thse are not set. To skip the identity check
	// set SkipIdentityCheck to true.
	ExpectedIssuer      string
	ExpectedIssuerRegex string
	ExpectedSan         string
	ExpectedSanRegex    string

	// SkipIdentityCheck makes the verifier skip the identity check. This
	// will ignore any setting in ExpectedIssuer ExpectedIssuerRegex
	// ExpectedSan or ExpectedSanRegex
	SkipIdentityCheck bool

	// Artifact digest to check when verifier in addition to the signature
	ArtifactDigestAlgo string
	ArtifactDigest     string
}

SigstoreVerification configures how we verify signatures using a particular instance.

type SigstoreVerify added in v0.5.0 

type SigstoreVerify struct {
	*SigstoreCommon
	// contains filtered or unexported fields
}

SigstoreVerify is the OptionsSet for the verification side of a sigstore workflow. The require-CTlog/Tlog/observer-timestamp/ signed-timestamps policy is per-instance configuration that lives in sigstore-roots.json and is read by the bundle verifier directly — it's not a user-tunable knob, so this set carries no toggle flags. It exists primarily so SigstoreVerifySet has a verify-side counterpart to SigstoreSign and so SigstoreCommon's --roots flag flows through to the runtime.

func DefaultSigstoreVerify added in v0.5.0 

func DefaultSigstoreVerify(common *SigstoreCommon) *SigstoreVerify

DefaultSigstoreVerify builds a SigstoreVerify sharing the supplied common. Pass nil for common to allocate a fresh one.

func (*SigstoreVerify) AddFlags added in v0.5.0 

func (v *SigstoreVerify) AddFlags(cmd *cobra.Command)

AddFlags is a no-op. SigstoreCommon registers --roots; SigstoreVerify has no flags of its own.

func (*SigstoreVerify) ApplyToVerifier added in v0.5.0 

func (v *SigstoreVerify) ApplyToVerifier(target *Verifier) error

ApplyToVerifier writes the sigstore-roots configuration onto target so signer.NewVerifier(...) consumes it.

func (*SigstoreVerify) Config added in v0.5.0 

func (v *SigstoreVerify) Config() *command.OptionsSetConfig

Config returns the flag configuration for SigstoreVerify. Currently empty — SigstoreCommon owns the only verify-side flag (--roots). Kept so SigstoreVerify implements command.OptionsSet uniformly with the rest of the family.

func (*SigstoreVerify) Validate added in v0.5.0 

func (v *SigstoreVerify) Validate() error

Validate ensures the embedded SigstoreCommon is populated and the roots configuration loads cleanly.

type SigstoreVerifySet added in v0.5.0 

type SigstoreVerifySet struct {
	Common *SigstoreCommon
	Verify *SigstoreVerify
}

SigstoreVerifySet bundles a SigstoreCommon and a SigstoreVerify sharing the same flag prefix. Mirror of SigstoreSignSet for the verify side.

func DefaultSigstoreVerifySet added in v0.5.0 

func DefaultSigstoreVerifySet(flagPrefix string) *SigstoreVerifySet

DefaultSigstoreVerifySet builds a SigstoreVerifySet with the default embedded sigstore roots and verifier toggles, applying flagPrefix to both Common and Verify Config(). Empty prefix produces bare flag names (e.g. --roots, --require-ctlog).

func (*SigstoreVerifySet) Active added in v0.5.0 

func (s *SigstoreVerifySet) Active() bool

Active reports whether the bundled VerifierSet should consult this child. Sigstore is the always-on verification baseline — even with no user flags, the embedded sigstore.DefaultRoots make SigstoreVerifySet ready to verify, so Active is true whenever the set is non-nil. Returning false here would suppress sigstore verification entirely, which is rarely what callers want.

func (*SigstoreVerifySet) AddFlags added in v0.5.0 

func (s *SigstoreVerifySet) AddFlags(cmd *cobra.Command)

AddFlags registers both Common and Verify flags. Common first so the shared --<prefix>-roots flag is registered exactly once.

func (*SigstoreVerifySet) ApplyToVerifier added in v0.5.0 

func (s *SigstoreVerifySet) ApplyToVerifier(target *Verifier) error

ApplyToVerifier delegates to SigstoreVerify.ApplyToVerifier. Nil-safe.

func (*SigstoreVerifySet) BuildVerifier added in v0.5.0 

func (s *SigstoreVerifySet) BuildVerifier() (*Verifier, error)

BuildVerifier returns a *Verifier populated from the resolved sigstore-roots configuration. Mirrors SigstoreSignSet.BuildSigner on the verify side.

func (*SigstoreVerifySet) Config added in v0.5.0 

func (s *SigstoreVerifySet) Config() *command.OptionsSetConfig

Config returns the SigstoreVerify Config — the bundle's primary flag-namespace identity.

func (*SigstoreVerifySet) Validate added in v0.5.0 

func (s *SigstoreVerifySet) Validate() error

Validate runs the verify-side validation. Nil-safe so callers can detect a zero-value receiver without panicking.

type SpiffeCommon added in v0.5.0 

type SpiffeCommon struct {
	// TrustDomain is the expected SPIFFE trust domain (e.g.
	// "prod.example.org"). Used at sign time to assert the issued
	// SVID belongs to this trust domain, and at verify time to
	// require the SVID's trust domain matches.
	TrustDomain string
	// contains filtered or unexported fields
}

SpiffeCommon holds the SPIFFE configuration shared between SpiffeSign and SpiffeVerify. Tools that expose both operations construct one *SpiffeCommon, share it via pointer in their SpiffeSign and SpiffeVerify, and call SpiffeCommon.AddFlags(cmd) once so --spiffe-trust-domain is registered exactly once.

func DefaultSpiffeCommon added in v0.5.0 

func DefaultSpiffeCommon() *SpiffeCommon

DefaultSpiffeCommon returns an empty SpiffeCommon ready to bind flags.

func (*SpiffeCommon) AddFlags added in v0.5.0 

func (c *SpiffeCommon) AddFlags(cmd *cobra.Command)

AddFlags registers the SpiffeCommon flags on cmd.

func (*SpiffeCommon) Config added in v0.5.0 

func (c *SpiffeCommon) Config() *command.OptionsSetConfig

Config returns the flag configuration for SpiffeCommon.

func (*SpiffeCommon) ParseTrustDomain added in v0.5.0 

func (c *SpiffeCommon) ParseTrustDomain() (spiffeid.TrustDomain, error)

ParseTrustDomain returns the configured TrustDomain parsed as a spiffeid.TrustDomain. Returns the zero value (and a nil error) when TrustDomain is empty — empty means "no constraint".

func (*SpiffeCommon) Validate added in v0.5.0 

func (c *SpiffeCommon) Validate() error

Validate checks that the trust-domain string parses (when set). Empty TrustDomain is valid — it just means "don't constrain".

type SpiffeSign added in v0.5.0 

type SpiffeSign struct {
	*SpiffeCommon

	// SocketPath is the SPIFFE Workload API endpoint
	// (typically "unix:///run/spire/sockets/api.sock"). Empty falls
	// back to the SPIFFE_ENDPOINT_SOCKET env var; if both are empty,
	// Validate fails.
	SocketPath string

	// Timestamp, when true, attaches an RFC 3161 TSA-signed timestamp
	// to the bundle. The TSA URL is sourced from the embedded
	// sigstore-roots.json (the bundle that comes out carries only the
	// resulting RFC 3161 token, not the rest of the sigstore config).
	// Bound to --<prefix>-timestamp when ManagedTimestamp is false.
	Timestamp bool

	// ManagedTimestamp, when true, suppresses registration of the
	// --<prefix>-timestamp flag. Set by SignerSet so the bundled
	// --signing-timestamp can be the single user-facing knob;
	// standalone callers leave this false (default).
	ManagedTimestamp bool
	// contains filtered or unexported fields
}

SpiffeSign is the OptionsSet for the signing side of a SPIFFE workflow. It carries the Workload API socket path (with env fallback) used to fetch the X.509-SVID, plus the Timestamp toggle for RFC 3161 TSA stamps.

func DefaultSpiffeSign added in v0.5.0 

func DefaultSpiffeSign(common *SpiffeCommon) *SpiffeSign

DefaultSpiffeSign builds a SpiffeSign sharing the supplied common. Pass nil to allocate a fresh one. Timestamp defaults to true so SVID-signed bundles are durable past SVID expiry by default.

func (*SpiffeSign) AddFlags added in v0.5.0 

func (s *SpiffeSign) AddFlags(cmd *cobra.Command)

AddFlags registers SpiffeSign flags. Assumes the caller registers SpiffeCommon's flags separately so --<prefix>-trust-domain is not registered twice. The --<prefix>-timestamp flag is suppressed when ManagedTimestamp is true (set by the bundled SignerSet).

func (*SpiffeSign) BuildCredentialProvider added in v0.5.0 

func (s *SpiffeSign) BuildCredentialProvider() (*spiffe.CredentialProvider, error)

BuildCredentialProvider constructs a *spiffe.CredentialProvider from the resolved options (effective socket path + parsed trust domain). The Sign side of signer/spiffe is decoupled from signer/options (the Verifier lives in signer/spiffe/verifier so importing the sign package back here is cycle-free).

func (*SpiffeSign) Config added in v0.5.0 

func (s *SpiffeSign) Config() *command.OptionsSetConfig

Config returns the flag configuration for SpiffeSign.

func (*SpiffeSign) EffectiveSocketPath added in v0.5.0 

func (s *SpiffeSign) EffectiveSocketPath() string

EffectiveSocketPath returns the explicit SocketPath when set, or the SPIFFE_ENDPOINT_SOCKET env var otherwise. Empty when neither is set.

func (*SpiffeSign) Validate added in v0.5.0 

func (s *SpiffeSign) Validate() error

Validate ensures the trust-domain parses (when set) and that a Workload API socket is available either via flag or env var.

type SpiffeSignSet added in v0.5.0 

type SpiffeSignSet struct {
	Common *SpiffeCommon
	Sign   *SpiffeSign
}

SpiffeSignSet bundles a SpiffeCommon and a SpiffeSign sharing the same flag prefix — the typical shape needed by a CLI signing tool.

func DefaultSpiffeSignSet added in v0.5.0 

func DefaultSpiffeSignSet(flagPrefix string) *SpiffeSignSet

DefaultSpiffeSignSet builds a SpiffeSignSet with the supplied flag prefix applied to both Common and Sign Config(). Empty prefix produces bare flag names (--trust-domain, --socket).

func (*SpiffeSignSet) AddFlags added in v0.5.0 

func (s *SpiffeSignSet) AddFlags(cmd *cobra.Command)

AddFlags registers Common and Sign flags in order so the shared trust-domain flag is registered exactly once.

func (*SpiffeSignSet) BuildCredentialProvider added in v0.5.0 

func (s *SpiffeSignSet) BuildCredentialProvider() (*spiffe.CredentialProvider, error)

BuildCredentialProvider returns a *spiffe.CredentialProvider built from the resolved options. Nil-safe.

func (*SpiffeSignSet) BuildSigner added in v0.5.0 

func (s *SpiffeSignSet) BuildSigner() (*Signer, error)

BuildSigner returns a *Signer wired for the SPIFFE backend: Backend set to BackendSpiffe and Timestamp propagated from Sign.Timestamp. Callers must additionally call BuildCredentialProvider and assign the result to signer.Signer.Credentials before signing — the SPIFFE backend cannot construct credentials from Options alone. Validates the set before returning.

SigningConfig is left nil; the bundle layer (bundle.DefaultSigner.BuildBundleOptions) synthesizes a TSA-only SigningConfig at sign time when Timestamp is true, sourcing the TSA URLs from the embedded sigstore-roots. Keeping that synthesis out of the OptionsSet layer keeps SpiffeSignSet purely about flag-binding.

AppendToRekor is left zero — SPIFFE-signed bundles never go to Rekor.

func (*SpiffeSignSet) Config added in v0.5.0 

func (s *SpiffeSignSet) Config() *command.OptionsSetConfig

Config returns the SpiffeSign Config — the bundle's primary flag-namespace identity.

func (*SpiffeSignSet) Validate added in v0.5.0 

func (s *SpiffeSignSet) Validate() error

Validate runs the sign-side validation. Nil-safe.

type SpiffeVerification added in v0.5.0 

type SpiffeVerification struct {
	// TrustRootsPEM is the inline PEM-encoded set of trust anchors used to
	// validate the SVID chain. At least one of TrustRootsPEM or
	// TrustRootsPath must be set for SPIFFE verification to be enabled.
	TrustRootsPEM []byte

	// TrustRootsPath is a filesystem path to a PEM-encoded trust anchor file.
	TrustRootsPath string

	// ExpectedTrustDomain, when non-empty, asserts the leaf SVID's trust
	// domain matches this string (e.g. "prod.example.org").
	ExpectedTrustDomain string

	// ExpectedPath, when non-empty, requires an exact match on the SVID's
	// SPIFFE path component (e.g. "/workload/api").
	ExpectedPath string

	// ExpectedPathRegex, when non-empty, requires a regex match on the SVID's
	// SPIFFE path component. Mutually exclusive with ExpectedPath.
	ExpectedPathRegex string

	// SkipSVIDValidity disables enforcement of the leaf SVID's
	// NotBefore/NotAfter dates during chain validation. Default
	// (false) is the safe behavior: the verifier checks the leaf is
	// time-valid against either an RFC 3161 timestamp from the bundle
	// or time.Now(). Set true to validate the chain using the leaf's
	// NotBefore as the reference time, so the chain is checked purely
	// on its cryptographic shape — useful for archival verification
	// of bundles whose SVIDs have rotated.
	SkipSVIDValidity bool
}

SpiffeVerification carries the trust material and identity matchers used when verifying a bundle signed against a SPIFFE/SPIRE trust domain.

type SpiffeVerify added in v0.5.0 

type SpiffeVerify struct {
	*SpiffeCommon

	// TrustBundlePath is a filesystem path to a PEM-encoded SPIRE
	// upstream CA bundle. Empty falls back to SPIFFE_TRUST_BUNDLE.
	TrustBundlePath string

	// TrustBundlePEM is inline PEM-encoded trust roots set
	// programmatically. Not bound to a CLI flag — callers building
	// the verifier in code use this to skip the file step.
	TrustBundlePEM []byte

	// Path constrains the SVID's path component to this exact value.
	// Mutually exclusive with PathRegex.
	Path string

	// PathRegex constrains the SVID's path to match this regex.
	// Anchored at match time by the verifier. Mutually exclusive
	// with Path.
	PathRegex string

	// SkipSVIDValidity disables enforcement of the leaf SVID's
	// NotBefore/NotAfter dates. Default (false) is the safe
	// behavior. Set true to validate the chain on cryptographic
	// shape only — useful for archival verification of bundles whose
	// SVIDs have rotated past their TTL, when the caller trusts the
	// PKI chain alone. Bound to --<prefix>-skip-svid-validity.
	SkipSVIDValidity bool
	// contains filtered or unexported fields
}

SpiffeVerify is the OptionsSet for the verification side of a SPIFFE workflow. It carries the trust bundle (file path with env fallback, or programmatic PEM) plus the optional path constraints.

func DefaultSpiffeVerify added in v0.5.0 

func DefaultSpiffeVerify(common *SpiffeCommon) *SpiffeVerify

DefaultSpiffeVerify builds a SpiffeVerify sharing the supplied common. Pass nil to allocate a fresh one. Defaults to enforcing SVID validity dates; callers opt out by setting SkipSVIDValidity.

func (*SpiffeVerify) AddFlags added in v0.5.0 

func (v *SpiffeVerify) AddFlags(cmd *cobra.Command)

AddFlags registers SpiffeVerify flags. Assumes the caller registers SpiffeCommon's flags separately.

func (*SpiffeVerify) ApplyTo added in v0.5.0 

func (v *SpiffeVerify) ApplyTo(target *Verification) error

ApplyTo populates the SpiffeVerification fields on a Verification options struct so the verifier sees the resolved SPIFFE config. Reads the env-var fallback for the trust-bundle path so downstream code doesn't need to know about it.

func (*SpiffeVerify) ApplyToVerifier added in v0.5.0 

func (v *SpiffeVerify) ApplyToVerifier(target *Verifier) error

ApplyToVerifier populates the SPIFFE verification fields on a Verifier options struct via the embedded Verification. Mirror of SigstoreVerify.ApplyToVerifier and KeysVerify.ApplyToVerifier.

func (*SpiffeVerify) Config added in v0.5.0 

func (v *SpiffeVerify) Config() *command.OptionsSetConfig

Config returns the flag configuration for SpiffeVerify.

func (*SpiffeVerify) EffectiveTrustBundlePath added in v0.5.0 

func (v *SpiffeVerify) EffectiveTrustBundlePath() string

EffectiveTrustBundlePath returns the explicit TrustBundlePath when set, or the SPIFFE_TRUST_BUNDLE env var otherwise. Empty when neither is set.

func (*SpiffeVerify) Validate added in v0.5.0 

func (v *SpiffeVerify) Validate() error

Validate ensures the trust-domain parses (when set), the path constraints aren't both set, the path regex compiles (when set), and a trust bundle source is configured (file/env/PEM).

type SpiffeVerifySet added in v0.5.0 

type SpiffeVerifySet struct {
	Common *SpiffeCommon
	Verify *SpiffeVerify
}

SpiffeVerifySet bundles a SpiffeCommon and a SpiffeVerify sharing the same flag prefix.

func DefaultSpiffeVerifySet added in v0.5.0 

func DefaultSpiffeVerifySet(flagPrefix string) *SpiffeVerifySet

DefaultSpiffeVerifySet builds a SpiffeVerifySet with the supplied flag prefix applied to both Common and Verify Config().

func (*SpiffeVerifySet) Active added in v0.5.0 

func (s *SpiffeVerifySet) Active() bool

Active reports whether the user has configured a SPIFFE trust bundle from any source: --spiffe-trust-bundle flag, the SPIFFE_TRUST_BUNDLE env var, or programmatic TrustBundlePEM. Inactive sets contribute nothing to the bundled VerifierSet so CLIs verifying sigstore-only bundles aren't forced to set SPIFFE trust material.

func (*SpiffeVerifySet) AddFlags added in v0.5.0 

func (s *SpiffeVerifySet) AddFlags(cmd *cobra.Command)

AddFlags registers Common and Verify flags in order.

func (*SpiffeVerifySet) ApplyTo added in v0.5.0 

func (s *SpiffeVerifySet) ApplyTo(target *Verification) error

ApplyTo populates target.SpiffeVerification with the resolved SPIFFE verifier config. Nil-safe.

func (*SpiffeVerifySet) ApplyToVerifier added in v0.5.0 

func (s *SpiffeVerifySet) ApplyToVerifier(target *Verifier) error

ApplyToVerifier delegates to SpiffeVerify.ApplyToVerifier. Nil-safe.

func (*SpiffeVerifySet) BuildVerifier added in v0.5.0 

func (s *SpiffeVerifySet) BuildVerifier() (*Verifier, error)

BuildVerifier returns a *Verifier populated from the resolved SPIFFE configuration. Mirrors SpiffeSignSet.BuildSigner on the verify side.

func (*SpiffeVerifySet) Config added in v0.5.0 

func (s *SpiffeVerifySet) Config() *command.OptionsSetConfig

Config returns the SpiffeVerify Config.

func (*SpiffeVerifySet) Validate added in v0.5.0 

func (s *SpiffeVerifySet) Validate() error

Validate runs the verify-side validation. Nil-safe.

type Verification added in v0.3.0 

type Verification struct {
	SigstoreVerification
	KeyVerification
	SpiffeVerification
}

Verification options are generic options that all the Verify* functions take

type VerificationOptFunc added in v0.3.0 

type VerificationOptFunc func(*Verification) error

func WithArtifactData 

func WithArtifactData(data []byte) VerificationOptFunc

WithArtifactData hashes the artifact data to verify along the signature. This is required for message verifications

func WithExpectedIdentity 

func WithExpectedIdentity(issuer, san string) VerificationOptFunc

WithExpectedIdentity serts the ExpectedIssuer and ExptectedSan options and unsets the regex alternatives

func WithExpectedIdentityRegex added in v0.1.1 

func WithExpectedIdentityRegex(issuer, san string) VerificationOptFunc

WithExpectedIdentityRegex sets the ExpectedIssuerRegex and ExptectedSanRegex options and unsets the non-regex alternatives.

func WithExpectedSpiffeID added in v0.5.0 

func WithExpectedSpiffeID(trustDomain, path string) VerificationOptFunc

WithExpectedSpiffeID sets the expected trust domain and path for the SVID leaf. Either can be empty to skip that check; both together form an exact match (use WithExpectedSpiffeIDRegex for pattern matching on the path).

func WithExpectedSpiffeIDRegex added in v0.5.0 

func WithExpectedSpiffeIDRegex(trustDomain, pathRegex string) VerificationOptFunc

WithExpectedSpiffeIDRegex sets the expected trust domain and a regex that must match the SVID path. Unsets any exact ExpectedPath.

func WithSkipIdentityCheck 

func WithSkipIdentityCheck(yesno bool) VerificationOptFunc

WithSkipIdentityCheck instructs the verifier to not check the signature identities, only the signed payload will be checked.

func WithSpiffeTrustRootsFile added in v0.5.0 

func WithSpiffeTrustRootsFile(path string) VerificationOptFunc

WithSpiffeTrustRootsFile sets the filesystem path to a PEM-encoded SPIFFE trust anchor file.

func WithSpiffeTrustRootsPEM added in v0.5.0 

func WithSpiffeTrustRootsPEM(pem []byte) VerificationOptFunc

WithSpiffeTrustRootsPEM sets the inline PEM-encoded SPIFFE trust anchors.

type Verifier 

type Verifier struct {
	// The verifier options embed a set of verification options. These are
	// treated as defaults when calling the sigstore/dsse verifiers
	Verification

	// SigstoreRootsPath is the path to a sigstore roots file
	SigstoreRootsPath string

	// SigstoreRootsData holds raw json with data about the configured roots
	SigstoreRootsData []byte
}

Verifier options

type VerifierOptFunc 

type VerifierOptFunc func(*Verifier)

func WithSigstoreRoots added in v0.3.0 

func WithSigstoreRoots(raw []byte) VerifierOptFunc

WithSigstoreRootsData sets the sigstore roots data from raw json

func WithSigstoreRootsPath added in v0.3.0 

func WithSigstoreRootsPath(path string) VerifierOptFunc

WithSigstoreRootsPath sets the path to the sigstore roots configuration file

type VerifierSet added in v0.5.0 

type VerifierSet struct {
	Keys     *KeysVerify
	Sigstore *SigstoreVerifySet
	Spiffe   *SpiffeVerifySet
	// contains filtered or unexported fields
}

VerifierSet is the top-level verify-side OptionsSet that bundles every backend-specific child set behind one AddFlags call. Verify composes (unlike sign, which selects): a single bundle may be signed via sigstore, SPIFFE, or a raw key, so the verifier needs trust material for each path the caller is willing to accept.

AddFlags registers every child's flags so the CLI's --help shows the full surface. Validate and ApplyToVerifier consult only the children that are Active — i.e., where the user has supplied enough configuration to use them. A user verifying a sigstore-only bundle leaves --key and --spiffe-trust-bundle unset and gets no "missing trust material" error from the inactive children.

Sigstore is always Active when present: the embedded sigstore.DefaultRoots make it the baseline verifier even with no user flags. Keys is Active when --key is provided. SPIFFE is Active when --spiffe-trust-bundle is provided (or SPIFFE_TRUST_BUNDLE env var, or programmatic TrustBundlePEM).

Typical use: 

set := DefaultVerifierSet()
set.AddFlags(cmd)
// ... after cobra parses ...
if err := set.Validate(); err != nil { ... }
opts, err := set.BuildVerifier()
runtime := signer.NewVerifier(func(v *options.Verifier) { *v = *opts })

func DefaultVerifierSet added in v0.5.0 

func DefaultVerifierSet() *VerifierSet

DefaultVerifierSet builds a VerifierSet with every child constructed under its conventional flag prefix ("sigstore", "spiffe"; KeysVerify uses bare --key).

func (*VerifierSet) AddFlags added in v0.5.0 

func (v *VerifierSet) AddFlags(cmd *cobra.Command)

AddFlags registers every non-nil child's flags. Order is fixed (keys → sigstore → spiffe) so --help output is stable across runs.

func (*VerifierSet) ApplyToVerifier added in v0.5.0 

func (v *VerifierSet) ApplyToVerifier(target *Verifier) error

ApplyToVerifier composes every Active child's contribution onto target. Children write disjoint fields (KeysVerify → Verification.PubKeys; SigstoreVerifySet → SigstoreRoots*; SpiffeVerifySet → Verification.TrustRoots* + ExpectedTrustDomain + ExpectedPath*) so the order they're applied in does not matter. Inactive children are skipped.

func (*VerifierSet) BuildVerifier added in v0.5.0 

func (v *VerifierSet) BuildVerifier() (*Verifier, error)

BuildVerifier returns a *Verifier populated by every Active child, starting from DefaultVerifier (which carries the embedded sigstore DefaultRoots). Mirror of SignerSet.BuildSigner on the verify side.

func (*VerifierSet) Config added in v0.5.0 

func (v *VerifierSet) Config() *command.OptionsSetConfig

Config returns the (empty) flag config for the VerifierSet itself. The set has no own flags; every flag belongs to a child whose Config() remains the authoritative source for its namespace.

func (*VerifierSet) Validate added in v0.5.0 

func (v *VerifierSet) Validate() error

Validate runs each Active child's validation, joining any errors so callers see every problem at once. Inactive children are skipped — their flags can be left unset without failing validation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.