sign

Documentation

Overview

Package sign creates Sigstore attestations for evidence packs.

This package defines the Signer interface and provides high-level pack signing operations. The sign/sigstore subpackage provides the Sigstore implementation.

Package Structure

• sign: Interface definitions and pack signing operations (SignPackFile)
• sign/sigstore: Sigstore implementation (Fulcio, Rekor, TSA integration)

Signing Methods

Keyless (OIDC): Uses Sigstore's Fulcio CA with identity from an OIDC provider (Google, GitHub, etc.). The signer's identity is embedded in a short-lived certificate and recorded in the Rekor transparency log.

signer, err := sigstore.NewSigner(ctx, sigstore.Options{
    OIDC: &sigstore.OIDCOptions{Interactive: true},
})
if err != nil {
    log.Fatal(err)
}
if err := sign.SignPackFile(ctx, "evidence.epack", signer); err != nil {
    log.Fatal(err)
}

Key-based: Uses a provided private key for signing.

signer, err := sigstore.NewSigner(ctx, sigstore.Options{
    PrivateKey: privateKey,
})
if err != nil {
    log.Fatal(err)
}
if err := sign.SignPackFile(ctx, "evidence.epack", signer); err != nil {
    log.Fatal(err)
}

Signing creates an in-toto attestation with the pack digest as the subject, wraps it in a DSSE envelope with a Sigstore bundle, and appends it to the pack.

Backward Compatibility

For backward compatibility, this package re-exports commonly used types from sign/sigstore. New code should import sign/sigstore directly.

Package sign provides Sigstore signing for evidence packs.

Index

• Constants
• func LoadPrivateKey(path string) (crypto.Signer, error)
• func MarshalBundle(b *bundle.Bundle) ([]byte, error)
• func NewStatement(packDigest, stream string) (*intoto.Statement, error)
• func SignPackFile(ctx context.Context, packPath string, s Signer) error
• func SignPackFileWithOptions(ctx context.Context, packPath string, s Signer, opts MemoryLimitOptions) error
• func UnmarshalBundle(data []byte) (*bundle.Bundle, error)
• type MemoryLimitOptions
• type SignPackOptions
  • func (o *SignPackOptions) Method() string
  • func (o *SignPackOptions) Validate() error
• type Signer
  • func NewKeySignerFromPath(ctx context.Context, keyPath string) (Signer, error)
  • func NewKeylessSigner(ctx context.Context) (Signer, error)
  • func NewSignerFromOptions(ctx context.Context, opts SignPackOptions) (Signer, error)

Constants

const (
	DefaultFulcioURL   = sigstore.DefaultFulcioURL
	DefaultRekorURL    = sigstore.DefaultRekorURL
	SigstoreOIDCIssuer = sigstore.SigstoreOIDCIssuer
	SigstoreClientID   = sigstore.SigstoreClientID
)

Re-export sigstore package constants for convenience.

const MaxPrivateKeySize = 64 * 1024 // 64 KB

MaxPrivateKeySize is the maximum size of a private key file. Private keys are typically small (< 10KB even for RSA 4096). This limit prevents memory exhaustion from malicious paths.

Functions

func LoadPrivateKey

func LoadPrivateKey(path string) (crypto.Signer, error)

LoadPrivateKey loads a PEM-encoded private key from a file. Supports EC, PKCS8, and RSA private key formats.

func MarshalBundle

func MarshalBundle(b *bundle.Bundle) ([]byte, error)

MarshalBundle serializes a bundle to JSON.

func NewStatement

func NewStatement(packDigest, stream string) (*intoto.Statement, error)

NewStatement creates an in-toto statement for an evidence pack. The packDigest should be in "algo:hash" format (e.g., "sha256:abc123").

func SignPackFile

func SignPackFile(ctx context.Context, packPath string, s Signer) error

SignPackFile signs an evidence pack and writes the attestation back to it. Uses DefaultSigningMemoryLimit; use SignPackFileWithOptions for larger packs.

func SignPackFileWithOptions

func SignPackFileWithOptions(ctx context.Context, packPath string, s Signer, opts MemoryLimitOptions) error

SignPackFileWithOptions signs a pack with configurable memory limits. Attestation is written to attestations/{sha256(identity)}.sigstore.json. TOCTOU-safe: snapshots pack, verifies integrity, then writes from snapshot.

func UnmarshalBundle

func UnmarshalBundle(data []byte) (*bundle.Bundle, error)

UnmarshalBundle deserializes a bundle from JSON.

Types

type MemoryLimitOptions

type MemoryLimitOptions struct {
	// MaxMemoryBytes limits memory for in-memory snapshot.
	// Defaults to DefaultSigningMemoryLimit (256 MB).
	// Total memory ≈ MaxMemoryBytes × concurrent_requests.
	MaxMemoryBytes int64
}

MemoryLimitOptions configures memory limits for signing operations. This is separate from SignPackOptions which configures authentication.

type SignPackOptions

type SignPackOptions struct {
	// KeyPath is the path to a PEM-encoded private key.
	// Mutually exclusive with OIDCToken/Interactive.
	KeyPath string

	// OIDCToken is the OIDC token for keyless signing.
	// If empty and Interactive is false, ambient credentials are used
	// (e.g., ACTIONS_ID_TOKEN_REQUEST_TOKEN in GitHub Actions).
	OIDCToken string

	// Interactive enables browser-based OIDC authentication.
	// When true and OIDCToken is empty, opens a browser for authentication.
	Interactive bool

	// SkipTlog skips the transparency log (Rekor).
	// When true, signatures are not recorded in the public log.
	SkipTlog bool

	// TSAURLs are optional timestamp authority URLs for RFC3161 timestamps.
	// Requires InsecureAllowCustomEndpoints to be set.
	TSAURLs []string

	// InsecureAllowCustomEndpoints permits non-default TSA/Fulcio/Rekor URLs.
	// Use with caution - custom endpoints could capture OIDC tokens.
	// CLI: --insecure-allow-custom-endpoints
	InsecureAllowCustomEndpoints bool
}

SignPackOptions configures high-level pack signing. Simplified interface over sigstore.Options that handles key loading and OIDC token resolution.

func (*SignPackOptions) Method

func (o *SignPackOptions) Method() string

Method returns "key" or "oidc" based on the configuration.

func (*SignPackOptions) Validate

func (o *SignPackOptions) Validate() error

Validate checks that SignPackOptions are valid.

type Signer

type Signer interface {
	// Sign creates a Sigstore bundle for the given in-toto statement JSON.
	Sign(ctx context.Context, statement []byte) (*bundle.Bundle, error)

	// Identity returns the signer's identity (email, URI, or key fingerprint).
	Identity() string
}

Signer signs evidence packs using Sigstore.

func NewKeySignerFromPath

func NewKeySignerFromPath(ctx context.Context, keyPath string) (Signer, error)

NewKeySignerFromPath creates a Signer using a PEM-encoded private key. This is the recommended constructor for key-based signing.

The signature is recorded in the transparency log by default. For private signing (no tlog), use NewSignerFromOptions with SkipTlog.

Example:

signer, err := sign.NewKeySignerFromPath(ctx, "private-key.pem")
if err != nil {
    return err
}
if err := sign.SignPackFile(ctx, "evidence.epack", signer); err != nil {
    return err
}

func NewKeylessSigner

func NewKeylessSigner(ctx context.Context) (Signer, error)

NewKeylessSigner creates a Signer using OIDC/keyless authentication. This is the recommended constructor for keyless signing - it opens a browser for interactive authentication and records the signature in the transparency log.

For CI/CD environments, use NewSignerFromOptions with an OIDCToken instead.

Example:

signer, err := sign.NewKeylessSigner(ctx)
if err != nil {
    return err
}
if err := sign.SignPackFile(ctx, "evidence.epack", signer); err != nil {
    return err
}

func NewSignerFromOptions

func NewSignerFromOptions(ctx context.Context, opts SignPackOptions) (Signer, error)

NewSignerFromOptions creates a Signer from high-level options. This handles key loading and OIDC configuration, returning a ready-to-use Signer.

For simple use cases, prefer NewKeylessSigner or NewKeySignerFromPath.