9.2 KiB
TUF Integration Guide
This guide explains how StellaOps uses The Update Framework (TUF) for secure trust distribution and how to configure TUF-based trust management.
Overview
TUF provides a secure method for distributing and updating trust anchors (public keys, service endpoints) without requiring client reconfiguration. StellaOps uses TUF to:
- Distribute Rekor public keys for checkpoint verification
- Distribute Fulcio certificate chains for keyless signing
- Provide service endpoint discovery (Rekor, Fulcio URLs)
- Enable secure key rotation with grace periods
- Support offline verification with bundled trust state
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ TUF Trust Hierarchy │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ │
│ │ Root │ ← Offline, rotates rarely (yearly) │
│ │ Key │ │
│ └────┬────┘ │
│ │ │
│ ┌────┴────────────────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Snapshot │ │Timestamp │ │ Targets │ │
│ │ Key │ │ Key │ │ Key │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ snapshot.json timestamp.json targets.json │
│ │ │ │
│ │ ├── rekor-key-v1.pub │
│ │ ├── rekor-key-v2.pub │
│ │ ├── fulcio-chain.pem │
│ │ └── sigstore-services-v1.json │
│ │ │
│ └── Refreshed frequently (daily) │
│ │
└─────────────────────────────────────────────────────────────────┘
TUF Roles
Root
- Signs the root metadata containing all role keys
- Highest trust level, rotates rarely
- Should be kept offline in secure storage (HSM, air-gapped system)
- Used only for initial setup and key rotation ceremonies
Timestamp
- Signs timestamp metadata indicating freshness
- Must be refreshed frequently (default: daily)
- Clients reject metadata older than expiration
- Can be automated with short-lived credentials
Snapshot
- Signs snapshot metadata listing current target versions
- Updated when targets change
- Prevents rollback attacks
Targets
- Signs metadata for actual target files
- Lists hashes and sizes for verification
- Supports delegations for large repositories
Configuration
Attestor Configuration
attestor:
trust_repo:
enabled: true
tuf_url: https://trust.yourcompany.com/tuf/
refresh_interval_minutes: 60
freshness_threshold_days: 7
offline_mode: false
local_cache_path: /var/lib/stellaops/tuf-cache
service_map_target: sigstore-services-v1
rekor_key_targets:
- rekor-key-v1
- rekor-key-v2
Configuration Options
| Option | Description | Default |
|---|---|---|
enabled |
Enable TUF-based trust distribution | false |
tuf_url |
URL to TUF repository root | Required |
refresh_interval_minutes |
How often to check for updates | 60 |
freshness_threshold_days |
Max age before rejecting metadata | 7 |
offline_mode |
Use bundled metadata only | false |
local_cache_path |
Local metadata cache directory | OS-specific |
service_map_target |
TUF target name for service map | sigstore-services-v1 |
rekor_key_targets |
TUF target names for Rekor keys | ["rekor-key-v1"] |
Environment Variables
| Variable | Description |
|---|---|
STELLA_TUF_ROOT_URL |
Override TUF repository URL |
STELLA_SIGSTORE_SERVICE_MAP |
Path to local service map override |
STELLA_TUF_OFFLINE_MODE |
Force offline mode (true/false) |
CLI Usage
Initialize Trust
# Initialize with a TUF repository
stella trust init \
--tuf-url https://trust.yourcompany.com/tuf/ \
--service-map sigstore-services-v1 \
--pin rekor-key-v1 rekor-key-v2
# Initialize in offline mode with bundled metadata
stella trust init \
--tuf-url file:///path/to/bundled-trust/ \
--offline
Sync Metadata
# Refresh TUF metadata
stella trust sync
# Force refresh even if fresh
stella trust sync --force
Check Status
# Show current trust state
stella trust status
# Show with key details
stella trust status --show-keys --show-endpoints
Export for Offline Use
# Export trust state
stella trust export --out ./trust-bundle/
# Create sealed snapshot with tiles
stella trust snapshot export \
--out ./snapshots/2026-01-25.tar.zst \
--depth 10000
Import Offline Bundle
# Import trust bundle
stella trust import ./snapshots/2026-01-25.tar.zst \
--verify-manifest \
--reject-if-stale 7d
Service Map
The service map (sigstore-services-v1.json) contains endpoint URLs for Sigstore
services. This enables endpoint changes without client reconfiguration.
Schema
{
"version": 1,
"rekor": {
"url": "https://rekor.sigstore.dev",
"log_id": "c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d",
"public_key_target": "rekor-key-v1"
},
"fulcio": {
"url": "https://fulcio.sigstore.dev",
"root_cert_target": "fulcio-chain.pem"
},
"overrides": {
"staging": {
"rekor_url": "https://rekor.sigstage.dev"
}
}
}
Site-Local Overrides
Organizations can define environment-specific overrides:
attestor:
trust_repo:
environment: staging # Use staging overrides from service map
Key Rotation
TUF supports secure key rotation with grace periods:
- Add new key: Publish new key while keeping old key active
- Grace period: Clients sync and receive both keys
- Verify: Ensure all clients have new key
- Revoke old key: Remove old key from active set
See Key Rotation Runbook for detailed procedures.
Offline Mode
For air-gapped environments, StellaOps can operate with bundled TUF metadata:
-
Export trust state on connected system:
stella trust snapshot export --out ./bundle.tar.zst -
Transfer bundle to air-gapped system
-
Import on air-gapped system:
stella trust import ./bundle.tar.zst --offline -
Verify attestations using bundled trust:
stella attest verify ./attestation.json --offline
Troubleshooting
"TUF metadata expired"
The timestamp hasn't been refreshed. On the TUF repository:
./scripts/update-timestamp.sh
"Unknown target"
The requested target doesn't exist in the repository:
./scripts/add-target.sh /path/to/target target-name
"Signature verification failed"
Keys may have rotated. Force a sync:
stella trust sync --force
"Service map not found"
Ensure the service map target name matches configuration:
stella trust status # Check service_map_target value
Security Considerations
-
Root Key Security: Keep root key offline. Only use for initial setup and rotations.
-
Timestamp Automation: Automate timestamp updates but use short-lived credentials.
-
Monitoring: Monitor for failed TUF fetches - may indicate MITM or repository issues.
-
Rollback Protection: TUF prevents rollback attacks through version tracking.
-
Freshness: Configure appropriate freshness thresholds for your security requirements.