archy/docs/adr/005-chacha20-backup-encryption.md

# ADR-005: ChaCha20-Poly1305 for Backup Encryption

**Status**: Accepted
**Date**: 2026-03

## Context

Backups contain sensitive data (keys, credentials, app state) and must be encrypted at rest. Options: AES-256-GCM, ChaCha20-Poly1305, XChaCha20-Poly1305.

## Decision

Use ChaCha20-Poly1305 (AEAD) with Argon2id key derivation for backup encryption.

## Consequences

### Positive
- **Software performance**: ChaCha20 is faster than AES on hardware without AES-NI (common on ARM/SBCs)
- **Constant-time**: No timing side channels, unlike some AES implementations
- **AEAD**: Authenticated encryption ensures both confidentiality and integrity
- **Widely audited**: Used in TLS 1.3, WireGuard, and Signal Protocol
- **Simple implementation**: No padding, no CBC/CTR mode complexity
- **Argon2id KDF**: Memory-hard key derivation resists GPU/ASIC brute force attacks

### Negative
- **96-bit nonce**: Must ensure nonce uniqueness per encryption (random generation with collision check)
- **Not FIPS-certified**: Some enterprise environments require AES (not relevant for personal nodes)
- **Less hardware acceleration**: AES-NI on x86 can make AES faster on desktop CPUs

### Mitigation
- Generate random nonce per backup; store nonce alongside ciphertext
- Argon2id with high memory cost (64MB) and iterations (3) for password-to-key derivation
- Target hardware is mixed x86/ARM; ChaCha20's consistent performance is an advantage
release(v1.7.41-alpha): post-OTA auto-rollback so a bad release cannot strand the fleet Closes failure mode FM5 from docs/bulletproof-containers.md: the v1.7.38 + v1.7.39 rollouts left every affected node on an unreachable UI (nginx 500) with no recovery path short of SSH. This release adds a self-check guardrail to the update flow. What changed: - apply_update() writes a pending-verify marker with old+new version and a 150s deadline immediately before scheduling the service restart. - verify_pending_update() runs from main.rs startup. If the marker is present and within its freshness window, the new binary waits 15s for nginx + backend to settle, then probes https://127.0.0.1/ every 5s for up to 90s (self-signed certs accepted). - On any probe success within the window, the marker is cleared and nothing else happens. - On window-exhaust, the new binary: 1. Moves the broken /opt/archipelago/web-ui to web-ui.failed.<ts> (quarantined, not deleted, so we can post-mortem). 2. Restores web-ui.bak on top of web-ui. 3. Calls rollback_update() to restore the previous binary. 4. Updates state.current_version to reflect the rollback. 5. systemctl --no-block restart archipelago so the OLD binary boots. - Markers older than 10 minutes are treated as stale and cleared without probing, so a crashed-during-startup marker from weeks ago cannot spontaneously roll back a healthy node on a later reboot. - rollback_update() binary copy now goes through host_sudo instead of tokio::fs::copy, so it escapes the service's ProtectSystem=strict mount namespace. Without this, the rollback silently failed with EROFS on /usr/local/bin and orphaned the rollback - the exact opposite of what auto-rollback is for. Tests: 4 new unit tests in update::tests covering marker round-trip, absent-marker noop, no-panic on verify_pending_update with nothing to verify, and an invariant assert that the 90s probe window stays below the 600s stale threshold. All passing. Side fix: scripts/create-release-manifest.sh was dying with exit 141 (SIGPIPE from tar tvzf pipe head pipe awk) under set -euo pipefail. Replaced with a single awk NR==1 that doesn't short-circuit the upstream pipe, so the release-build flow is idempotent again. 2026-04-22 16:14:35 -04:00			`# ADR-005: ChaCha20-Poly1305 for Backup Encryption`

			`Status: Accepted`
			`Date: 2026-03`

			`## Context`

			`Backups contain sensitive data (keys, credentials, app state) and must be encrypted at rest. Options: AES-256-GCM, ChaCha20-Poly1305, XChaCha20-Poly1305.`

			`## Decision`

			`Use ChaCha20-Poly1305 (AEAD) with Argon2id key derivation for backup encryption.`

			`## Consequences`

			`### Positive`
			`- Software performance: ChaCha20 is faster than AES on hardware without AES-NI (common on ARM/SBCs)`
			`- Constant-time: No timing side channels, unlike some AES implementations`
			`- AEAD: Authenticated encryption ensures both confidentiality and integrity`
			`- Widely audited: Used in TLS 1.3, WireGuard, and Signal Protocol`
			`- Simple implementation: No padding, no CBC/CTR mode complexity`
			`- Argon2id KDF: Memory-hard key derivation resists GPU/ASIC brute force attacks`

			`### Negative`
			`- 96-bit nonce: Must ensure nonce uniqueness per encryption (random generation with collision check)`
			`- Not FIPS-certified: Some enterprise environments require AES (not relevant for personal nodes)`
			`- Less hardware acceleration: AES-NI on x86 can make AES faster on desktop CPUs`

			`### Mitigation`
			`- Generate random nonce per backup; store nonce alongside ciphertext`
			`- Argon2id with high memory cost (64MB) and iterations (3) for password-to-key derivation`
			`- Target hardware is mixed x86/ARM; ChaCha20's consistent performance is an advantage`