sigstore

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultTrustedRootMaxAge = 30 * 24 * time.Hour

DefaultTrustedRootMaxAge is the staleness window for an embedded trusted root. Once the instance's snapshot date is older than this, TrustedRoot refreshes the trust material from TUF instead of using the embed.

Variables

View Source 
var DefaultRoots []byte

Functions

func TrustedRoot added in v0.5.3 

func TrustedRoot(opts ...TrustedRootOptFn) (*root.TrustedRoot, error)

TrustedRoot resolves the sigstore trusted root for the default instance (Roots[0], which is the public good sigstore instance) or the one selected if selected with WithInstance().

It is the single source of sigstore trust material for the signer and its consumers. See (*Instance).TrustedRoot for the resolution order.

Types

type CaCertMatcher 

type CaCertMatcher func()

type CredentialProvider added in v0.5.0 

type CredentialProvider struct {
	// Instance holds the sigstore configuration (TUF options, signing config,
	// OIDC client config, verifier config).
	Instance *Instance

	// DisableSTS skips the ambient credential providers.
	DisableSTS bool

	// Token is an optional pre-provided OIDC ID token. When set, Prepare skips
	// the ambient STS providers; the token still flows through OIDConnect so
	// that it is parsed/validated the same way as a freshly issued one.
	// Treated as read-only input: Prepare stores the parsed result in the
	// private token field instead of writing back here.
	Token *oauthflow.OIDCIDToken
	// contains filtered or unexported fields
}

CredentialProvider implements bundle.CredentialProvider and binds a sigstore instance (OIDC provider + Fulcio) to a signer.

func NewCredentialProvider added in v0.5.0 

func NewCredentialProvider(instance *Instance) *CredentialProvider

NewCredentialProvider creates a sigstore CredentialProvider for the given Instance.

func (*CredentialProvider) CertificateProvider added in v0.5.0 

func (p *CredentialProvider) CertificateProvider() (sign.CertificateProvider, *sign.CertificateProviderOptions)

CertificateProvider returns the Fulcio provider and the OIDC ID token that authenticates the signing cert request. The token parsed during Prepare wins; the public Token field is the fallback for providers assembled by hand that never went through Prepare.

func (*CredentialProvider) CertifiedKey added in v0.5.3 

func (p *CredentialProvider) CertifiedKey(ctx context.Context) (
	leaf *x509.Certificate, chain []*x509.Certificate, key crypto.Signer, err error,
)

CertifiedKey runs the keyless (Fulcio) flow with a freshly generated key and returns the leaf certificate with its intermediate chain (leaf-adjacent first, root excluded), and the private key. The material is suitable for building a detached CMS/PKCS7 signature. We built this to emulate the gitsign signer but it can be used to sign anything with the same ambient identity the sigstore bundle backend signs with.

Unlike the bundle path, the returned key is available to the caller as a crypto.Signer,. this function generates its own key and drives the Fulcio certificate request with it but ( as opposed to sigstore-go's that hides its its key in EphemeralKeypair), the issued certificate binds to a key the caller gets to keep.

The ambient OIDC token and Fulcio provider are obtained through Prepare, so an injected Token / DisableSTS is honored exactly like the signing path.

func (*CredentialProvider) Intermediates added in v0.5.0 

func (p *CredentialProvider) Intermediates() []*x509.Certificate

Intermediates returns nil. The Fulcio chain is reconstructed at verify time from the sigstore TUF root, so no intermediates are embedded in the bundle's VerificationMaterial.

func (*CredentialProvider) Keypair added in v0.5.0 

func (p *CredentialProvider) Keypair() sign.Keypair

Keypair returns the ephemeral keypair bound to the Fulcio certificate.

func (*CredentialProvider) Prepare added in v0.5.0 

func (p *CredentialProvider) Prepare(ctx context.Context) error

Prepare runs the OIDC flow, ensures TUF roots are on disk, generates an ephemeral keypair, and builds the Fulcio certificate provider. Subsequent calls are no-ops. Safe for concurrent use.

type Instance added in v0.3.2 

type Instance struct {
	// Embed the tuf options struct
	tuf.TufOptions

	// ID is the stable identifier for the instance. We ship with "sigstore" and
	// "github"). It selects the embedded TUF bootstrap and trusted roots from
	// (roots/<id>.json and roots/<id>.trusted_root.json).
	ID string `json:"id"`

	// TrustedRootSnapshot records when the embedded trusted_root.json for
	// this instance was captured. TrustedRoot uses it to decide whether the
	// embedded copy is still fresh (see DefaultTrustedRootMaxAge) or should
	// be refreshed from TUF.
	TrustedRootSnapshot time.Time `json:"trusted-root-snapshot"`

	// SigningConfig holds the official sigstore signing configuration
	// (application/vnd.dev.sigstore.signingconfig.v0.2+json).
	SigningConfig *root.SigningConfig `json:"-"`

	Timestamp bool

	// AppendToRekor controls if the signing operation is recorded into the
	// transparency log.
	AppendToRekor bool `json:"rekor-append"`
	DisableSTS    bool

	// Hide the OIDC options in the CLI --help
	HideOIDCOptions bool
	// FlagPrefix adds a prefix to the CLI strings, these help grouping them
	FlagPrefix string

	// OIDCConfig holds the client-side OIDC configuration.
	OIDCConfig OIDCConfig `json:"oidc-config"`

	// VerifierConfig holds the verification policy options.
	VerifierConfig VerifierConfig `json:"verifier-config"`
}

Instance captures the configuration required to talk to a sigstore instance.

func (*Instance) FulcioURL added in v0.3.2 

func (i *Instance) FulcioURL() string

FulcioURL returns the Fulcio CA URL from the signing config.

func (*Instance) OidcIssuerURL added in v0.4.0 

func (i *Instance) OidcIssuerURL() string

OidcIssuerURL returns the OIDC issuer URL from the signing config.

func (*Instance) RekorURL added in v0.3.2 

func (i *Instance) RekorURL() string

RekorURL returns the Rekor transparency log URL from the signing config.

func (*Instance) TrustedRoot added in v0.5.3 

func (i *Instance) TrustedRoot(opts ...TrustedRootOptFn) (*root.TrustedRoot, error)

TrustedRoot resolves the trusted root for the current sigstore instance. The resolution order is:

  1. First, any supplied override (WithTrustedRootJSON/WithTrustedRootPath) wins
  2. If there is an embedded roots/instance-id.trusted_root.json and its fresh (snapshot is within MaxAge and its Fulcio anchors are not expired) and TUF is not forced, the the embeds are used. Here we make no network calls.
  3. Otherwise a TUF fetch of the live trusted root as defined in the roots.
  4. If the TUF fetch fails but a stale embed exists, the embed is used and a warning is logged so verification works.

func (*Instance) ValidateOIDC added in v0.3.2 

func (i *Instance) ValidateOIDC() error

ValidateOIDC checks that the OIDC properties are correct

func (*Instance) ValidateSigner added in v0.3.2 

func (i *Instance) ValidateSigner() error

func (*Instance) ValidateSigningConfig added in v0.4.0 

func (i *Instance) ValidateSigningConfig() error

ValidateSigningConfig checks that the instance has a valid signing config.

func (*Instance) ValidateTimestamps added in v0.3.2 

func (i *Instance) ValidateTimestamps() error

ValidateTimestamps checks that at least one timestamp verification method is set.

func (*Instance) ValidateVerifier added in v0.3.2 

func (i *Instance) ValidateVerifier() error

type InstanceConfig 

type InstanceConfig struct {
	IssuerOrg        string          `json:"issuer-org"`
	SigningConfigRaw json.RawMessage `json:"signing-config"`
	Instance
}

type OIDCConfig added in v0.4.0 

type OIDCConfig struct {
	// RedirectURL defines the URL that the browser will redirect to.
	// If the port is set to 0, it will be randomized to a high number
	// port before starting the OIDC flow.
	RedirectURL string `json:"redirect-url"`

	// ClientID is the OIDC client ID to stamp on the tokens.
	ClientID string `json:"client-id"`

	// ClientSecret is the OIDC client secret.
	ClientSecret string `json:"client-secret"`
}

OIDCConfig captures the client-side OIDC configuration for a sigstore instance.

func (*OIDCConfig) Validate added in v0.4.0 

func (oc *OIDCConfig) Validate() error

Validate checks that the required OIDC client fields are set.

type SignerKeypair added in v0.5.3 

type SignerKeypair struct {
	// contains filtered or unexported fields
}

SignerKeypair adapts a caller-provided crypto.Signer to the sigstore-go sign.Keypair interface. Unlike sign.EphemeralKeypair — which generates its private key internally and never exposes it — SignerKeypair signs with a key the caller owns and keeps. That is what lets CertifiedKey hand the private key back so callers can build a detached CMS/PKCS7 signature (e.g. a signed git tag) with the same keyless identity the signer uses.

func NewSignerKeypair added in v0.5.3 

func NewSignerKeypair(signer crypto.Signer, opts *SignerKeypairOptions) (*SignerKeypair, error)

NewSignerKeypair wraps signer in a sign.Keypair. When opts is nil the keypair defaults to ECDSA P-256 SHA-256 with a SHA-256 public-key hint. The logic mirrors sign.NewEphemeralKeypair, but signs with the provided key instead of a freshly generated one.

func (*SignerKeypair) GetHashAlgorithm added in v0.5.3 

func (k *SignerKeypair) GetHashAlgorithm() protocommon.HashAlgorithm

GetHashAlgorithm returns the hash algorithm used to compute the digest to sign.

func (*SignerKeypair) GetHint added in v0.5.3 

func (k *SignerKeypair) GetHint() []byte

GetHint returns the fingerprint of the public key.

func (*SignerKeypair) GetKeyAlgorithm added in v0.5.3 

func (k *SignerKeypair) GetKeyAlgorithm() string

GetKeyAlgorithm returns the top-level key algorithm, used as part of requests to Fulcio.

func (*SignerKeypair) GetPublicKey added in v0.5.3 

func (k *SignerKeypair) GetPublicKey() crypto.PublicKey

GetPublicKey returns the public key.

func (*SignerKeypair) GetPublicKeyPem added in v0.5.3 

func (k *SignerKeypair) GetPublicKeyPem() (string, error)

GetPublicKeyPem returns the public key in PEM format.

func (*SignerKeypair) GetSigningAlgorithm added in v0.5.3 

func (k *SignerKeypair) GetSigningAlgorithm() protocommon.PublicKeyDetails

GetSigningAlgorithm returns the signing algorithm of the key.

func (*SignerKeypair) SignData added in v0.5.3 

func (k *SignerKeypair) SignData(_ context.Context, data []byte) (sig, digest []byte, err error)

SignData returns the signature and the data that was signed (a digest, except for pure Ed25519). It mirrors sign.EphemeralKeypair.SignData over the provided key.

type SignerKeypairOptions added in v0.5.3 

type SignerKeypairOptions struct {
	// Hint is the optional public-key fingerprint sent to Fulcio. When empty a
	// base64-encoded SHA-256 hash of the DER-encoded public key is used, exactly
	// like sigstore-go's EphemeralKeypair.
	Hint []byte

	// Algorithm selects the signing algorithm. Defaults to ECDSA P-256 SHA-256.
	Algorithm protocommon.PublicKeyDetails
}

SignerKeypairOptions configures a SignerKeypair.

type SigstoreRoots 

type SigstoreRoots struct {
	Roots []InstanceConfig `json:"roots"`
}

func ParseRoots 

func ParseRoots(data []byte) (*SigstoreRoots, error)

ParseRoots parses a roots file

func ParseRootsFile 

func ParseRootsFile(path string) (*SigstoreRoots, error)

ParseRootsFile parses a sigstore roots file

type TrustedRootOptFn added in v0.5.3 

type TrustedRootOptFn func(*trustedRootOptions)

TrustedRootOptFn configures a TrustedRoot lookup.

func WithForceTUF added in v0.5.3 

func WithForceTUF() TrustedRootOptFn

WithForceTUF skips the embedded trusted root entirely and always fetches from TUF. Because the embed is bypassed, it is not available as a resilient fallback if the TUF fetch fails.

func WithInstance added in v0.5.3 

func WithInstance(id string) TrustedRootOptFn

WithInstance indicates the sigstore instance (by ID) for which we will resolve its roots. Only meaningful for the package level TrustedRoot method, it is ignored by the (*Instance).TrustedRoot method which returns its own root.

func WithMaxAge added in v0.5.3 

func WithMaxAge(d time.Duration) TrustedRootOptFn

WithMaxAge overrides the staleness window for the embedded trusted root. A zero (or negative) duration forces the embed to be treated as stale so the TUF path is taken (falling back to the embed only if TUF fails).

func WithRoots added in v0.5.3 

func WithRoots(roots *SigstoreRoots) TrustedRootOptFn

WithRoots supplies the parsed sigstore roots to resolve the instance from. When unset, we use the embedded DefaultRoots. Only meaningful for the package level TrustedRoot.

func WithTrustedRootJSON added in v0.5.3 

func WithTrustedRootJSON(b []byte) TrustedRootOptFn

WithTrustedRootJSON provides to the solver the trusted root material directly. It short circuits instance resolution and the embeds, in favor of the supplied bytes

func WithTrustedRootPath added in v0.5.3 

func WithTrustedRootPath(p string) TrustedRootOptFn

WithTrustedRootPath loads trusted root material from a file. Like WithTrustedRootJSON it wins over any instance embed or TUF fetch.

func WithoutEmbedded added in v0.5.3 

func WithoutEmbedded() TrustedRootOptFn

WithoutEmbedded is an alias of WithForceTUF: it opts out of the embedded trusted root and forces a TUF fetch.

type VerifierConfig added in v0.4.0 

type VerifierConfig struct {
	// Look for a signed timestamp in the cert and verify with the CTLog Auth
	RequireCTlog bool `json:"require-ct-log"`
	// Verify the cert validity in the transparency log
	RequireTlog bool `json:"require-tlog"`
	// Verify the certificate validity time with a signed timestamp
	RequireSignedTimestamps bool `json:"require-signed-timestamps"`
	// Require an observer timestamp for verification
	RequireObserverTimestamp bool `json:"require-observer-timestamp"`
}

VerifierConfig captures the verification policy for a sigstore instance.

func (*VerifierConfig) Validate added in v0.4.0 

func (vc *VerifierConfig) Validate() error

Validate checks that at least one timestamp verification method is set.

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.