163 lines
4.1 KiB
Markdown
163 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. **Root Key**: Store offline in HSM or air-gapped system. Only use for:
|
|
- Initial repository creation
|
|
- Root key rotation (rare)
|
|
- Emergency recovery
|
|
|
|
2. **Snapshot/Targets Keys**: Can be stored in secure KMS for automation.
|
|
|
|
3. **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:
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
./scripts/update-timestamp.sh
|
|
```
|
|
|
|
### Client reports "signature verification failed"
|
|
Keys may have rotated without client update. Client should run:
|
|
```bash
|
|
stella trust sync --force
|
|
```
|
|
|
|
### Client reports "unknown target"
|
|
Target hasn't been added to repository. Add it:
|
|
```bash
|
|
./scripts/add-target.sh /path/to/target target-name
|
|
```
|
|
|
|
## References
|
|
|
|
- [TUF Specification](https://theupdateframework.github.io/specification/latest/)
|
|
- [StellaOps Trust Documentation](docs/modules/attestor/tuf-integration.md)
|
|
- [Key Rotation Runbook](docs/operations/key-rotation-runbook.md)
|