Key Backup & Restoration

Overview

Cryptographic keys (consensus keys, identity keys, encryption keys) are backed up automatically after each generation or rotation event. Each backup is AES-256-GCM encrypted and distributed to multiple vault locations. When restoring, restore_keys() verifies SHA-512 integrity before decrypting and applying keys to the system.

Key property: Even if one vault is compromised, the plaintext keys are protected by AES-256-GCM. Even if the ciphertext is tampered, the SHA-512 integrity check prevents decryption of corrupted data.

Flow Diagram — Backup

sequenceDiagram
    autonumber
    participant Trigger as ⚙️ Key Generation / Rotation
    participant KBM as 🔑 KeyBackupManager
    participant AES as 🔐 AES-256-GCM
    participant FS as 📁 File System / Vault

    Note over Trigger: New key created (MSP cert issue, consensus rotation)

    Trigger->>KBM: backup_keys(public_key, private_key, key_type)
    KBM->>KBM: Sanitize key_type → backup_id = "{key_type}_{timestamp}"

    rect rgb(0, 0, 0, 0)
        Note over KBM,AES: Phase 1 — Encryption
        KBM->>AES: _encrypt_backup_data({ public_key, private_key, ... }, encryption_key)
        Note right of AES: nonce = secrets.token_bytes(12)<br/>ciphertext = AESGCM.encrypt(nonce, json_data, aad)<br/>output = nonce || ciphertext
        AES-->>KBM: encrypted_data (bytes)
    end

    rect rgb(0, 0, 0, 0)
        Note over KBM,FS: Phase 2 — Write & Integrity Verify
        KBM->>FS: write {backup_id}.enc to primary vault
        KBM->>KBM: _calculate_integrity_hash(encrypted_data) → SHA-512
        KBM->>KBM: _verify_integrity(backup_file, expected_hash) → confirm write OK
    end

    rect rgb(0, 0, 0, 0)
        Note over KBM,FS: Phase 3 — Distribution & Metadata
        KBM->>FS: _distribute_to_locations(file, backup_id, locations)
        Note right of FS: Copy to secondary_vault, tertiary_vault, ...<br/>Each = separate directory / remote path
        FS-->>KBM: distributed_locations []

        KBM->>KBM: _update_metadata(backup_id, { timestamp, key_type, hash, locations, file_path })
        KBM->>KBM: _cleanup_old_backups() — remove backups older than retention_period days
    end
    KBM-->>Trigger: backup_id ✅

Flow Diagram — Restoration

sequenceDiagram
    autonumber
    participant Trigger as ⚙️ Disaster Recovery
    participant KBM as 🔑 KeyBackupManager
    participant AES as 🔐 AES-256-GCM
    participant FS as 📁 File System / Vault

    Trigger->>KBM: restore_keys(backup_id)
    rect rgb(0, 0, 0, 0)
        Note over KBM,FS: Phase 1 — Locate & Integrity Check
        KBM->>FS: _find_backup_file(backup_id)<br/>Search primary vault, then distributed locations
        FS-->>KBM: backup_file path

        KBM->>KBM: _get_backup_hash(backup_id) → expected_hash from metadata
        KBM->>KBM: _calculate_integrity_hash(file_content) → actual_hash
    end

    alt Integrity OK (actual == expected)
        KBM->>AES: _decrypt_backup_data(encrypted_data, encryption_key)
        AES-->>KBM: { public_key, private_key, key_type }
        KBM->>KBM: _validate_keys(public_key, private_key, key_type)
        KBM->>KBM: _apply_restored_keys(public_key, private_key, key_type)
        KBM-->>Trigger: { public_key, private_key } ✅
    else Integrity FAIL (tampered or corrupted)
        KBM-->>Trigger: raise IntegrityError ❌
        Note over KBM: Log corruption, try next vault location
    end

Multi-Vault Failover

flowchart LR
    RESTORE["restore_keys(backup_id)"]
    V1["📁 Primary Vault\n_find_backup_file()"]
    V2["📁 Secondary Vault\n(fallback)"]
    V3["📁 Tertiary Vault\n(fallback)"]
    OK["✅ Decrypted Keys"]
    ERR["❌ IntegrityError\nAll vaults failed"]

    RESTORE --> V1
    V1 -->|Found + intact| OK
    V1 -->|Not found / tampered| V2
    V2 -->|Found + intact| OK
    V2 -->|Not found / tampered| V3
    V3 -->|Found + intact| OK
    V3 -->|Not found / tampered| ERR

Step-by-Step Breakdown

Backup Configuration

Error Handling

Key Classes & Methods

Related

• MSP Identity — certificate issuance triggers key backup
• Cluster Lockdown — lockdown may require key rotation, triggering this workflow
• IPFS Storage — uses the same AES-256-GCM encryption pattern