# 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 ```yaml 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 ```bash # 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 ```bash # Refresh TUF metadata stella trust sync # Force refresh even if fresh stella trust sync --force ``` ### Check Status ```bash # Show current trust state stella trust status # Show with key details stella trust status --show-keys --show-endpoints ``` ### Export for Offline Use ```bash # 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 ```bash # 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 ```json { "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: ```yaml attestor: trust_repo: environment: staging # Use staging overrides from service map ``` ## Key Rotation TUF supports secure key rotation with grace periods: 1. **Add new key**: Publish new key while keeping old key active 2. **Grace period**: Clients sync and receive both keys 3. **Verify**: Ensure all clients have new key 4. **Revoke old key**: Remove old key from active set See [Key Rotation Runbook](../../operations/key-rotation-runbook.md) for detailed procedures. ## Offline Mode For air-gapped environments, StellaOps can operate with bundled TUF metadata: 1. Export trust state on connected system: ```bash stella trust snapshot export --out ./bundle.tar.zst ``` 2. Transfer bundle to air-gapped system 3. Import on air-gapped system: ```bash stella trust import ./bundle.tar.zst --offline ``` 4. Verify attestations using bundled trust: ```bash stella attest verify ./attestation.json --offline ``` ## Troubleshooting ### "TUF metadata expired" The timestamp hasn't been refreshed. On the TUF repository: ```bash ./scripts/update-timestamp.sh ``` ### "Unknown target" The requested target doesn't exist in the repository: ```bash ./scripts/add-target.sh /path/to/target target-name ``` ### "Signature verification failed" Keys may have rotated. Force a sync: ```bash stella trust sync --force ``` ### "Service map not found" Ensure the service map target name matches configuration: ```bash stella trust status # Check service_map_target value ``` ## Security Considerations 1. **Root Key Security**: Keep root key offline. Only use for initial setup and rotations. 2. **Timestamp Automation**: Automate timestamp updates but use short-lived credentials. 3. **Monitoring**: Monitor for failed TUF fetches - may indicate MITM or repository issues. 4. **Rollback Protection**: TUF prevents rollback attacks through version tracking. 5. **Freshness**: Configure appropriate freshness thresholds for your security requirements. ## References - [TUF Specification](https://theupdateframework.github.io/specification/latest/) - [Sigstore Trust Root](https://github.com/sigstore/root-signing) - [StellaOps Trust Repository Template](../../../devops/trust-repo-template/)