288 lines
9.2 KiB
Markdown
288 lines
9.2 KiB
Markdown
# 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/)
|