Deep Dive: How Sigstore 2 Keyless Signing Works Under the Hood for Open Source Software Supply Chain

// fulcio_client.go: Core logic for requesting short-lived signing certificates from Fulcio
// Part of the Sigstore client library (https://github.com/sigstore/sigstore)
package sigstore

import (
    "context"
    "crypto/ecdsa"
    "crypto/elliptic"
    "crypto/rand"
    "crypto/x509"
    "encoding/pem"
    "errors"
    "fmt"
    "net/http"
    "time"

    "github.com/coreos/go-oidc/v3/oidc"
    fulcioclient "github.com/sigstore/fulcio/pkg/client"
    "github.com/sigstore/fulcio/pkg/identity"
    "github.com/sigstore/fulcio/pkg/oidc"
)

// OIDCCredential holds validated OIDC token and issuer metadata
type OIDCCredential struct {
    Token     string
    IssuerURL string
    Subject   string // OIDC subject (e.g., "repo:owner/repo:ref:refs/heads/main")
}

// RequestFulcioCertificate requests a short-lived signing certificate from Fulcio
// using a validated OIDC credential. Returns the DER-encoded certificate and ephemeral private key.
func RequestFulcioCertificate(ctx context.Context, cred *OIDCCredential, fulcioURL string) (*x509.Certificate, *ecdsa.PrivateKey, error) {
    // 1. Validate OIDC token and extract issuer metadata
    provider, err := oidc.NewProvider(ctx, cred.IssuerURL)
    if err != nil {
        return nil, nil, fmt.Errorf("failed to initialize OIDC provider: %w", err)
    }

    // Verify OIDC token signature and validity
    verifier := provider.Verifier(&oidc.Config{SkipClientIDCheck: true}) // Fulcio skips client ID check for public OIDC providers
    idToken, err := verifier.Verify(ctx, cred.Token)
    if err != nil {
        return nil, nil, fmt.Errorf("invalid OIDC token: %w", err)
    }

    // Extract subject from verified token
    var claims struct {
        Subject string `json:"sub"`
        Email   string `json:"email"`
    }
    if err := idToken.Claims(&claims); err != nil {
        return nil, nil, fmt.Errorf("failed to extract OIDC claims: %w", err)
    }
    if claims.Subject == "" {
        return nil, nil, errors.New("OIDC token missing subject claim")
    }

    // 2. Generate ephemeral ECDSA P-256 key pair (used only for this signing session)
    privKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
    if err != nil {
        return nil, nil, fmt.Errorf("failed to generate ephemeral key pair: %w", err)
    }

    // 3. Initialize Fulcio client and submit certificate request
    fulcioClient, err := fulcioclient.New(fulcioURL)
    if err != nil {
        return nil, nil, fmt.Errorf("failed to initialize Fulcio client: %w", err)
    }

    // Prepare certificate request with OIDC identity and public key
    req := fulcioclient.CertificateRequest{
        PublicKey: &privKey.PublicKey,
        OIDCSession: fulcioclient.OIDCSession{
            Token: cred.Token,
            Issuer: cred.IssuerURL,
        },
    }

    // Submit request to Fulcio, with 10s timeout
    reqCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
    defer cancel()
    resp, err := fulcioClient.RequestCertificate(reqCtx, req)
    if err != nil {
        return nil, nil, fmt.Errorf("Fulcio certificate request failed: %w", err)
    }

    // 4. Parse and validate returned certificate
    certDER := resp.Certificate
    cert, err := x509.ParseCertificate(certDER)
    if err != nil {
        return nil, nil, fmt.Errorf("failed to parse Fulcio certificate: %w", err)
    }

    // Validate certificate lifetime (max 20 minutes per Sigstore policy)
    if cert.NotAfter.Sub(cert.NotBefore) > 20*time.Minute {
        return nil, nil, errors.New("Fulcio issued certificate with lifetime exceeding 20 minute maximum")
    }

    // Validate certificate contains OIDC subject in SAN (Subject Alternative Name)
    foundSAN := false
    for _, san := range cert.Extensions {
        if san.Id.Equal(oidc.OIDCEmailSANOID) || san.Id.Equal(oidc.OIDCSubjectSANOID) {
            foundSAN = true
            break
        }
    }
    if !foundSAN {
        return nil, nil, errors.New("Fulcio certificate missing OIDC identity SAN")
    }

    return cert, privKey, nil
}

// rekor_client.go: Logic for submitting signing events to Rekor transparency log
// Part of Sigstore client (https://github.com/sigstore/sigstore)
package sigstore

import (
    "context"
    "crypto"
    "encoding/json"
    "fmt"
    "time"

    "github.com/sigstore/rekor/pkg/client"
    "github.com/sigstore/rekor/pkg/types"
    "github.com/sigstore/rekor/pkg/types/hashedrekord"
    "github.com/sigstore/sigstore/pkg/signature"
)

// RekorEntryMetadata holds metadata returned after submitting a signing event to Rekor
type RekorEntryMetadata struct {
    UUID        string    // Unique entry UUID in Rekor
    LogIndex    int64     // Sequential index in the transparency log
    IntegratedAt time.Time // Time the entry was integrated into the log
    Signature   []byte    // The artifact signature included in the entry
}

// SubmitToRekor submits a signed artifact entry to the Rekor transparency log
// Inputs: artifact hash, signature, signing certificate, Rekor server URL
// Returns metadata for the created Rekor entry
func SubmitToRekor(ctx context.Context, artifactHash crypto.Hash, sig []byte, cert *x509.Certificate, rekorURL string) (*RekorEntryMetadata, error) {
    // 1. Initialize Rekor client with timeout
    rekorClient, err := client.GetRekorClient(rekorURL)
    if err != nil {
        return nil, fmt.Errorf("failed to initialize Rekor client: %w", err)
    }

    // 2. Prepare hashedrekord entry (standard Rekor type for hashed artifact signatures)
    // This entry includes the artifact hash, signature, and signing certificate
    entry := &hashedrekord.Entry{
        HashedRekordObj: hashedrekord.V001Schema{
            Data: hashedrekord.Data{
                Hash: hashedrekord.Hash{
                    Algorithm: artifactHash.String(),
                    Value:     fmt.Sprintf("%x", artifactHash.Sum(nil)), // Hex-encoded hash
                },
            },
            Signature: hashedrekord.Signature{
                Content: sig,
                PublicKey: hashedrekord.PublicKey{
                    Content: cert.Raw, // Embed the Fulcio-issued certificate as the public key
                },
            },
        },
    }

    // 3. Validate entry before submission
    if err := entry.Validate(); err != nil {
        return nil, fmt.Errorf("invalid Rekor entry: %w", err)
    }

    // 4. Submit entry to Rekor with 15s timeout
    submitCtx, cancel := context.WithTimeout(ctx, 15*time.Second)
    defer cancel()
    resp, err := rekorClient.CreateLogEntry(submitCtx, types.Entry(entry))
    if err != nil {
        return nil, fmt.Errorf("failed to submit entry to Rekor: %w", err)
    }

    // 5. Parse response and extract metadata
    if len(resp) == 0 {
        return nil, errors.New("Rekor returned empty response for log entry submission")
    }

    // Rekor returns a map of UUID to entry, extract the first entry
    var uuid string
    var entryResp *types.LogEntryAnon
    for uuid, entryResp = range resp {
        break
    }

    // Parse integrated time
    integratedAt := time.Unix(entryResp.IntegratedTime, 0)

    // Extract signature from response to confirm
    sigBytes, err := json.Marshal(entryResp.Body.(*hashedrekord.Entry).HashedRekordObj.Signature.Content)
    if err != nil {
        return nil, fmt.Errorf("failed to extract signature from Rekor response: %w", err)
    }

    return &RekorEntryMetadata{
        UUID:        uuid,
        LogIndex:    entryResp.LogIndex,
        IntegratedAt: integratedAt,
        Signature:   sigBytes,
    }, nil
}

// verifier.go: Logic for verifying Sigstore 2 keyless signatures
// Part of Sigstore client (https://github.com/sigstore/sigstore)
package sigstore

import (
    "context"
    "crypto"
    "crypto/x509"
    "encoding/hex"
    "errors"
    "fmt"
    "time"

    "github.com/sigstore/rekor/pkg/client"
    "github.com/sigstore/rekor/pkg/verify"
    "github.com/sigstore/sigstore/pkg/tuf"
)

// VerificationOptions holds configuration for signature verification
type VerificationOptions struct {
    ExpectedOIDSubject string // Expected OIDC subject (e.g., "repo:octocat/hello-world:ref:refs/heads/main")
    RekorURL           string // Rekor server URL
    FulcioRootCert     *x509.Certificate // Fulcio's root CA certificate
    MaxCertAge         time.Duration // Maximum allowed age of signing certificate (default 20m)
}

// VerifySignature verifies a Sigstore keyless signature for an artifact
// Inputs: artifact hash, signature, Rekor entry UUID, options
// Returns nil if verification succeeds, error otherwise
func VerifySignature(ctx context.Context, artifactHash crypto.Hash, sig []byte, rekorUUID string, opts *VerificationOptions) error {
    // 1. Initialize Rekor client and fetch the log entry
    rekorClient, err := client.GetRekorClient(opts.RekorURL)
    if err != nil {
        return fmt.Errorf("failed to initialize Rekor client: %w", err)
    }

    fetchCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
    defer cancel()
    entry, err := rekorClient.GetLogEntryByUUID(fetchCtx, rekorUUID)
    if err != nil {
        return fmt.Errorf("failed to fetch Rekor entry %s: %w", rekorUUID, err)
    }

    // 2. Validate the Rekor entry is present in the log (inclusion proof)
    verifier, err := verify.NewVerifier(rekorClient)
    if err != nil {
        return fmt.Errorf("failed to initialize Rekor verifier: %w", err)
    }
    if err := verifier.VerifyLogEntry(entry); err != nil {
        return fmt.Errorf("invalid Rekor log entry: %w", err)
    }

    // 3. Extract signing certificate from Rekor entry
    hashedEntry, ok := entry.Body.(*hashedrekord.Entry)
    if !ok {
        return errors.New("Rekor entry is not a hashedrekord type")
    }
    certBytes := hashedEntry.HashedRekordObj.Signature.PublicKey.Content
    cert, err := x509.ParseCertificate(certBytes)
    if err != nil {
        return fmt.Errorf("failed to parse signing certificate: %w", err)
    }

    // 4. Validate certificate against Fulcio root CA
    roots := x509.NewCertPool()
    roots.AddCert(opts.FulcioRootCert)
    intermediates := x509.NewCertPool()
    // Fulcio uses intermediate CAs, add if present (omitted for brevity in example)
    optsCert := x509.VerifyOptions{
        Roots:         roots,
        Intermediates: intermediates,
        KeyUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageCodeSigning},
    }
    if _, err := cert.Verify(optsCert); err != nil {
        return fmt.Errorf("certificate verification failed against Fulcio root: %w", err)
    }

    // 5. Validate certificate lifetime and OIDC subject
    maxAge := opts.MaxCertAge
    if maxAge == 0 {
        maxAge = 20 * time.Minute
    }
    if time.Since(cert.NotBefore) > maxAge {
        return fmt.Errorf("signing certificate is older than maximum allowed age %v", maxAge)
    }

    // Extract OIDC subject from certificate SAN
    oidcSubject, err := extractOIDCSubjectFromCert(cert)
    if err != nil {
        return fmt.Errorf("failed to extract OIDC subject from certificate: %w", err)
    }
    if oidcSubject != opts.ExpectedOIDSubject {
        return fmt.Errorf("unexpected OIDC subject: got %q, want %q", oidcSubject, opts.ExpectedOIDSubject)
    }

    // 6. Validate the signature matches the artifact hash
    pubKey, ok := cert.PublicKey.(*ecdsa.PublicKey)
    if !ok {
        return errors.New("signing certificate does not contain ECDSA public key")
    }
    sigHash := crypto.SHA256.New()
    sigHash.Write(artifactHash.Sum(nil))
    hashSum := sigHash.Sum(nil)
    if !ecdsa.VerifyASN1(pubKey, hashSum, sig) {
        return errors.New("signature does not match artifact hash")
    }

    return nil
}

// extractOIDCSubjectFromCert extracts the OIDC subject from a Fulcio-issued certificate's SAN
func extractOIDCSubjectFromCert(cert *x509.Certificate) (string, error) {
    // Fulcio embeds OIDC subject in the Subject Alternative Name extension with OID 1.3.6.1.4.1.57264.1.1
    oidcSubjectOID := asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 57264, 1, 1}
    for _, ext := range cert.Extensions {
        if ext.Id.Equal(oidcSubjectOID) {
            return string(ext.Value), nil
        }
    }
    return "", errors.New("certificate missing OIDC subject SAN extension")
}

# GitHub Actions step for keyless Cosign signing
- name: Install Cosign
  uses: sigstore/cosign-installer@v3.3.0
  with:
    cosign-release: 'v2.2.0' # Pin to specific version for reproducibility

- name: Keyless sign container image
  run: |
    cosign sign --keyless \
      --oidc-provider=github \
      --oidc-client-id=sigstore \
      --oidc-issuer=https://token.actions.githubusercontent.com \
      ghcr.io/${{ github.repository }}/app:${{ github.sha }}
  env:
    COSIGN_EXPERIMENTAL: 1 # Enable keyless signing (required for Cosign < v2.3.0)

# Kyverno policy for Sigstore keyless signature verification
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: verify-sigstore-signatures
spec:
  validationFailureAction: Enforce
  rules:
  - name: check-container-signatures
    match:
      resources:
        kinds:
        - Pod
    verifyImages:
    - image: "ghcr.io/*/*:*" # Match all images in GitHub Container Registry
      keyless:
        issuer: "https://token.actions.githubusercontent.com" # GitHub OIDC issuer
        subject: "repo:my-org/*:ref:refs/heads/main" # Only allow signs from main branch of org repos
        rekor:
          url: "https://rekor.sigstore.dev" # Rekor public instance
      attestations: []

# Sigstore Policy Controller configuration for Rekor monitoring
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: monitor-project-signatures
spec:
  authorities:
  - keyless:
      issuer: "https://token.actions.githubusercontent.com"
      subject: "repo:my-org/my-project:*"
  sources:
  - rekor:
      url: "https://rekor.sigstore.dev"
  alerting:
    slack:
      webhookURL: "https://hooks.slack.com/services/your/webhook/url"
      channel: "#security-alerts"