Files

master 6e687b523a fix tests. new product advisories enhancements

2026-01-25 19:11:36 +02:00

4.1 KiB

Raw Blame History

Stella TUF Trust Repository Template

This directory contains a template for creating a TUF (The Update Framework) repository for distributing trust anchors to StellaOps clients.

WARNING

The sample keys in this template are for DEMONSTRATION ONLY. DO NOT USE THESE KEYS IN PRODUCTION.

Generate new keys using the scripts/init-tuf-repo.sh script before deploying.

Directory Structure

stella-trust/
├── root.json           # Root metadata (rotates rarely, high ceremony)
├── snapshot.json       # Current target versions
├── timestamp.json      # Freshness indicator (rotates frequently)
├── targets.json        # Target file metadata
└── targets/
    ├── rekor-key-v1.pub              # Rekor log public key
    ├── fulcio-chain.pem              # Fulcio certificate chain
    └── sigstore-services-v1.json     # Service endpoint map

Quick Start

1. Initialize a New Repository

# Generate new signing keys (do this in a secure environment)
./scripts/init-tuf-repo.sh /path/to/new-repo

# This creates:
# - Root key (keep offline, backup securely)
# - Snapshot key
# - Timestamp key
# - Targets key
# - Initial metadata files

2. Add a Target

# Add Rekor public key as a target
./scripts/add-target.sh /path/to/rekor-key.pub rekor-key-v1

# Add service map
./scripts/add-target.sh /path/to/sigstore-services.json sigstore-services-v1

3. Publish Updates

# Update timestamp (do this regularly, e.g., daily)
./scripts/update-timestamp.sh

# The timestamp.json should be refreshed frequently to maintain client trust

4. Deploy

Host the repository contents on a web server:

HTTPS required for production
Set appropriate cache headers (short TTL for timestamp.json)
Consider CDN for global distribution

Key Management

Key Hierarchy

Root Key (offline, high ceremony)
├── Snapshot Key (can be online)
├── Timestamp Key (must be online for automation)
└── Targets Key (can be online)

Security Recommendations

Root Key: Store offline in HSM or air-gapped system. Only use for:
- Initial repository creation
- Root key rotation (rare)
- Emergency recovery
Snapshot/Targets Keys: Can be stored in secure KMS for automation.
Timestamp Key: Must be accessible for automated updates. Use short-lived credentials and rotate regularly.

Key Rotation

See docs/operations/key-rotation-runbook.md for detailed procedures.

Quick rotation example:

# Add new key while keeping old one active
./scripts/rotate-key.sh targets --add-key /path/to/new-key.pub

# After grace period (clients have updated), remove old key
./scripts/rotate-key.sh targets --remove-key old-key-id

Client Configuration

Configure StellaOps clients to use your TUF repository:

attestor:
  trust_repo:
    enabled: true
    tuf_url: https://trust.yourcompany.com/tuf/
    service_map_target: sigstore-services-v1
    rekor_key_targets:
      - rekor-key-v1

Or via CLI:

stella trust init \
  --tuf-url https://trust.yourcompany.com/tuf/ \
  --service-map sigstore-services-v1 \
  --pin rekor-key-v1

Metadata Expiration

Default expiration times (configurable in init script):

root.json: 365 days
snapshot.json: 7 days
timestamp.json: 1 day
targets.json: 30 days

Clients will refuse to use metadata past its expiration. Ensure automated timestamp updates are running.

Troubleshooting

Client reports "metadata expired"

The timestamp.json hasn't been updated. Run:

./scripts/update-timestamp.sh

Client reports "signature verification failed"

Keys may have rotated without client update. Client should run:

stella trust sync --force

Client reports "unknown target"

Target hasn't been added to repository. Add it:

./scripts/add-target.sh /path/to/target target-name

4.1 KiB Raw Blame History