ZCLIP 001 RFC: `loadwallet` & `unloadwallet` & `dm-crypt`/`veracrypt` logic flow for FULL wallet encryption integration

# ZCLIP 001 RFC: `loadwallet` & `unloadwallet` & `cryptsetup`/`veracrypt` logic flow for FULL wallet encryption integration

## Overview
Before implementing full wallet encryption via dm-crypt/VeraCrypt, we must first backport `loadwallet`/`unloadwallet` RPC functionality from Bitcoin Core to enable dynamic wallet mounting.     

i am working on this now, before working on the zclassic full node dm-crypt/veracrypt funcitons/RPC calls

## Phased Implementation

### Phase 1: Wallet Load/Unload (Current Scope)
- **Reference**: Bitcoin Core v0.17.0 (earliest stable implementation of multi-wallet load/unload)
- **Scope Reduction**: Single wallet support only (no multi-wallet complexity)
- **Functions**: `loadwallet` and `unloadwallet` RPC commands
- **Security Benefit**: Minimizes wallet memory exposure time

### Phase 2: Full Wallet Encryption Integration
Once Phase 1 is complete:
- **Linux**: **5-layer dm-crypt cascade**: Serpent → Twofish → AES → Camellia → Blowfish
- **Windows/macOS**: VeraCrypt 3-cipher cascade: AES(Twofish(Serpent))
- **Encryption Hash**: **Whirlpool** for all platforms
- **Integration**: Symlink `wallet.dat` from mounted encrypted volume to datadir
- **UX Enhancement**: All encryption operations integrated into `zcl-cli` wrapper commands
- **Attack Surface Reduction**: Wallet encrypted at rest; only decrypted when actively loaded

## Cryptographic Parameters

### Linux: 5-Layer dm-crypt Cascade

**Cipher Stack (outer → inner)**:
1. **Serpent-XTS** (outermost) - 256-bit key, 32 rounds, highest security margin
2. **Twofish-XTS** - 256-bit key, 16 rounds, Schneier-designed Feistel cipher
3. **AES-XTS** - 256-bit key, 14 rounds, hardware-accelerated (AES-NI)
4.  **Camellia-XTS** - 256-bit key, 24 rounds, NTT/Mitsubishi design (international diversity)
5. **Blowfish-XTS** (innermost) - **448-bit key**, 16 rounds, Schneier design (maximum key length)

**Rationale for 5-Layer Cascade**:
- **Maximum paranoia** for high-value cryptocurrency cold storage
- **Maximum compatibility**: All ciphers available on standard Linux kernels (modprobe if needed)
- **Algorithm diversity**: Western (AES, Twofish, Serpent, Blowfish), Japanese (Camellia)
- **Design diversity**: Feistel (Twofish, Blowfish), SPN (AES, Serpent, Camellia)
- **Failure resilience**: Breaking requires compromise of ALL five ciphers independently
- **Geographic trust distribution**: Algorithms from USA, Japan, UK design teams
- **Performance**: Kernel-level dm-crypt faster than user-space VeraCrypt even with 5 layers
- **Extended key length**: Blowfish supports up to 448-bit keys (longest in cascade)

**Security Property**: An attacker must:
1. Break Serpent-256 (32 rounds, no practical attacks)
2. AND break Twofish-256 (key-dependent S-boxes)
3. AND break AES-256 (NIST standard, hardware-accelerated)
4. AND break Camellia-256 (ISO/IEC 18033-3 standard)
5.  AND break Blowfish-448 (16 rounds, 448-bit key = largest keyspace in cascade)

**XTS Mode**: Each cipher layer uses XTS mode (IEEE P1619) for disk encryption:
- Serpent/Twofish/AES/Camellia: 512-bit effective key (256-bit encryption + 256-bit tweak)
- Blowfish: 896-bit effective key (448-bit encryption + 448-bit tweak)
- No IV reuse across sectors
- Resistant to block manipulation attacks

### Windows/macOS: 3-Layer VeraCrypt Cascade

**Cipher Stack**: AES(Twofish(Serpent))
- **Serpent (Inner)**: 256-bit key, 32 rounds, conservative design
- **Twofish (Middle)**: 256-bit key, 16 rounds, key-dependent S-boxes
- **AES (Outer)**: 256-bit key, 14 rounds, hardware-accelerated

**Rationale**: VeraCrypt maximum supported cascade (3 ciphers).  Linux provides superior 5-layer protection.

### Hash Algorithm: Whirlpool (All Platforms)

**Whirlpool Advantages**:
- ✅ 512-bit output (double SHA-256)
- ✅ Designed by Rijmen/Barreto (Rijmen co-designed AES)
- ✅ Based on modified AES block cipher (well-understood primitives)
- ✅ **No length-extension attacks** (unlike SHA-2 family)
- ✅ Larger internal state (512-bit vs SHA-512's 256-bit)
- ✅ ISO/IEC 10118-3 standard
- ✅ **No known collision attacks**
- ✅ Resistance to multi-collision attacks

**Decision**: **Whirlpool** for maximum cryptographic conservatism in long-term cold storage scenario.

## Technical Workflow

```
┌───────────────────────────────────────────────────────────────────────────┐
│         FULL WALLET ENCRYPTION WORKFLOW (Post-Implementation)             │
│              (5-Layer dm-crypt / 3-Layer VeraCrypt via zcl-cli)           │
│                                                                           │
│   Linux: Serpent→Twofish→AES→Camellia→Blowfish + Whirlpool (5 CIPHERS!) │
│   Win/Mac: AES(Twofish(Serpent)) + Whirlpool (3 CIPHERS)                 │
└───────────────────────────────────────────────────────────────────────────┘

  [User Command: zcl-cli encryptedwallet create]
           │
           ├─────────────────────────┬──────────────────────────┐
           │                         │                          │
    ┌──────▼──────┐          ┌───────▼────────┐        ┌───────▼────────┐
    │   LINUX     │          │    WINDOWS     │        │     macOS      │
    │  (5-LAYER)  │          │  (3-LAYER)     │        │  (3-LAYER)     │
    └──────┬──────┘          └───────┬────────┘        └───────┬────────┘
           │                         │                         │
           │ zcl-cli orchestrates:   │ zcl-cli calls:          │ zcl-cli calls:
           │                         │ veracrypt --create      │ veracrypt --create
           │ [Layer 5 - Blowfish]    │ wallet. tc               │ wallet.tc
           │ cryptsetup luksFormat   │ --encryption=           │ --encryption=
           │ --cipher blowfish-xts-  │  AES-Twofish-Serpent    │  AES-Twofish-Serpent
           │  plain64 --key-size 896 │ --hash=Whirlpool        │ --hash=Whirlpool
           │ wallet_layer5.luks      │ --filesystem=NTFS       │ --filesystem=exFAT
           │                         │ --pim=485               │ --pim=485
           │ [Layer 4 - Camellia]    │ --size=100M             │ --size=100M
           │ cryptsetup luksFormat   │                         │
           │ --cipher camellia-xts-  │                         │
           │  plain64 --key-size 512 │                         │
           │ /dev/mapper/layer5      │                         │
           │                         │                         │
           │ [Layer 3 - AES]         │                         │
           │ cryptsetup luksFormat   │                         │
           │ --cipher aes-xts-       │                         │
           │  plain64 --key-size 512 │                         │
           │ /dev/mapper/layer4      │                         │
           │                         │                         │
           │ [Layer 2 - Twofish]     │                         │
           │ cryptsetup luksFormat   │                         │
           │ --cipher twofish-xts-   │                         │
           │  plain64 --key-size 512 │                         │
           │ /dev/mapper/layer3      │                         │
           │                         │                         │
           │ [Layer 1 - Serpent]     │                         │
           │ cryptsetup luksFormat   │                         │
           │ --cipher serpent-xts-   │                         │
           │  plain64 --key-size 512 │                         │
           │ /dev/mapper/layer2      │                         │
           │                         │                         │
           │ mkfs.ext4               │                         │
           │ /dev/mapper/layer1      │                         │
           │                         │                         │
           │ [5-cipher cascade created: Serpent→Twofish→AES→   │
           │  Camellia→Blowfish(448-bit), all with Whirlpool]  │
           │                         │                         │
           └─────────────────────────┴─────────────────────────┘

  [User Command: zcl-cli encryptedwallet mount]
           │
           ├─────────────────────────┬──────────────────────────┐
           │                         │                          │
    ┌──────▼──────┐          ┌───────▼────────┐        ┌───────▼────────┐
    │   LINUX     │          │    WINDOWS     │        │     macOS      │
    │  (5-LAYER)  │          │  (3-LAYER)     │        │  (3-LAYER)     │
    └──────┬──────┘          └───────┬────────┘        └───────┬────────┘
           │                         │                         │
           │ zcl-cli ONE PASSWORD    │ zcl-cli executes:       │ zcl-cli executes:
           │ unlocks ALL 5 layers:   │ veracrypt --mount       │ veracrypt --mount
           │                         │ wallet.tc /l W          │ wallet.tc
           │ cryptsetup open         │ --pim=485               │ --pim=485
           │ wallet_layer5.luks      │                         │
           │ layer5 (Blowfish-448)   │ [Decrypt: AES→Twofish→  │ [Decrypt cascade]
           │ [Password: user input]  │  Serpent layers]        │
           │                         │                         │
           │ cryptsetup open         │                         │
           │ /dev/mapper/layer5      │                         │
           │ layer4 (Camellia-256)   │                         │
           │ [Password: DERIVED]     │                         │
           │                         │                         │
           │ cryptsetup open         │                         │
           │ /dev/mapper/layer4      │                         │
           │ layer3 (AES-256)        │                         │
           │ [Password: DERIVED]     │                         │
           │                         │                         │
           │ cryptsetup open         │                         │
           │ /dev/mapper/layer3      │                         │
           │ layer2 (Twofish-256)    │                         │
           │ [Password: DERIVED]     │                         │
           │                         │                         │
           │ cryptsetup open         │                         │
           │ /dev/mapper/layer2      │                         │
           │ layer1 (Serpent-256)    │                         │
           │ [Password: DERIVED]     │                         │
           │                         │                         │
           │ mount /dev/mapper/      │                         │
           │ layer1 /mnt/zcl_wallet  │                         │
           │                         │                         │
           ▼                         ▼                         ▼
    /mnt/zcl_wallet/          W:\wallet.dat            /Volumes/VERACRYPT1/
      wallet. dat                                         wallet.dat
           │                         │                         │
           │ zcl-cli auto-creates symlink:                     │
           │ ln -s <mount>/wallet.dat ~/. zclassic/wallet.dat   │
           │                         │                         │
           └─────────────────────────┴─────────────────────────┘
                                     │
                                     ▼
                          ┌──────────────────────┐
                          │  Symlink Created:    │
                          │  ~/.zclassic/        │
                          │    wallet.dat ──────►│ (points to encrypted vol)
                          └──────────┬───────────┘
                                     │
                                     │ [AUTOMATIC by mount command]
                                     │
                                     │  zcl-cli loadwallet "wallet.dat"
                                     ▼
                          ┌──────────────────────┐
                          │  zclassicd Process   │
                          │  • Validate symlink  │
                          │  • Load wallet. dat   │
                          │  • Decrypt with      │
                          │    wallet passphrase │
                          │  • Hold in RAM       │
                          └──────────┬───────────┘
                                     │
                                [Active Wallet]
                                [Shielded Ops]
                             [JoinSplit Proofs]
                                     │
                                     │
  [User Command: zcl-cli encryptedwallet unmount]
                                     │
                                     ▼
                          ┌──────────────────────┐
                          │  zcl-cli executes:   │
                          │  1. unloadwallet     │
                          │     (zero memory)    │
                          │  2. Platform-specific│
                          │     dismount         │
                          └──────────┬───────────┘
                                     │
           ┌─────────────────────────┼─────────────────────────┐
           │                         │                         │
    ┌──────▼──────┐          ┌───────▼────────┐        ┌──────▼───────┐
    │   LINUX     │          │    WINDOWS     │        │    macOS     │
    │  (5-LAYER)  │          │  (3-LAYER)     │        │  (3-LAYER)   │
    └──────┬──────┘          └───────┬────────┘        └──────┬───────┘
           │                         │                         │
           │ zcl-cli calls:          │ zcl-cli calls:          │ zcl-cli calls:
           │ unloadwallet            │ unloadwallet            │ unloadwallet
           │                         │ veracrypt --dismount W  │ veracrypt
           │ umount /mnt/zcl_wallet  │                         │ --dismount
           │                         │ [Locks all 3 ciphers]   │ /Volumes/VERACRYPT1
           │ cryptsetup close layer1 │                         │
           │ (Serpent LOCKED)        │                         │
           │                         │                         │
           │ cryptsetup close layer2 │                         │
           │ (Twofish LOCKED)        │                         │
           │                         │                         │
           │ cryptsetup close layer3 │                         │
           │ (AES LOCKED)            │                         │
           │                         │                         │
           │ cryptsetup close layer4 │                         │
           │ (Camellia LOCKED)       │                         │
           │                         │                         │
           │ cryptsetup close layer5 │                         │
           │ (Blowfish-448 LOCKED)   │                         │
           │                         │                         │
           └─────────────────────────┴─────────────────────────┘
                                     │
                                     ▼
                          ┌──────────────────────┐
                          │  Encrypted Container │
                          │   [LOCKED STATE]     │
                          │  • Linux: 5 ciphers  │
                          │  • Win/Mac: 3 ciphers│
                          │  • Whirlpool KDF     │
                          │  • Attack surface: 0 │
                          │  • Cold storage mode │
                          └──────────────────────┘
```

## Platform-Specific Security Considerations

### Linux (5-Layer dm-crypt/LUKS Cascade)
- ✅ **MAXIMUM SECURITY**: 5 independent cipher layers
- ✅ **MAXIMUM COMPATIBILITY**: All ciphers universally available
- ✅ Kernel-level encryption (battle-tested, high performance)
- ✅ LUKS2 supports Argon2id key derivation (anti-GPU brute-force)
- ✅ Whirlpool hash support via `--hash whirlpool`
- ✅ **Algorithm diversity**: Western + Japanese designs
- ✅ **Design diversity**: Feistel (Twofish, Blowfish) + SPN (AES, Serpent, Camellia)
- ✅ **Extended key length**: Blowfish 448-bit key (longest in cascade)
- ✅ XTS mode per layer (no IV reuse, sector-level tweaking)
- ✅ **User-friendly**: Single password unlocks all 5 layers (key derivation)
- ✅ Detached headers possible (plausible deniability)
- ✅ Performance: Kernel-level faster than user-space VeraCrypt despite 5 layers
- ⚠️ Requires root/sudo for cryptsetup operations (zcl-cli will prompt)
- ⚠️ Camellia may require: `modprobe camellia_generic` (zcl-cli auto-loads)
- ⚠️ Consider using --allow-discards for SSD TRIM (metadata leakage vs wear)

### Windows (VeraCrypt 3-Layer Cascade)
- ✅ **AES(Twofish(Serpent))** cascade fully supported
- ✅ **Whirlpool** hash fully supported
- ✅ PIM (Personal Iterations Multiplier) for KDF strengthening
- ✅ Plausible deniability (hidden volumes)
- ✅ Portable mode (no admin required after driver install)
- ⚠️ User-space implementation (vs kernel-level on Linux)
- ⚠️ Limited to 3-cipher cascade (VeraCrypt maximum)
- ⚠️ Initial driver installation requires admin privileges
- ⚠️ NTFS filesystem overhead

### macOS (VeraCrypt 3-Layer Cascade)
- ✅ **AES(Twofish(Serpent))** cascade fully supported
- ✅ **Whirlpool** hash fully supported
- ✅ Hidden volume support (plausible deniability)
- ✅ exFAT recommended for macOS compatibility (vs NTFS)
- ✅ Cross-platform container portability (same . tc file works on all OS)
- ⚠️ Requires macFUSE installation (dependency on third-party kernel extension)
- ⚠️ Limited to 3-cipher cascade (VeraCrypt maximum)
- ⚠️ macOS Gatekeeper/SIP may require explicit permission grants
- ⚠️ Apple Silicon: macFUSE requires Reduced Security mode in Recovery
- ⚠️ VeraCrypt updates may lag behind macOS version releases

## Security Properties

- **Linux: 5-cipher cascade** - Requires breaking Serpent AND Twofish AND AES AND Camellia AND Blowfish-448 simultaneously
- **Windows/macOS: 3-cipher cascade** - Requires breaking AES AND Twofish AND Serpent simultaneously
- **Whirlpool KDF**: No length-extension attacks, larger state than SHA-512
- **Single password UX**: Linux derives 5 layer keys from one master password
- **Extended keyspace**: Blowfish 448-bit key provides 2^448 keyspace on innermost layer
- Wallet only decrypted when actively loaded in memory
- Two-layer security: disk encryption + wallet passphrase
- Cold storage compatible (mount read-only)
- Memory wiped on unloadwallet (zeroing implementation required)
- Resistant to offline attacks on wallet. dat
- Symlink validates mount state before load
- **UX Security**: Automated workflow reduces user error in encryption operations
- **Long-term security**: Conservative multi-cipher choice for decades-long cold storage
- **Geographic trust distribution** (Linux): Algorithms from USA, Japan, UK

## Threat Model Mitigations

| Threat | Mitigation |
|--------|------------|
| AES cryptanalysis breakthrough | ✅ Linux: 4 fallback ciphers; Win/Mac: 2 fallback ciphers |
| Single-cipher side-channel attacks | ✅ Cascade masks timing/power characteristics |
| Algorithm backdoors (trust issues) | ✅ Linux: 5 algorithms from different nations/teams |
| Filesystem forensics | ✅ Linux: 5-cipher encryption; Win/Mac: 3-cipher encryption |
| Memory dumps (post-use) | ✅ unloadwallet zeros sensitive data |
| Unauthorized disk access | ✅ Whirlpool KDF (500k iterations) + Argon2id |
| Wallet. dat theft | ✅ Encrypted at rest (requires container password) |
| Evil maid attacks | ✅ PIM adds entropy; keyfiles on separate device |
| User operational errors | ✅ zcl-cli automates mount/unmount/load/unload sequence |
| SHA-2 length-extension | ✅ Whirlpool structurally immune |
| Brute-force attacks | ✅ Linux: Blowfish 448-bit key = 2^448 keyspace (innermost layer) |
| Quantum computing (future) | ⚠️ 256-bit symmetric keys provide 128-bit quantum security; 448-bit provides 224-bit |
| Rubber-hose cryptanalysis | ❌ Out of scope; consider duress passwords/hidden volumes |

## New zcl-cli Commands (Phase 2)

### `zcl-cli encryptedwallet create [options]`

Creates a new encrypted wallet container using platform-appropriate encryption.

**Options:**
- `--size=<MB>` - Container size in megabytes (default: 100)
- `--keyfile=<path>` - Optional keyfile path for additional security
- `--pim=<number>` - VeraCrypt PIM value (default: 485, Windows/macOS only)
- `--iterations=<number>` - LUKS Argon2id iterations (default: 4, Linux only)
- `--hash=<algorithm>` - Hash algorithm (default: `Whirlpool`)

**Example:**
```bash
# Linux (5-layer cascade)
zcl-cli encryptedwallet create --size=500 --keyfile=/secure/usb/key.dat --iterations=6

# Windows/macOS (3-layer cascade)
zcl-cli encryptedwallet create --size=500 --keyfile=/secure/usb/key.dat --pim=650
```

**Behavior:**
- **Linux**: Creates 5-layer LUKS2 cascade at `~/.zclassic/wallet_encrypted/`
  - Outer layer: `wallet_layer5.luks` (Blowfish-XTS-PLAIN64, 448-bit key)
  - Automatically stacks all 5 layers
  - Single password encrypts all layers (derived keys)
  - Auto-loads kernel modules if needed (`modprobe camellia_generic`)
- **Windows**: Creates VeraCrypt container at `%APPDATA%\ZClassic\wallet_encrypted. tc`
- **macOS**: Creates VeraCrypt container at `~/Library/Application Support/ZClassic/wallet_encrypted.tc`
- Prompts for container password (with confirmation)
- Validates password strength (minimum 20 characters recommended)
- Automatically formats container and creates initial `wallet.dat`
- Displays security parameters confirmation

**Security Output (Linux):**
```
Creating encrypted wallet container (5-LAYER CASCADE)... 
Checking kernel crypto support...
  ✓ serpent available
  ✓ twofish available
  ✓ aes available
  ⚙ Loading camellia module...  ✓
  ✓ blowfish available

Layer 5 (outer): Blowfish-XTS-PLAIN64 (448-bit key)
Layer 4: Camellia-XTS-PLAIN64 (256-bit key)
Layer 3: AES-XTS-PLAIN64 (256-bit key)
Layer 2: Twofish-XTS-PLAIN64 (256-bit key)
Layer 1 (inner): Serpent-XTS-PLAIN64 (256-bit key)
Hash: Whirlpool
Key Derivation: Argon2id (iterations=4, 1GB memory)
Container size: 500 MB

Enter container password (20+ characters): **********************
Confirm password: **********************

[██████████████████████████████] 100% - Layer 5 (Blowfish-448) created
[██████████████████████████████] 100% - Layer 4 (Camellia-256) created
[██████████████████████████████] 100% - Layer 3 (AES-256) created
[██████████████████████████████] 100% - Layer 2 (Twofish-256) created
[██████████████████████████████] 100% - Layer 1 (Serpent-256) created
[██████████████████████████████] 100% - Filesystem created

Container created: ~/.zclassic/wallet_encrypted/
Security level: MAXIMUM (5 ciphers, 448-bit max key)
Security verification: PASS
```

**Security Output (Windows/macOS):**
```
Creating encrypted wallet container (3-LAYER CASCADE)...  
Encryption: AES(Twofish(Serpent)) cascade
Hash: Whirlpool
Key Derivation: PBKDF2-Whirlpool with PIM=650 (325,000 iterations)
Container size: 500 MB

Enter container password (20+ characters): **********************
Confirm password: **********************

[██████████████████████████████] 100% - Generating random data
Container created: ~/Library/Application Support/ZClassic/wallet_encrypted.tc
Security level: HIGH (3 ciphers)
Security verification: PASS
```

---

### `zcl-cli encryptedwallet mount`

Mounts encrypted wallet container and loads wallet into zclassicd.

**Example:**
```bash
zcl-cli encryptedwallet mount
```

**Behavior:**
1.  Detects platform (Linux/Windows/macOS)
2. Prompts for container password (ONCE for all layers on Linux)
3. **Linux**: Derives 5 keys from master password, opens all layers sequentially
4. **Windows/macOS**: Calls VeraCrypt with `--encryption=AES-Twofish-Serpent --hash=Whirlpool`
5.  Mounts encrypted container to platform-specific location
6. Creates/validates symlink: `~/.zclassic/wallet.dat` → mounted container
7. Automatically calls `loadwallet "wallet.dat"`
8. Returns wallet status and shielded address count

**Security:**
- Validates container integrity before mount
- Checks for existing mounts (prevents double-mount)
- **Linux**: Verifies all 5 cipher layers are configured correctly
- **Linux**: Auto-loads kernel modules if needed
- **Windows/macOS**: Verifies cipher cascade and hash algorithm match expected values
- Verifies symlink target before loading wallet
- **Linux-specific**: Uses `sudo` for cryptsetup operations (prompts for password)

**Output (Linux):**
```
Mounting encrypted wallet (5-LAYER CASCADE)...  
Container: ~/.zclassic/wallet_encrypted/

Enter container password: **********************

[Decrypting layer 5: Blowfish-448]  ✓
[Decrypting layer 4: Camellia-256]  ✓
[Decrypting layer 3: AES-256]       ✓
[Decrypting layer 2: Twofish-256]   ✓
[Decrypting layer 1: Serpent-256]   ✓

Mounted: /mnt/zcl_wallet
Symlink created: ~/.zclassic/wallet.dat → /mnt/zcl_wallet/wallet.dat
Loading wallet... 

Wallet loaded successfully. 
Shielded addresses: 5
Transparent addresses: 2
Security: 5-CIPHER CASCADE ACTIVE (max key: 448-bit)
```

**Output (Windows/macOS):**
```
Mounting encrypted wallet (3-LAYER CASCADE)... 
Container: ~/Library/Application Support/ZClassic/wallet_encrypted. tc
Encryption: AES(Twofish(Serpent)) ✓
Hash: Whirlpool ✓

Enter container password: **********************

[Decrypting layers: AES → Twofish → Serpent]
Mounted: /Volumes/VERACRYPT1
Symlink created: ~/.zclassic/wallet.dat → /Volumes/VERACRYPT1/wallet. dat
Loading wallet... 

Wallet loaded successfully.  
Shielded addresses: 5
Transparent addresses: 2
Security: 3-CIPHER CASCADE ACTIVE
```

---

### `zcl-cli encryptedwallet unmount`

Securely unloads wallet and dismounts encrypted container.

**Example:**
```bash
zcl-cli encryptedwallet unmount
```

**Behavior:**
1. Calls `unloadwallet "wallet.dat"` (zeros memory with `OPENSSL_cleanse`)
2. Waits for file handle closure (prevents premature dismount)
3. **Linux**: Closes all 5 dm-crypt layers in reverse order
4. **Windows/macOS**: Dismounts VeraCrypt container
5. Validates container is fully locked
6. Returns success confirmation

**Security:**
- Refuses to unmount if wallet has pending transactions
- Flushes wallet. dat to disk before unmount
- Scrubs sensitive data from memory (wallet keys, passphrases)
- **Linux**: Verifies all 5 cipher layers are re-locked
- **Windows/macOS**: Verifies all 3 cipher layers are re-locked
- **Linux-specific**: Uses `sudo` for cryptsetup close operations

**Output (Linux):**
```
Unloading wallet... 
Wallet unloaded ✓ (memory scrubbed)

Unmounting encrypted container (5-LAYER CASCADE)... 
Closing layer 1 (Serpent-256)   ✓ LOCKED
Closing layer 2 (Twofish-256)   ✓ LOCKED
Closing layer 3 (AES-256)       ✓ LOCKED
Closing layer 4 (Camellia-256)  ✓ LOCKED
Closing layer 5 (Blowfish-448)  ✓ LOCKED

Container fully locked ✓

Security status:
  Blowfish-448 layer: LOCKED
  Camellia-256 layer: LOCKED
  AES-256 layer: LOCKED
  Twofish-256 layer: LOCKED
  Serpent-256 layer: LOCKED
```

**Output (Windows/macOS):**
```
Unloading wallet... 
Wallet unloaded ✓ (memory scrubbed)

Unmounting encrypted container (3-LAYER CASCADE)... 
Dismounted: /Volumes/VERACRYPT1
Container locked ✓

Security status:
  AES layer: LOCKED
  Twofish layer: LOCKED
  Serpent layer: LOCKED
```

---

### `zcl-cli encryptedwallet status`

Reports encrypted wallet mount status and security state.

**Example:**
```bash
zcl-cli encryptedwallet status
```

**Output (Linux):**
```json
{
  "encrypted": true,
  "container_type": "dm-crypt-cascade",
  "container_path": "~/.zclassic/wallet_encrypted/",
  "mounted": true,
  "mount_point": "/mnt/zcl_wallet",
  "wallet_loaded": true,
  "symlink_valid": true,
  "cipher_layers": 5,
  "ciphers": [
    "Blowfish-XTS-PLAIN64 (448-bit key, outer)",
    "Camellia-XTS-PLAIN64 (256-bit key)",
    "AES-XTS-PLAIN64 (256-bit key)",
    "Twofish-XTS-PLAIN64 (256-bit key)",
    "Serpent-XTS-PLAIN64 (256-bit key, inner)"
  ],
  "max_key_length": 448,
  "hash": "Whirlpool",
  "kdf": "Argon2id",
  "kdf_iterations": 4,
  "filesystem": "ext4",
  "readonly": false,
  "keyfile_in_use": true,
  "security_level": "MAXIMUM (5-cipher cascade, 448-bit max key)"
}
```

**Output (Windows/macOS):**
```json
{
  "encrypted": true,
  "container_type": "veracrypt",
  "container_path": "~/Library/Application Support/ZClassic/wallet_encrypted.tc",
  "mounted": true,
  "mount_point": "/Volumes/VERACRYPT1",
  "wallet_loaded": true,
  "symlink_valid": true,
  "cipher_layers": 3,
  "encryption": "AES(Twofish(Serpent))",
  "hash": "Whirlpool",
  "pim": 650,
  "kdf_iterations": 325000,
  "filesystem": "exFAT",
  "readonly": false,
  "keyfile_in_use": true,
  "security_level": "HIGH (3-cipher cascade)"
}
```

---

### `zcl-cli encryptedwallet backup <destination>`

Creates encrypted backup of wallet container.

**Example:**
```bash
# Linux
zcl-cli encryptedwallet backup /media/usb/wallet_backup_2025/

# Windows/macOS
zcl-cli encryptedwallet backup /media/usb/wallet_backup_2025. tc
```

**Behavior:**
- Unmounts wallet if currently mounted
- **Linux**: Copies all 5 LUKS layer files
- **Windows/macOS**: Copies encrypted . tc container
- Verifies backup integrity (SHA-512 checksums)
- Optionally re-mounts original container
- **Critical**: Backup is already multi-cipher encrypted (safe for offsite storage)

**Output (Linux):**
```
Creating encrypted backup (5-LAYER CASCADE)... 
Source: ~/.zclassic/wallet_encrypted/
Destination: /media/usb/wallet_backup_2025/

[██████████████████████████████] 100% - wallet_layer5.luks (Blowfish-448)
[██████████████████████████████] 100% - Layer 4 container (Camellia-256)
[██████████████████████████████] 100% - Layer 3 container (AES-256)
[██████████████████████████████] 100% - Layer 2 container (Twofish-256)
[██████████████████████████████] 100% - Layer 1 container (Serpent-256)

Verifying backup integrity... 
SHA-512 checksums: ALL MATCH ✓

Backup created successfully.  
Encryption preserved: 5-cipher cascade (Serpent→Twofish→AES→Camellia→Blowfish-448)
Store in secure, offsite location.   
```

---

## Operational Security Workflow (Simplified UX)

### First-Time Setup

**Linux (5-cipher cascade):**
```bash
# 1. Create encrypted wallet container
zcl-cli encryptedwallet create --size=500 --keyfile=/secure/usb/key.dat --iterations=6
# Prompts: Enter container password (20+ chars recommended)
# Output: Container created with 5-cipher cascade (Blowfish-448 max key)

# 2.  Mount and initialize wallet (SINGLE PASSWORD for all 5 layers!)
zcl-cli encryptedwallet mount
# Prompts: Enter container password
# Output: [Decrypts all 5 layers automatically]
#         Wallet loaded successfully.  Shielded addresses: 0
```

**Windows/macOS (3-cipher cascade):**
```bash
# 1. Create encrypted wallet container
zcl-cli encryptedwallet create --size=500 --keyfile=/secure/usb/key.dat --pim=650
# Prompts: Enter container password (20+ chars recommended)
# Output: Container created with AES(Twofish(Serpent)) + Whirlpool

# 2. Mount and initialize wallet
zcl-cli encryptedwallet mount
# Prompts: Enter container password
# Output: Wallet loaded successfully. Shielded addresses: 0
```

### Daily Usage

```bash
# Mount encrypted wallet (single password unlocks all layers)
zcl-cli encryptedwallet mount
# Linux: [Decrypting 5 layers...  Blowfish-448 → Camellia → AES → Twofish → Serpent]
# Win/Mac: [Decrypting 3 layers... AES → Twofish → Serpent]

# Perform transactions
zcl-cli z_sendmany "t1address" '[{"address":"zcaddress","amount":10}]'

# Check encryption status
zcl-cli encryptedwallet status
# Linux output: "security_level": "MAXIMUM (5-cipher cascade, 448-bit max key)"
# Win/Mac output: "security_level": "HIGH (3-cipher cascade)"

# Unmount when done
zcl-cli encryptedwallet unmount
# Linux: [Locking all 5 cipher layers...]
# Win/Mac: [Locking all 3 cipher layers...]
```

### Cold Storage Backup

```bash
# Create encrypted backup to USB drive
zcl-cli encryptedwallet backup /media/usb/zclassic_cold_storage_2025

# Linux: Copies all 5 LUKS containers
# Win/Mac: Copies VeraCrypt . tc file
# Output: Backup created successfully (SHA-512: abc123...)
#         Encryption preserved
```

## Implementation Checklist

### Phase 1 (loadwallet/unloadwallet)
- [ ] Backport Bitcoin Core 0.17.0 wallet loading logic
- [ ] Implement CWallet lifecycle management (init/shutdown)
- [ ] Add RPC commands: `loadwallet`, `unloadwallet`
- [ ] Implement secure memory zeroing (`OPENSSL_cleanse` on keys)
- [ ] Add wallet lock file to prevent concurrent access
- [ ] Test symlink resolution and validation
- [ ] Audit for null pointer dereferences post-unload

### Phase 2 (zcl-cli Encryption Integration)

#### Cross-Platform
- [ ] Implement platform detection (Linux/Windows/macOS)
- [ ] Add dependency checks (cryptsetup on Linux, VeraCrypt on Win/Mac)
- [ ] Password strength validation (entropy calculation)
- [ ] Keyfile support and validation
- [ ] Implement `encryptedwallet status` command
- [ ] Implement `encryptedwallet backup` command
- [ ] Add comprehensive error handling
- [ ] Security audit: timing attacks, error message leakage
- [ ] Documentation: User guide with platform-specific instructions
- [ ] Documentation: Security best practices guide

#### Linux-Specific (5-Layer Cascade)
- [ ] Implement `encryptedwallet create` for Linux
  - [ ] Kernel crypto module detection (`/proc/crypto` parsing)
  - [ ] Auto-load missing modules (`modprobe camellia_generic` etc.)
  - [ ] Create 5 nested LUKS2 containers (Blowfish→Camellia→AES→Twofish→Serpent)
  - [ ] Layer 5 (outer): Blowfish-XTS-PLAIN64, 448-bit key (896-bit with XTS tweak)
  - [ ] Layers 4-1: 256-bit keys (512-bit with XTS tweak)
  - [ ] Each layer: Whirlpool hash, Argon2id KDF
  - [ ] Master password → derived keys for all 5 layers (HKDF-Whirlpool)
  - [ ] Automated loop device management
  - [ ] Create ext4 filesystem on innermost layer
  - [ ] Verify cascade integrity post-creation
- [ ] Implement `encryptedwallet mount` for Linux
  - [ ] Single password input (user-friendly!)
  - [ ] Derive 5 layer keys from master password (HKDF-Whirlpool)
  - [ ] Auto-load kernel modules if needed
  - [ ] Open layers sequentially: layer5→layer4→layer3→layer2→layer1
  - [ ] Mount innermost layer to `/mnt/zcl_wallet`
  - [ ] Handle `sudo` prompts gracefully
  - [ ] Validate all 5 layers before declaring success
- [ ] Implement `encryptedwallet unmount` for Linux
  - [ ] Close layers in reverse: layer1→layer2→layer3→layer4→layer5
  - [ ] Verify each layer closes successfully
  - [ ] Secure cleanup (zero derived keys from memory)
- [ ] Error handling
  - [ ] Missing cipher support in kernel (suggest modprobe)
  - [ ] Permission errors (sudo failures)
  - [ ] Corrupted layer detection
  - [ ] Partial unmount recovery
  - [ ] Module loading failures

#### Windows/macOS-Specific (3-Layer VeraCrypt)
- [ ] Implement `encryptedwallet create` for Win/Mac
  - [ ] VeraCrypt with AES(Twofish(Serpent)) + Whirlpool
  - [ ] PIM configuration (default: 485, range: 485-2000)
  - [ ] Verify cipher cascade and hash in container header
- [ ] Implement `encryptedwallet mount` for Win/Mac
  - [ ] VeraCrypt mount with explicit cipher/hash verification
  - [ ] Automatic symlink creation/validation
  - [ ] Validate all 3 cipher layers are active
- [ ] Implement `encryptedwallet unmount` for Win/Mac
  - [ ] VeraCrypt dismount
  - [ ] Verify all 3 cipher layers are locked
- [ ] Error handling
  - [ ] VeraCrypt not installed
  - [ ] macFUSE not installed (macOS)
  - [ ] Wrong cipher/hash configuration detected
  - [ ] Mount failures (wrong password, already mounted)

#### Testing
- [ ] Unit tests for each platform
- [ ] **Linux**: Test all 5 cipher combinations independently
- [ ] **Linux**: Test Blowfish 448-bit key derivation
- [ ] **Linux**: Test key derivation (master → 5 layer keys, HKDF-Whirlpool)
- [ ] **Linux**: Test partial failure recovery (e.g., layer 3 fails to open)
- [ ] **Linux**: Test kernel module auto-loading (unload camellia, verify auto-load)
- [ ] **Win/Mac**: Test VeraCrypt cascade verification
- [ ] Integration tests (end-to-end workflows)
- [ ] Cross-platform container portability (Win ↔ Mac for VeraCrypt)
- [ ] **Linux**: Cannot port to Win/Mac (different formats)
- [ ] Keyfile functionality (creation, validation, usage)
- [ ] Failure scenarios (wrong password, missing keyfile, container corruption)
- [ ] Concurrent access prevention (attempt double-mount)
- [ ] Memory leak detection (valgrind on Linux, instruments on macOS)
- [ ] Memory scrubbing verification (dump process memory, search for keys/passwords)
- [ ] **Linux**: 1000-iteration mount/unmount cycle (all 5 layers)
- [ ] **Win/Mac**: 1000-iteration mount/unmount cycle
- [ ] **Linux**: Performance benchmark (5-layer vs 1-layer throughput)

### Phase 3 (Advanced Features)
- [ ] Auto-unmount timeout (configurable, default: 30min idle)
- [ ] **Linux**: Support for detached LUKS headers (plausible deniability)
- [ ] **Win/Mac**: Support for VeraCrypt hidden volumes (plausible deniability)
- [ ] Encrypted wallet migration tool (plaintext → encrypted)
- [ ] Keyfile management utilities (generation, validation)
- [ ] Emergency backup recovery procedures
- [ ] **Win/Mac**: Duress password support (opens decoy wallet)
- [ ] Benchmark tool (measure cascade performance on user's hardware)
- [ ] **Linux**: Custom cipher order selection (advanced users)
- [ ] **Linux**: Optional 6th layer (add user-selected cipher)

## Critical Implementation Notes

### Security Requirements
- `unloadwallet` MUST securely zero wallet encryption keys from memory (`OPENSSL_cleanse`)
- Symlink validation prevents TOCTOU attacks (verify readlink target exists on mounted volume)
- Container passphrase ≠ wallet passphrase (defense in depth)
- All password prompts MUST disable terminal echo
- Error messages MUST NOT leak sensitive information (e.g., which layer failed, cipher config)
- **Linux key derivation**: Use HKDF-Whirlpool to derive 5 independent layer keys from master password
  - `layer5_key = HKDF-Whirlpool(master_password, salt, "ZCL-LAYER5-BLOWFISH")` (448-bit output)
  - `layer4_key = HKDF-Whirlpool(master_password, salt, "ZCL-LAYER4-CAMELLIA")` (256-bit output)
  - `layer3_key = HKDF-Whirlpool(master_password, salt, "ZCL-LAYER3-AES")` (256-bit output)
  - `layer2_key = HKDF-Whirlpool(master_password, salt, "ZCL-LAYER2-TWOFISH")` (256-bit output)
  - `layer1_key = HKDF-Whirlpool(master_password, salt, "ZCL-LAYER1-SERPENT")` (256-bit output)
- **Linux**: Store salt in metadata file `~/.zclassic/wallet_encrypted/salt` (not secret, but needed)
- **PIM enforcement** (Win/Mac): Minimum PIM=485 (reject lower values)

### Platform-Specific Requirements

**Linux (5-Layer dm-crypt)**:
- cryptsetup 2.3.0+ (LUKS2, Argon2id support)
- Kernel crypto API support for:
  - `blowfish` module (universal)
  - `camellia` module (may need: `modprobe camellia_generic`)
  - `aes` module (built-in on most kernels)
  - `twofish` module (universal)
  - `serpent` module (universal)
  - `xts` module (XTS mode support, built-in)
  - `whirlpool` module (hash, may need: `modprobe wp512`)
- Check module availability: `cat /proc/crypto | grep -i <cipher_name>`
- Auto-load modules: zcl-cli should execute `modprobe camellia_generic wp512` if missing
- `sudo` access for cryptsetup operations
- Loop device support (for nested containers)
- Example 5-layer creation script logic:
  ```bash
  # Layer 5 (outermost - Blowfish-448)
  dd if=/dev/urandom of=wallet_layer5.luks bs=1M count=500
  cryptsetup luksFormat --type luks2 --cipher blowfish-xts-plain64 \
    --key-size 896 --hash whirlpool --pbkdf argon2id \
    --pbkdf-memory 1048576 --pbkdf-parallel 4 wallet_layer5.luks
  
  cryptsetup open wallet_layer5.luks layer5
  
  # Layer 4 (Camellia-256) - created INSIDE layer5
  dd if=/dev/urandom of=/dev/mapper/layer5 bs=1M count=400
  cryptsetup luksFormat --type luks2 --cipher camellia-xts-plain64 \
    --key-size 512 --hash whirlpool --pbkdf argon2id \
    /dev/mapper/layer5
  
  cryptsetup open /dev/mapper/layer5 layer4
  
  # ...  repeat for AES, Twofish, Serpent ... 
  
  # Final filesystem on innermost layer
  mkfs. ext4 -L ZCL_WALLET /dev/mapper/layer1
  ```

**Windows (VeraCrypt)**:
- VeraCrypt 1.25. 9 or later (latest stable recommended)
- AES(Twofish(Serpent)) cascade support verified
- Whirlpool hash support verified
- Command-line interface available
- VeraCrypt driver installed (requires one-time admin install)
- NTFS or exFAT filesystem (exFAT for cross-platform compatibility)
- UAC prompts may appear on first use
- Example VeraCrypt create command:
  ```cmd
  veracrypt --text --create wallet. tc ^
    --volume-type=normal ^
    --encryption=AES-Twofish-Serpent ^
    --hash=Whirlpool ^
    --filesystem=exFAT ^
    --size=524288000 ^
    --password="user_passphrase" ^
    --pim=485 ^
    --keyfiles=C:\secure\keyfile.dat ^
    --random-source=\Device\Null
  ```

**macOS (VeraCrypt)**:
- **CRITICAL**: macFUSE must be installed BEFORE VeraCrypt
- macFUSE download: https://osxfuse.github.io/
- **Apple Silicon (M1/M2/M3/M4)**: Requires Reduced Security mode
  - Boot to Recovery (hold power button)
  - Security Policy → Reduced Security
  - Allow kernel extensions from "Benjamin Fleischer" (macFUSE developer)
- VeraCrypt 1.25.9+ (compiled for Apple Silicon)
- exFAT filesystem recommended (native macOS support)
- First mount may require explicit Security & Privacy approval
- Example VeraCrypt create command:
  ```bash
  veracrypt --text --create wallet.tc \
    --volume-type=normal \
    --encryption=AES-Twofish-Serpent \
    --hash=Whirlpool \
    --filesystem=exFAT \
    --size=524288000 \
    --password="user_passphrase" \
    --pim=485 \
    --keyfiles=/Volumes/USB/keyfile.dat \
    --random-source=/dev/urandom
  ```

### Cryptographic Implementation Details

**Linux 5-Layer Cascade (dm-crypt)**:
- Each layer is a LUKS2 container
- XTS mode per layer: each sector encrypted with sector-specific tweak
- Key derivation chain:
  ```
  User password → Argon2id → Master key (512-bit)
  Master key → HKDF-Whirlpool → layer5_key (448-bit, Blowfish-XTS → 896-bit with tweak)
  Master key → HKDF-Whirlpool → layer4_key (256-bit, Camellia-XTS → 512-bit with tweak)
  Master key → HKDF-Whirlpool → layer3_key (256-bit, AES-XTS → 512-bit with tweak)
  Master key → HKDF-Whirlpool → layer2_key (256-bit, Twofish-XTS → 512-bit with tweak)
  Master key → HKDF-Whirlpool → layer1_key (256-bit, Serpent-XTS → 512-bit with tweak)
  ```
- **Total effective keyspace**: Blowfish 2^448 × Camellia 2^256 × AES 2^256 × Twofish 2^256 × Serpent 2^256
- Data flow (write operation):
  ```
  Plaintext → Serpent-XTS → Twofish-XTS → AES-XTS → Camellia-XTS → Blowfish-XTS → Ciphertext on disk
  ```

**Blowfish XTS Key Size Note**:
- Blowfish supports 32-448 bit keys (variable length)
- XTS mode doubles effective key material: 448-bit encryption + 448-bit tweak = 896-bit total
- cryptsetup `--key-size 896` specifies total XTS key material
- Actual Blowfish cipher uses 448 bits for encryption

**Windows/macOS (VeraCrypt)**:
- Each plaintext block processed through: Serpent → Twofish → AES
- Each cipher uses independent 256-bit key (768 bits total key material)
- Master key (derived via Whirlpool PBKDF2) split into three 256-bit subkeys
- No cipher sees plaintext from another cipher (intermediate ciphertext only)

**Key Derivation (All Platforms)**:
- **Linux**: Argon2id (memory-hard, GPU-resistant) → HKDF-Whirlpool for layer keys
  - Default: 4 iterations, 1GB memory, 4 parallel threads
  - Adjustable via `--iterations` flag
- **Windows/macOS**: PBKDF2-Whirlpool with PIM multiplier
  - Base iterations: 500,000
  - With PIM=485: 500,000 iterations (baseline)
  - With PIM=650: ~670,103 iterations
- Salt: 64 random bytes (generated during container creation)

**Performance Expectations**:
- **Linux 5-layer**:
  - Container creation: 60-120 seconds (5 LUKS headers + random data)
  - Mount time: 10-15 seconds (Argon2id + 5 layer key derivations)
  - Runtime overhead: ~5-7x vs single AES (still acceptable, kernel-level fast)
  - Hardware AES-NI: Reduces overhead on layer 3 (AES)
  - Throughput: ~200-400 MB/s on modern hardware (SSD bottleneck, not crypto)
  - Blowfish (no hardware accel) is slowest layer, but acceptable for wallet ops
- **Windows/macOS 3-layer**:
  - Container creation: 30-60 seconds
  - Mount time: 2-5 seconds (PBKDF2 + cascade decryption)
  - Runtime overhead: ~3x vs AES-only
  - Hardware AES-NI: Reduces overhead to ~2x

## Testing Strategy

### Unit Tests
- [ ] Password strength validator (entropy, length, character classes)
- [ ] Symlink creation/validation logic
- [ ] Container path resolution (cross-platform)
- [ ] **Linux**: HKDF-Whirlpool key derivation (test vectors, 448-bit for Blowfish)
- [ ] **Linux**: Cipher module availability checker
- [ ] **Linux**: Blowfish 448-bit key size validation
- [ ] Error message sanitization (no info leaks)

### Integration Tests
- [ ] **Linux**: End-to-end 5-layer: create → mount → load → transact → unload → unmount
- [ ] **Win/Mac**: End-to-end 3-layer: create → mount → load → transact → unload → unmount
- [ ] Keyfile functionality (creation, validation, usage)
- [ ] **Linux**: Argon2id iteration variation (test 1, 4, 8 iterations)
- [ ] **Win/Mac**: PIM variation (test range 485-2000)
- [ ] Failure scenarios (wrong password, missing keyfile, container corruption)
- [ ] **Linux**: Partial layer failure (e.g., layer 3 corrupted, recovery)
- [ ] **Linux**: Missing kernel module handling (unload camellia, verify auto-load)
- [ ] Concurrent access prevention (attempt double-mount)
- [ ] Memory leak detection (valgrind on Linux, instruments on macOS)

### Security Tests
- [ ] Memory scrubbing verification (dump process memory post-unload, search for keys/passwords)
- [ ] Timing attack resistance (constant-time password comparison)
- [ ] **Linux**: 5-layer cascade integrity (modify each layer individually, verify mount failure)
- [ ] **Win/Mac**: 3-layer cascade integrity (modify container, verify mount failure)
- [ ] TOCTOU attack simulation (symlink race conditions)
- [ ] Error message information leakage audit (which layer failed?)
- [ ] Side-channel analysis (power/timing during mount/unmount)
- [ ] **Linux**: Key derivation independence test (same password, different salts = different layer keys)
- [ ] **Linux**: Blowfish 448-bit key strength test (entropy analysis)

### Platform-Specific Tests
- [ ] **Linux**: 5-layer mount/unmount cycle (1000 iterations, all layers)
- [ ] **Linux**: Kernel module auto-loading (unload modules, verify zcl-cli loads them)
- [ ] **Linux**: Loop device exhaustion handling (open many containers)
- [ ] **Linux**: Blowfish performance benchmark (vs AES on same data)
- [ ] **Windows**: UAC interaction, drive letter assignment
- [ ] **macOS**: macFUSE interaction, Apple Silicon compatibility, SIP/Gatekeeper
- [ ] **macOS**: Reduced Security mode verification

### Performance Benchmarks
- [ ] **Linux**: Measure throughput (MB/s) for 1-cipher vs 5-cipher cascade
- [ ] **Linux**: Identify bottleneck cipher (likely Blowfish or Camellia)
- [ ] **Win/Mac**: Measure throughput for 3-cipher cascade
- [ ] **Linux**: Mount time scaling (test on slow vs fast hardware)
- [ ] **All**: Memory usage during mount (measure resident set size)

## User Documentation Outline

### Quick Start Guide

**Linux (5-Cipher Maximum Security):**
1.  Verify kernel crypto support: `zcl-cli encryptedwallet check-deps`
2. Create encrypted wallet: `zcl-cli encryptedwallet create --size=500`
   - Auto-loads Camellia module if needed
3. Mount wallet: `zcl-cli encryptedwallet mount` (single password!)
4.  Unmount wallet: `zcl-cli encryptedwallet unmount`

**Windows/macOS (3-Cipher High Security):**
1. Install VeraCrypt: https://www.veracrypt.fr/
2. (macOS only) Install macFUSE: https://osxfuse.github. io/
3. Create encrypted wallet: `zcl-cli encryptedwallet create --size=500`
4. Mount wallet: `zcl-cli encryptedwallet mount`
5. Unmount wallet: `zcl-cli encryptedwallet unmount`

### Security Best Practices
- Use 20+ character passphrase (diceware recommended: https://theworld.com/~reinhold/diceware.html)
- Store keyfile on separate USB device (airgapped from computer)
- **Linux**: Set Argon2id iterations ≥ 6 for long-term cold storage (slower mount, better security)
- **Win/Mac**: Set PIM ≥ 650 for long-term cold storage
- Backup encrypted container to offsite location (already encrypted, safe to store)
- Never store container password digitally (paper/metal backup only)
- **Linux advantage**: 5-cipher cascade + Blowfish 448-bit key provides maximum paranoia
- **Win/Mac**: Consider VeraCrypt hidden volumes for plausible deniability

### Cryptography Rationale

**Why 5 ciphers on Linux?**
- dm-crypt allows unlimited stacking
- **Algorithm diversity**: Blowfish (USA/Schneier), Camellia (Japan/NTT), AES (Belgium/USA), Twofish (USA/Schneier), Serpent (UK/Israel/Norway)
- **Design diversity**: Feistel networks (Twofish, Blowfish) + SPN (AES, Serpent, Camellia)
- **Extended keyspace**: Blowfish 448-bit key (longest available in standard crypto)
- **Trust distribution**: No single government or organization designed all ciphers
- Breaking requires compromising ALL 5 ciphers independently
- User-friendly: SINGLE PASSWORD unlocks all layers (key derivation)

**Why Blowfish for innermost layer?**
- Supports up to 448-bit keys (longest in cascade)
- 2^448 keyspace provides maximum brute-force resistance
- Well-analyzed since 1993 (Schneier design)
- No practical attacks despite 30+ years of cryptanalysis
- Slower than AES (no hardware accel) but acceptable for wallet operations
- Innermost position: attacker must break 4 other ciphers first

**Why only 3 ciphers on Windows/macOS?**
- VeraCrypt limitation (maximum 3-cipher cascade)
- VeraCrypt doesn't support Blowfish in cascade mode
- Still provides strong defense-in-depth
- Cross-platform container portability (Win ↔ Mac)

**Why Whirlpool? **
- No length-extension attacks (unlike SHA-2)
- Larger internal state (512-bit vs SHA-512's 256-bit)
- Conservative design for decades-long cold storage

**Quantum resistance:**
- AES/Serpent/Twofish/Camellia 256-bit keys: ~128-bit post-quantum security
- Blowfish 448-bit key: ~224-bit post-quantum security
- Grover's algorithm: quantum speedup sqrt(keyspace)
- 224-bit quantum security considered safe beyond 2100

### Troubleshooting

**Linux:**
- **"Cipher module not found"**: Auto-loading failed, manual: `sudo modprobe camellia_generic wp512 blowfish`
- **"Device busy"**: Check for open file handles: `lsof | grep mapper`
- **"Operation not permitted"**: Run with sudo: `sudo zcl-cli encryptedwallet mount`

Threat	Mitigation
AES cryptanalysis breakthrough	✅ Linux: 4 fallback ciphers; Win/Mac: 2 fallback ciphers
Single-cipher side-channel attacks	✅ Cascade masks timing/power characteristics
Algorithm backdoors (trust issues)	✅ Linux: 5 algorithms from different nations/teams
Filesystem forensics	✅ Linux: 5-cipher encryption; Win/Mac: 3-cipher encryption
Memory dumps (post-use)	✅ unloadwallet zeros sensitive data
Unauthorized disk access	✅ Whirlpool KDF (500k iterations) + Argon2id
Wallet. dat theft	✅ Encrypted at rest (requires container password)
Evil maid attacks	✅ PIM adds entropy; keyfiles on separate device
User operational errors	✅ zcl-cli automates mount/unmount/load/unload sequence
SHA-2 length-extension	✅ Whirlpool structurally immune
Brute-force attacks	✅ Linux: Blowfish 448-bit key = 2^448 keyspace (innermost layer)
Quantum computing (future)	⚠️ 256-bit symmetric keys provide 128-bit quantum security; 448-bit provides 224-bit
Rubber-hose cryptanalysis	❌ Out of scope; consider duress passwords/hidden volumes

ZCLIP 001 RFC: loadwallet & unloadwallet & dm-crypt/veracrypt logic flow for FULL wallet encryption integration #101

Description

ZCLIP 001 RFC: loadwallet & unloadwallet & cryptsetup/veracrypt logic flow for FULL wallet encryption integration

Overview

Phased Implementation

Phase 1: Wallet Load/Unload (Current Scope)

Phase 2: Full Wallet Encryption Integration

Cryptographic Parameters

Linux: 5-Layer dm-crypt Cascade

Windows/macOS: 3-Layer VeraCrypt Cascade

Hash Algorithm: Whirlpool (All Platforms)

Technical Workflow

Platform-Specific Security Considerations

Linux (5-Layer dm-crypt/LUKS Cascade)

Windows (VeraCrypt 3-Layer Cascade)

macOS (VeraCrypt 3-Layer Cascade)

Security Properties

Threat Model Mitigations

New zcl-cli Commands (Phase 2)

zcl-cli encryptedwallet create [options]

zcl-cli encryptedwallet mount

zcl-cli encryptedwallet unmount

zcl-cli encryptedwallet status

zcl-cli encryptedwallet backup <destination>

Operational Security Workflow (Simplified UX)

First-Time Setup

Daily Usage

Cold Storage Backup

Implementation Checklist

Phase 1 (loadwallet/unloadwallet)

Phase 2 (zcl-cli Encryption Integration)

Cross-Platform

Linux-Specific (5-Layer Cascade)

Windows/macOS-Specific (3-Layer VeraCrypt)

Testing

Phase 3 (Advanced Features)

Critical Implementation Notes

Security Requirements

Platform-Specific Requirements

Cryptographic Implementation Details

Testing Strategy

Unit Tests

Integration Tests

Security Tests

Platform-Specific Tests

Performance Benchmarks

User Documentation Outline

Quick Start Guide

Security Best Practices

Cryptography Rationale

Troubleshooting

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

ZCLIP 001 RFC: `loadwallet` & `unloadwallet` & `dm-crypt`/`veracrypt` logic flow for FULL wallet encryption integration #101

ZCLIP 001 RFC: `loadwallet` & `unloadwallet` & `cryptsetup`/`veracrypt` logic flow for FULL wallet encryption integration

`zcl-cli encryptedwallet create [options]`

`zcl-cli encryptedwallet mount`

`zcl-cli encryptedwallet unmount`

`zcl-cli encryptedwallet status`

`zcl-cli encryptedwallet backup <destination>`