[EPIC](crypto) Internal Versioned Key (IVK) Management (with Per-Version Algorithm Selection & Automatic L2.x Rotation)

[nnicora]

📋 Overview

User Story: I want to implement the IVK (Internal Versioned Key) module so that OpenKCM can securely generate, store, rotate, decrypt, and version the symmetric key used for encrypting all tenant L2 keys.

Context: The IVK module manages the lifecycle of keys that protect tenant-specific L2 keys. By introducing versioning at this layer, OpenKCM can upgrade cryptographic standards (e.g., AES to ChaCha20) and rotate keys without rotating the immutable MasterKey.

---

🎯 Business Value

• Isolation Boundary: Protects L2.x keys, which are the fundamental isolation boundary of the system.
• MasterKey Stability: Decouples key rotation from the MasterKey, which must never rotate.
• Cryptographic Agility: Supports algorithm evolution (AES, ChaCha20, Post-Quantum) without redesign.
• Compliance: Ensures OpenKCM meets evolving cloud security and regulatory standards.

---

🏗️ Technical Architecture

1. Key Lifecycle State Machine

Each IVK version transitions through a strictly managed lifecycle to ensure data availability during migrations:

• Active: The current version used for new encryption and all decryption.
• Deprecated: Previous version; used only for decryption during the L2 migration window.
• Retired: Archived version; no longer used by any active L2 keys.

2. Encryption Schema

The IVK material is never stored in plaintext. It is wrapped by the MasterKey:
encrypted_blob = Encrypt(MasterKey, IVK_Material)

3. Metadata Structure

Each version record in the keystore (PostgreSQL/OpenBao) must contain:

• ivk_version: Sequential integer.
• algorithm_metadata: Algorithm ID, Key Size, Cipher Mode.
• status: Active, Deprecated, or Retired.
• material: Encrypted blob + integrity tag/checksum.
• timestamps: Created at, rotated at.

---

🚀 Functional Requirements

Milestone 1: Core IVK Management & Dispatcher

• Implement secure IVK generation with selectable algorithms.
• Develop a Dynamic Dispatcher to route encrypt/decrypt calls to the correct algorithm routine based on IVK version.
• Integrate with MasterKey (Seal/Shamir) for IVK loading and decryption.

Milestone 2: Transactional Rotation Logic

• Implement atomic rotation: Generate IVK.(n+1), set as Active, and demote IVK.n to Deprecated.
• Implement concurrency guards to prevent overlapping rotation operations.

Milestone 3: Automated L2 Re-encryption Queue

• Create a background worker to process the "L2 Re-encryption Queue."
• Implement idempotent migration: Decrypt L2 with IVK.n -> Encrypt L2 with IVK.(n+1) -> Update metadata.
• Ensure "mixed-state" support where the system seamlessly handles L2 keys on multiple IVK versions.

---

🛡️ Non-Functional Requirements (NFRs)

• Security: - Mandatory Memory Zeroization of plaintext IVK material immediately after use.
  • Failsafe algorithm mismatch detection.
• Performance: - IVK generation latency < 100ms.
  • High-throughput batch processing for L2 re-encryption.
• Resilience: - Full recovery from interrupted rotations.
  • Idempotent task processing.

---

✅ Acceptance Criteria

• System generates IVK versions with arbitrary algorithms (AES-GCM, ChaCha20, etc.).
• Activating a new IVK version triggers an automated, auditable L2 re-encryption migration.
• Historical IVK versions remain decryptable until all dependent L2 keys are migrated.
• Rotation process is atomic and failsafe against system restarts.
• No sensitive material is exposed in audit logs.