verify

package
v0.1.21 Latest Latest
Warning

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

 Go to latest Published: Feb 27, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package verify validates Sigstore attestations in evidence packs.

This package handles:

  • Loading Sigstore bundles from attestation files
  • Verifying signatures against the transparency log
  • Extracting signer identity (issuer, subject)
  • Matching attestation subjects to pack digests

Example: 

result, err := verify.VerifyAttestation(ctx, bundleBytes, opts)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Signed by: %s\n", result.Subject)

Identity verification requires specifying expected issuer and/or subject using exact match or regular expressions.

Package verify provides signature verification for attestations in evidence packs.

The package defines a Verifier interface that can be implemented by different verification backends. The primary implementation uses sigstore-go for Sigstore-based verification.

Index

Constants

View Source 
const (
	// GoogleAccountsIssuer is the OIDC issuer for Google Accounts.
	GoogleAccountsIssuer = "https://accounts.google.com"

	// GitHubActionsIssuer is the OIDC issuer for GitHub Actions.
	GitHubActionsIssuer = "https://token.actions.githubusercontent.com"
)

Common OIDC issuers for preset verifiers.

Variables

This section is empty.

Functions

func LoadTrustedRoot 

func LoadTrustedRoot(jsonData []byte) (root.TrustedMaterial, error)

LoadTrustedRoot loads a trusted root from JSON data. This is useful for loading custom trust roots for private Sigstore instances.

func ValidateAttestation 

func ValidateAttestation(data []byte) error

ValidateAttestation performs size and depth validation before parsing.

func ValidateAttestationDepth 

func ValidateAttestationDepth(data []byte) error

ValidateAttestationDepth checks that JSON nesting depth is within limits. This prevents stack overflow during parsing of deeply nested structures.

func ValidateAttestationSize 

func ValidateAttestationSize(data []byte) error

ValidateAttestationSize checks that attestation data is within size limits.

func VerifyStatementSemantics 

func VerifyStatementSemantics(result *Result, expectedPackDigest string) error

VerifyStatementSemantics validates the in-toto statement structure and content. Checks statement type, predicate type, and that subject/predicate pack_digest match expected.

Types

type Identity 

type Identity struct {
	// Issuer is the OIDC issuer that authenticated the signer (e.g., "https://accounts.google.com").
	Issuer string

	// Subject is the subject alternative name from the certificate (e.g., email or URI).
	Subject string

	// SubjectAlternativeNames contains all SANs from the certificate.
	SubjectAlternativeNames []string
}

Identity represents the verified signer identity from the certificate.

type Option 

type Option func(*config)

Option configures a Verifier.

func WithInsecureSkipIdentityCheck deprecated 

func WithInsecureSkipIdentityCheck() Option

WithInsecureSkipIdentityCheck disables certificate identity verification. Any certificate chaining to the trusted root is accepted, regardless of issuer or subject. Use only for tests; in production, use WithIssuer/WithSubject.

Deprecated: Use WithInsecureSkipIdentityCheckForTesting instead for clearer intent.

func WithInsecureSkipIdentityCheckForTesting 

func WithInsecureSkipIdentityCheckForTesting() Option

WithInsecureSkipIdentityCheckForTesting disables certificate identity verification. This accepts ANY valid signature from ANY signer - use ONLY in test code.

In production, always use NewStrictVerifier or configure WithIssuer/WithSubject to ensure attestations come from expected signers.

Example (test only): 

verifier, _ := verify.NewSigstoreVerifier(
    verify.WithInsecureSkipIdentityCheckForTesting(),
)

func WithIssuer 

func WithIssuer(issuer string) Option

WithIssuer requires the certificate issuer to match exactly.

func WithIssuerRegexp 

func WithIssuerRegexp(pattern *regexp.Regexp) Option

WithIssuerRegexp requires the certificate issuer to match a regular expression.

func WithOffline 

func WithOffline() Option

WithOffline disables online transparency log verification. When offline, verification relies on embedded timestamps only.

func WithSubject 

func WithSubject(subject string) Option

WithSubject requires the certificate subject (SAN) to match exactly.

func WithSubjectRegexp 

func WithSubjectRegexp(pattern *regexp.Regexp) Option

WithSubjectRegexp requires the certificate subject (SAN) to match a regular expression.

func WithTimestampAuthorityThreshold 

func WithTimestampAuthorityThreshold(threshold int) Option

WithTimestampAuthorityThreshold sets the minimum number of TSA timestamps required. Default is 0 (no TSA timestamps required).

func WithTransparencyLogThreshold 

func WithTransparencyLogThreshold(threshold int) Option

WithTransparencyLogThreshold sets the minimum number of transparency log entries required. Default is 1 when online verification is enabled.

func WithTrustedRoot 

func WithTrustedRoot(tr root.TrustedMaterial) Option

WithTrustedRoot uses a custom trusted root instead of Sigstore Public Good. This is useful for private Sigstore instances or enterprise PKI.

type Result 

type Result struct {
	// Verified indicates whether the signature was cryptographically valid.
	Verified bool

	// Identity contains information about who signed the attestation.
	Identity *Identity

	// Timestamps contains when the signature was observed/verified.
	Timestamps []time.Time

	// Statement contains the decoded in-toto statement payload, if applicable.
	Statement *Statement

	// TransparencyLog contains info about the transparency log entry, if available.
	TransparencyLog *TransparencyLogEntry
}

Result contains the outcome of attestation verification.

type SigstoreVerifier 

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

SigstoreVerifier implements Verifier using sigstore-go. It verifies attestations stored as Sigstore bundles.

func NewGitHubActionsVerifier 

func NewGitHubActionsVerifier(repo string, workflow string, opts ...Option) (*SigstoreVerifier, error)

NewGitHubActionsVerifier creates a verifier for GitHub Actions workload identity. It verifies that attestations were signed by a specific GitHub repository and optionally a specific workflow.

The repo parameter should be in "owner/repo" format (e.g., "myorg/myrepo"). The workflow parameter is optional; if provided, it restricts to a specific workflow file (e.g., "release.yml" or ".github/workflows/release.yml").

Example: 

// Any workflow in the repo
v, err := verify.NewGitHubActionsVerifier("myorg/myrepo", "")

// Specific workflow only
v, err := verify.NewGitHubActionsVerifier("myorg/myrepo", "release.yml")

func NewGoogleAccountVerifier 

func NewGoogleAccountVerifier(email string, opts ...Option) (*SigstoreVerifier, error)

NewGoogleAccountVerifier creates a verifier for any Google account. It verifies that attestations were signed by a specific Google account email.

Example: 

v, err := verify.NewGoogleAccountVerifier("user@example.com")

func NewGoogleCloudVerifier 

func NewGoogleCloudVerifier(serviceAccount string, opts ...Option) (*SigstoreVerifier, error)

NewGoogleCloudVerifier creates a verifier for Google Cloud workload identity. It verifies that attestations were signed by a specific service account.

The serviceAccount parameter should be the full email address (e.g., "my-sa@my-project.iam.gserviceaccount.com").

Example: 

v, err := verify.NewGoogleCloudVerifier("builder@my-project.iam.gserviceaccount.com")

func NewSigstoreVerifier 

func NewSigstoreVerifier(opts ...Option) (*SigstoreVerifier, error)

NewSigstoreVerifier creates a new Verifier backed by sigstore-go. By default, it uses the Sigstore Public Good instance for trust material and requires online verification against the transparency log.

For production use, prefer NewStrictVerifier which enforces identity checks. This constructor requires explicit identity configuration or opt-in to WithInsecureSkipIdentityCheck for testing.

func NewStrictVerifier 

func NewStrictVerifier(issuer, subject string, opts ...Option) (*SigstoreVerifier, error)

NewStrictVerifier creates a Verifier that requires identity verification. This is the recommended constructor for production use - it ensures both issuer and subject are checked, preventing impersonation attacks.

Parameters:

  • issuer: Required OIDC issuer (e.g., "https://accounts.google.com")
  • subject: Required certificate subject/SAN (e.g., "user@example.com")
  • opts: Additional options (e.g., WithOffline, WithTrustedRoot)

Example: 

verifier, err := verify.NewStrictVerifier(
    "https://accounts.google.com",
    "security-team@company.com",
)

func (*SigstoreVerifier) Verify 

func (v *SigstoreVerifier) Verify(ctx context.Context, attestation []byte) (*Result, error)

Verify verifies a Sigstore bundle attestation. The attestation parameter should be the raw Sigstore bundle JSON. This verifies the cryptographic signature and identity policy. Callers should separately verify that the statement's subject digest matches the expected pack digest.

Note: The context parameter is accepted for interface compatibility but is not currently used by the underlying sigstore-go library. Verification is not cancelable once started.

type Statement 

type Statement struct {
	// Type is the in-toto statement type (e.g., "https://in-toto.io/Statement/v1").
	Type string

	// PredicateType is the predicate type URI.
	PredicateType string

	// Subjects contains the subjects (artifacts) the statement refers to.
	Subjects []Subject

	// Predicate contains the raw predicate JSON.
	Predicate []byte
}

Statement represents a decoded in-toto statement from the attestation payload.

type Subject 

type Subject struct {
	Name   string
	Digest map[string]string
}

Subject represents an in-toto subject (artifact reference).

type TransparencyLogEntry 

type TransparencyLogEntry struct {
	// LogIndex is the index of the entry in the transparency log.
	LogIndex int64

	// LogID is the ID of the transparency log (e.g., Rekor log ID).
	LogID string
}

TransparencyLogEntry contains information about a transparency log entry.

type Verifier 

type Verifier interface {
	// Verify verifies an attestation's cryptographic signature.
	// The attestation parameter should be the raw Sigstore bundle JSON.
	// Returns the verification result including the parsed statement.
	Verify(ctx context.Context, attestation []byte) (*Result, error)
}

Verifier verifies attestation signatures.

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.