Encryption Model

┌────────┬────────────┬──────────────┬────────────┐
│ Version│   Nonce    │  Ciphertext  │  GCM Tag   │
│ 1 byte │  12 bytes  │   Variable   │  16 bytes  │
└────────┴────────────┴──────────────┴────────────┘

Total overhead: 29 bytes per object

// Generate random nonce
nonce := make([]byte, 12)
rand.Read(nonce)

// Encrypt with AES-256-GCM
gcm := cipher.NewGCM(aes.NewCipher(encryptionKey))
ciphertext := gcm.Seal(nil, nonce, plaintext, nil)

// Assemble: version || nonce || ciphertext
out := []byte{0x01}
out = append(out, nonce...)
out = append(out, ciphertext...)  // includes 16-byte tag

// Parse format
version := data[0]
if version != 0x01 {
    return nil, ErrInvalidCiphertext
}
nonce := data[1:13]
sealed := data[13:]

// Decrypt and verify tag
gcm := cipher.NewGCM(aes.NewCipher(encryptionKey))
plaintext, err := gcm.Open(nil, nonce, sealed, nil)
if err != nil {
    return nil, ErrDecryptFailed  // wrong key or tampered data
}

Platform Key / Password / Recovery Key
         ↓ (wraps)
    Master Key (256-bit, per tenant)
         ↓ HKDF-SHA256(info="cloudstic-backup-v1")
    Encryption Key (256-bit for AES-256-GCM)
         ↓ HKDF-SHA256(info="cloudstic-dedup-mac-v1")
    Dedup HMAC Key (256-bit for chunk addressing)

encryptionKey := HKDF-SHA256(
    secret = masterKey,
    salt   = nil,
    info   = "cloudstic-backup-v1",
    length = 32,
)

dedupKey := HKDF-SHA256(
    secret = encryptionKey,
    salt   = nil,
    info   = "cloudstic-dedup-mac-v1",
    length = 32,
)

{
  "slot_type": "password",
  "wrapped_key": "AaQxMjM0NTY3ODkwYWJjZGVm...",
  "label": "default",
  "kdf_params": {
    "algorithm": "argon2id",
    "salt": "cmFuZG9tc2FsdA==",
    "time": 3,
    "memory": 65536,
    "threads": 4
  }
}

nonce (12 bytes) || AES-GCM(masterKey) || tag (16 bytes)

// Derive wrapping key from password
salt := randomBytes(16)
wrappingKey := argon2.IDKey(
    password,
    salt,
    time=3,        // iterations
    memory=64*1024, // 64 MiB
    threads=4,
    keyLen=32,
)

// Wrap master key
wrappedKey := AES-GCM-Encrypt(masterKey, wrappingKey)

// Store slot
slot := KeySlot{
    Type: "password",
    WrappedKey: base64(wrappedKey),
    KDFParams: {
        "salt": base64(salt),
        "time": 3,
        "memory": 65536,
        "threads": 4,
    },
}

export PLATFORM_ENCRYPTION_KEY="a3f5b8c9d1e2f4a6..."

AWS KMS CMK (Customer Managed Key)
    ↓ encrypts
Data Encryption Key (DEK, 256-bit)
    ↓ wraps
Master Key

// Generate 256-bit random key
recoveryKey := randomBytes(32)

// Encode as BIP39 mnemonic (24 words)
mnemonic := bip39.Encode(recoveryKey)
// Example: "abandon ability able about above absent absorb abstract ..."

// Wrap master key with recovery key
wrappedKey := AES-GCM-Encrypt(masterKey, recoveryKey)

// Store slot (recovery key is NOT stored)
slot := KeySlot{
    Type: "recovery",
    WrappedKey: base64(wrappedKey),
    Label: "default",
}

// Display mnemonic ONCE to user
fmt.Println("Recovery key (write this down securely):")
fmt.Println(mnemonic)

// User provides 24-word mnemonic
mnemonic := "abandon ability able about above ..."

// Decode to raw 256-bit key
recoveryKey := bip39.Decode(mnemonic)

// Unwrap master key
masterKey := AES-GCM-Decrypt(wrappedKey, recoveryKey)

// Derive encryption key
encryptionKey := HKDF-SHA256(masterKey, "cloudstic-backup-v1")

# Initialize with password and recovery key
cloudstic init --encryption-password mypass --recovery

# Add recovery key to existing repo
cloudstic add-recovery-key --encryption-password mypass

# Use recovery key to unlock repo
cloudstic backup --recovery-key "abandon ability able about above ..."

# Or via environment variable
export CLOUDSTIC_RECOVERY_KEY="abandon ability able about above ..."
cloudstic backup

BackupEngine
    ↓
CompressedStore  (zstd)
    ↓
EncryptedStore   (AES-256-GCM) ← You are here
    ↓
MeteredStore
    ↓
Backend (S3, B2, etc.)

func (e *EncryptedStore) Put(ctx, key string, data []byte) error {
    // Pass through keys/* unencrypted
    if strings.HasPrefix(key, "keys/") {
        return e.inner.Put(ctx, key, data)
    }
    
    // Encrypt data
    ciphertext, err := crypto.Encrypt(data, e.encryptionKey)
    if err != nil {
        return err
    }
    
    // Delegate to inner store
    return e.inner.Put(ctx, key, ciphertext)
}

func (e *EncryptedStore) Get(ctx, key string) ([]byte, error) {
    // Pass through keys/* unencrypted
    if strings.HasPrefix(key, "keys/") {
        return e.inner.Get(ctx, key)
    }
    
    // Fetch from inner store
    data, err := e.inner.Get(ctx, key)
    if err != nil {
        return nil, err
    }
    
    // Check if encrypted (version byte 0x01)
    if !crypto.IsEncrypted(data) {
        // Legacy unencrypted data - return as-is
        return data, nil
    }
    
    // Decrypt
    plaintext, err := crypto.Decrypt(data, e.encryptionKey)
    if err != nil {
        return nil, err
    }
    
    return plaintext, nil
}

// 1. Chunk the file (content-defined boundaries)
chunks := FastCDC(fileStream)

for chunk := range chunks {
    // 2. Hash with HMAC (using dedup key)
    chunkHash := HMAC-SHA256(dedupKey, chunk)
    key := "chunk/" + chunkHash
    
    // 3. Check existence BEFORE encrypting
    exists, _ := store.Exists(ctx, key)
    if exists {
        continue  // Skip upload - chunk already stored
    }
    
    // 4. Compress and encrypt
    compressed := zstd.Compress(chunk)
    encrypted := AES-GCM-Encrypt(compressed, encryptionKey)
    
    // 5. Upload
    store.Put(ctx, key, encrypted)
}

// 1. For each tenant:
for tenant := range tenants {
    // 2. Unwrap master key with OLD platform key
    masterKey := UnwrapKey(tenant.WrappedKey, oldPlatformKey)
    
    // 3. Re-wrap with NEW platform key
    newWrappedKey := WrapKey(masterKey, newPlatformKey)
    
    // 4. Update database
    db.Exec("UPDATE encryption_key_slots SET wrapped_key = ? WHERE tenant_id = ?",
        newWrappedKey, tenant.ID)
}

1. List keys/* objects to discover available slots
   ↓
2. If -kms-key-arn provided, try kms-platform slots
   └─ Call kms:Decrypt to unwrap DEK
   └─ Use DEK to unwrap master key
   ↓
3. Try platform key (PLATFORM_ENCRYPTION_KEY env var)
   └─ Unwrap master key directly
   ↓
4. Try password (-encryption-password flag or CLOUDSTIC_PASSWORD)
   └─ Derive wrapping key with Argon2id
   └─ Unwrap master key
   ↓
5. Try recovery key (-recovery-key flag or CLOUDSTIC_RECOVERY_KEY)
   └─ Decode BIP39 mnemonic to raw key
   └─ Unwrap master key
   ↓
6. Derive encryption key: HKDF-SHA256(masterKey, "cloudstic-backup-v1")
   ↓
7. Derive dedup key: HKDF-SHA256(encryptionKey, "cloudstic-dedup-mac-v1")
   ↓
8. Create EncryptedStore with encryption key