# Sigstore Documentation

Sigstore is an open source project for improving software supply chain security. The Sigstore framework and tooling empowers software developers and consumers to securely sign and verify software artifacts such as release files, container images, binaries, software bills of materials (SBOMs), and more. Signatures are generated with ephemeral signing keys so there's no need to manage keys. Signing events are recorded in a tamper-resistant public log so software developers can audit signing events.

The project is backed by the Open Source Security Foundation (OpenSSF) under the Linux Foundation. Sigstore addresses traditional signing weaknesses around identity verification, key management, and key revocation by using identity-based signing with OpenID Connect (OIDC) authentication, short-lived certificates from Fulcio (certificate authority), and transparent logging via Rekor (transparency log). This eliminates the need for long-lived cryptographic keys while providing cryptographic proof of artifact authenticity.

## Installing Cosign

Install the Cosign CLI tool to sign and verify artifacts with Sigstore.

```bash
# Install with Go 1.20+
go install github.com/sigstore/cosign/v3/cmd/cosign@latest

# Install with Homebrew
brew install cosign

# Install on Arch Linux
pacman -S cosign

# Install on Alpine Linux
apk add cosign

# Install with binary download (Linux amd64)
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64"
sudo mv cosign-linux-amd64 /usr/local/bin/cosign
sudo chmod +x /usr/local/bin/cosign

# Install with rpm
LATEST_VERSION=$(curl https://api.github.com/repos/sigstore/cosign/releases/latest | grep tag_name | cut -d : -f2 | tr -d "v\", ")
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-${LATEST_VERSION}-1.x86_64.rpm"
sudo rpm -ivh cosign-${LATEST_VERSION}-1.x86_64.rpm

# Install with dpkg
LATEST_VERSION=$(curl https://api.github.com/repos/sigstore/cosign/releases/latest | grep tag_name | cut -d : -f2 | tr -d "v\", ")
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign_${LATEST_VERSION}_amd64.deb"
sudo dpkg -i cosign_${LATEST_VERSION}_amd64.deb
```

## Signing Blobs (Keyless)

Sign files and blobs using identity-based keyless signing with OpenID Connect authentication.

```bash
# Sign a blob with keyless signing (recommended)
# This opens a browser for OIDC authentication (Google, GitHub, or Microsoft)
cosign sign-blob myfile.txt --bundle artifact.sigstore.json

# The bundle contains signature, certificate, and proof of transparency log inclusion
# Output:
# Generating ephemeral keys...
# Retrieving signed certificate...
# Your browser will now be opened to:
# https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&...
# Successfully verified SCT...
# tlog entry created with index: 965333

# Sign with separate output files (legacy, not recommended)
cosign sign-blob README.md --output-certificate cert.pem --output-signature sig

# Sign with a local key instead of keyless
cosign sign-blob --key cosign.key --bundle artifact.sigstore.json README.md

# Non-interactive signing for CI/CD pipelines
cosign sign-blob --yes --key cosign.key --bundle artifact.sigstore.json myfile.txt
```

## Verifying Blob Signatures

Verify signatures on blobs using identity-based verification or public keys.

```bash
# Verify a blob with keyless signing (using bundle)
cosign verify-blob file.txt --bundle artifact.sigstore.json \
  --certificate-identity=name@example.com \
  --certificate-oidc-issuer=https://accounts.google.com

# OIDC issuers:
# - Google: https://accounts.google.com
# - GitHub: https://github.com/login/oauth
# - Microsoft: https://login.microsoftonline.com
# - GitLab: https://gitlab.com

# Verify with a public key
cosign verify-blob file.txt --key cosign.pub --bundle artifact.sigstore.json

# Verify with regex patterns for identity matching
cosign verify-blob file.txt --bundle artifact.sigstore.json \
  --certificate-identity-regexp=".*@example.com" \
  --certificate-oidc-issuer-regexp="https://accounts.*"
```

## Signing Container Images

Sign container images stored in OCI registries with keyless or key-based signing.

```bash
# Keyless signing of a container image
cosign sign $IMAGE_URI_DIGEST

# Sign with annotations
cosign sign -a foo=bar -a environment=production $IMAGE

# Sign with a local key pair
cosign sign --key cosign.key $IMAGE

# Sign with certificate and chain
cosign sign --certificate cosign.crt --certificate-chain chain.crt $IMAGE

# Sign with KMS-managed keys
cosign sign --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] $IMAGE
cosign sign --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY]/versions/[VERSION] $IMAGE
cosign sign --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] $IMAGE
cosign sign --key hashivault://[KEY] $IMAGE
cosign sign --key k8s://[NAMESPACE]/[KEY] $IMAGE

# Sign but skip upload (store signature locally)
cosign sign --upload=false --output-signature demo.sig --output-certificate demo.crt $IMAGE

# Example workflow with ttl.sh (free ephemeral registry)
SRC_IMAGE=busybox
SRC_DIGEST=$(crane digest busybox)
IMAGE_URI=ttl.sh/$(uuidgen | head -c 8 | tr 'A-Z' 'a-z')
crane cp $SRC_IMAGE@$SRC_DIGEST $IMAGE_URI:1h
IMAGE_URI_DIGEST=$IMAGE_URI@$SRC_DIGEST
cosign sign $IMAGE_URI_DIGEST
```

## Verifying Container Images

Verify signatures on container images using identity or key-based verification.

```bash
# Keyless verification with identity
cosign verify $IMAGE \
  --certificate-identity=name@example.com \
  --certificate-oidc-issuer=https://accounts.google.com

# Verify with regex patterns
cosign verify $IMAGE_URI_DIGEST \
  --certificate-identity-regexp=.* \
  --certificate-oidc-issuer-regexp=.*

# Verify with a public key
cosign verify --key cosign.pub user/demo

# Verify multiple images
cosign verify user-0/demo-0 user-1/demo-1

# Verify with local certificate and chain
cosign verify --certificate cosign.crt --certificate-chain chain.crt \
  --certificate-oidc-issuer https://issuer.example.com \
  --certificate-identity foo@example.com user/demo

# Verify annotations
cosign verify -a sig=original --key cosign.pub user/demo

# Verify with KMS key
cosign verify --key gcpkms://projects/[PROJECT]/locations/[LOCATION]/keyRings/[KEYRING]/cryptoKeys/[KEY] $IMAGE

# Download signatures for external verification
cosign download signature us-central1-docker.pkg.dev/user/test/taskrun
# Output: {"Base64Signature":"...","Payload":"..."}
```

## Creating and Verifying Attestations

Create and verify in-toto attestations with policy validation using CUE or Rego.

```bash
# Create an attestation with a predicate file
cosign attest --predicate predicate.json --key cosign.key $IMAGE

# Keyless attestation
cosign attest --predicate predicate.json $IMAGE

# Verify attestation
cosign verify-attestation --key cosign.pub $IMAGE

# Verify attestation with keyless
cosign verify-attestation $IMAGE \
  --certificate-identity=name@example.com \
  --certificate-oidc-issuer=https://accounts.google.com

# Verify attestation with CUE policy
cat > policy.cue << 'EOF'
import "time"

before: time.Parse(time.RFC3339, "2025-10-09T17:10:27Z")
predicateType: "https://cosign.sigstore.dev/attestation/v1"
predicate: {
    Timestamp: <before
}
EOF

cosign verify-attestation --policy policy.cue --key cosign.pub $IMAGE

# Verify attestation with Rego policy
cat > policy.rego << 'EOF'
package signature

allow[msg] {
    input.predicateType == "https://cosign.sigstore.dev/attestation/v1"
    input.predicate.Data == "expected_value"
    msg := "attestation validated"
}
EOF

cosign verify-attestation --policy policy.rego --key cosign.pub $IMAGE
```

## Key Management

Generate, import, and manage signing keys with various backends.

```bash
# Generate a new key pair
cosign generate-key-pair

# Generate keys in KMS
cosign generate-key-pair --kms awskms://[ENDPOINT]/[ID/ALIAS/ARN]
cosign generate-key-pair --kms gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY]
cosign generate-key-pair --kms azurekms://[VAULT_NAME][VAULT_URI]/[KEY]
cosign generate-key-pair --kms hashivault://[KEY]

# Import an existing key pair
cosign import-key-pair --key private.pem

# Export public key from private key
cosign public-key --key cosign.key
# Output:
# -----BEGIN PUBLIC KEY-----
# MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
# -----END PUBLIC KEY-----

# Export public key from KMS
cosign public-key --key gcpkms://projects/[PROJECT]/locations/[LOCATION]/keyRings/[KEYRING]/cryptoKeys/[KEY]

# Use key from environment variable
export COSIGN_PRIVATE_KEY=$(cat cosign.key)
cosign sign --key env://COSIGN_PRIVATE_KEY $IMAGE
```

## Gitsign - Signing Git Commits

Sign Git commits with keyless Sigstore using OpenID Connect authentication.

```bash
# Install Gitsign
go install github.com/sigstore/gitsign@latest
# Or with Homebrew
brew tap sigstore/tap
brew install gitsign

# Configure Git for a single repository
cd /path/to/my/repository
git config --local commit.gpgsign true
git config --local tag.gpgsign true
git config --local gpg.x509.program gitsign
git config --local gpg.format x509

# Configure Git globally
git config --global commit.gpgsign true
git config --global tag.gpgsign true
git config --global gpg.x509.program gitsign
git config --global gpg.format x509

# Sign a commit (opens browser for OIDC auth)
git commit --message="Signed commit"
# Output:
# Your browser will now be opened to:
# https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&...
# [main 040b9af] Signed commit

# Verify a signed commit
git verify-commit HEAD
# Output:
# tlog index: 2801760
# gitsign: Signature made using certificate ID 0xf805288664f2e851dcb34e6a03b1a5232eb574ae
# gitsign: Good signature from [user@example.com]
# Validated Git signature: true
# Validated Rekor entry: true

# Sign and verify tags
git tag -s v0.0.1
git verify-tag v0.0.1

# Configure custom Sigstore instance
git config --local gitsign.fulcio https://fulcio.example.com
git config --local gitsign.rekor https://rekor.example.com
git config --local gitsign.connectorID https://accounts.google.com
```

## Kubernetes Policy Controller

Deploy and configure the policy-controller to enforce image signature policies in Kubernetes.

```yaml
# Enable policy enforcement on a namespace
# kubectl label namespace my-secure-namespace policy.sigstore.dev/include=true

# ClusterImagePolicy with keyless verification
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: keyless-image-policy
spec:
  images:
  - glob: "ghcr.io/myorg/**"
  authorities:
  - keyless:
      identities:
      - issuer: https://accounts.google.com
        subject: signer@example.com
      - issuer: https://token.actions.githubusercontent.com
        subjectRegExp: https://github.com/myorg/*/.github/workflows/*@*

---
# ClusterImagePolicy with key-based verification
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: key-image-policy
spec:
  images:
  - glob: "gcr.io/myproject/**"
  authorities:
  - key:
      data: |
        -----BEGIN PUBLIC KEY-----
        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
        -----END PUBLIC KEY-----

---
# ClusterImagePolicy with attestation validation
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: attestation-policy
spec:
  images:
  - glob: "registry.example.com/**"
  authorities:
  - name: verify-attestation
    keyless:
      identities:
      - issuer: https://accounts.google.com
        subject: builder@example.com
    attestations:
    - name: provenance
      predicateType: https://slsa.dev/provenance/v1
      policy:
        type: cue
        data: |
          predicateType: "https://slsa.dev/provenance/v1"

---
# TrustRoot for custom Sigstore instance
apiVersion: policy.sigstore.dev/v1alpha1
kind: TrustRoot
metadata:
  name: my-sigstore
spec:
  sigstoreKeys:
    certificateAuthorities:
    - subject:
        organization: my-org
        commonName: fulcio
      uri: https://fulcio.example.com
      certChain: |-
        BASE64_ENCODED_CERT_CHAIN
    tLogs:
    - baseURL: https://rekor.example.com
      hashAlgorithm: sha-256
      publicKey: |-
        BASE64_ENCODED_PUBLIC_KEY

---
# Static policy to allow specific images without signatures
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: allow-gcr-images
spec:
  images:
  - glob: "gcr.io/distroless/**"
  authorities:
  - static:
      action: pass

---
# Warn mode policy (allows but warns on policy failures)
apiVersion: policy.sigstore.dev/v1alpha1
kind: ClusterImagePolicy
metadata:
  name: warn-unsigned
spec:
  mode: warn
  images:
  - glob: "**"
  authorities:
  - keyless:
      identities:
      - issuer: https://accounts.google.com
        subjectRegExp: ".*@example.com"
```

## GitHub Actions Integration

Use Cosign in CI/CD pipelines for automated signing and verification.

```yaml
# .github/workflows/sign-and-push.yml
name: Sign and Push Container Image

on:
  push:
    branches: [main]

jobs:
  build-sign-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write  # Required for keyless signing

    steps:
    - uses: actions/checkout@v4

    - name: Install Cosign
      uses: sigstore/cosign-installer@main
      with:
        cosign-release: "v2.2.0"  # optional, defaults to latest

    - name: Login to GHCR
      uses: docker/login-action@v3
      with:
        registry: ghcr.io
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}

    - name: Build and Push
      uses: docker/build-push-action@v5
      with:
        push: true
        tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

    - name: Sign Container Image (Keyless)
      env:
        COSIGN_EXPERIMENTAL: "true"
      run: |
        cosign sign --yes ghcr.io/${{ github.repository }}@${{ steps.build.outputs.digest }}

    - name: Verify Signature
      run: |
        cosign verify ghcr.io/${{ github.repository }}@${{ steps.build.outputs.digest }} \
          --certificate-identity-regexp="https://github.com/${{ github.repository }}/*" \
          --certificate-oidc-issuer=https://token.actions.githubusercontent.com
```

## Language Client Libraries

Sigstore provides language-specific client libraries for integration into applications.

```bash
# Go - sigstore-go (currently in beta)
go get github.com/sigstore/sigstore-go

# Python - sigstore-python
pip install sigstore

# JavaScript/TypeScript - sigstore-js
npm install sigstore

# Java - sigstore-java
# Add to pom.xml:
# <dependency>
#   <groupId>dev.sigstore</groupId>
#   <artifactId>sigstore-java</artifactId>
#   <version>LATEST</version>
# </dependency>

# Ruby - sigstore-ruby
gem install sigstore

# Rust - sigstore-rs
# Add to Cargo.toml:
# [dependencies]
# sigstore = "LATEST"
```

```python
# Python example - sign and verify
from sigstore.sign import SigningContext
from sigstore.verify import Verifier, VerificationMaterials
from sigstore.oidc import detect_credential

# Sign an artifact
artifact_path = "myartifact.tar.gz"
with open(artifact_path, "rb") as f:
    artifact_contents = f.read()

signing_ctx = SigningContext.production()
with signing_ctx.signer(detect_credential()) as signer:
    result = signer.sign(artifact_contents)

# Verify an artifact
verifier = Verifier.production()
materials = VerificationMaterials.from_bundle(bundle_path)
verifier.verify(artifact_contents, materials, policy)
```

## Rekor Transparency Log

Query and interact with the Rekor transparency log for audit and verification.

```bash
# Install Rekor CLI
go install github.com/sigstore/rekor/cmd/rekor-cli@latest

# Search for entries by email
rekor-cli search --email user@example.com

# Search by public key
rekor-cli search --public-key cosign.pub

# Search by artifact hash
rekor-cli search --sha sha256:abc123...

# Get a specific log entry
rekor-cli get --uuid 24296fb24b8ad77a...

# Get log info
rekor-cli loginfo

# Verify inclusion proof
rekor-cli verify --artifact myfile.txt --signature sig --public-key cosign.pub

# Upload an entry manually
rekor-cli upload --artifact myfile.txt --signature sig --public-key cosign.pub

# Public Rekor instance
# https://rekor.sigstore.dev
# API: https://rekor.sigstore.dev/api/v1/log/entries
```

## Summary

Sigstore provides a comprehensive solution for software supply chain security through identity-based signing and verification. The primary use cases include signing container images in CI/CD pipelines with keyless authentication, verifying artifact integrity before deployment using Kubernetes policy-controller, signing Git commits with Gitsign for code provenance, and creating attestations for SLSA compliance. Integration is straightforward through the Cosign CLI, GitHub Actions, or language-specific client libraries.

For production deployments, organizations typically combine keyless signing in CI pipelines with policy-controller enforcement in Kubernetes clusters. The transparency log (Rekor) provides an immutable audit trail of all signing events, while the certificate authority (Fulcio) eliminates key management complexity by issuing short-lived certificates bound to verified identities. This architecture enables zero-trust verification where consumers can independently verify artifact authenticity without prior key exchange with producers.