README

SentinelVault is a standalone PHP class providing a lightweight Key Management System (KMS).
It securely handles encryption, decryption, and user-specific Data Encryption Keys (DEX), all protected by a master key.

🔐 Features

• XChaCha20-Poly1305 AEAD encryption (via PHP libsodium)
• Master key encryption model (MASTER_KEY_B64)
• Per-user Data Encryption Keys (DEX), each sealed with the master key
• Associated Data (AD) support for contextual encryption
• Status / Expiration / Metadata fields for key lifecycle management
• Key rotation: re-encrypt DEX with a new master key
• Rekeying: regenerate internal DEX keys while preserving metadata

🧩 Architecture Overview

Master Key (KMS Root)
     │
     ├── DEX Key (per user/context)
     │      - privateKeyB64 (32 bytes)
     │      - associatedData
     │      - exp / status / meta
     │
     └── Encrypted user data (via DEX key)

DEX JSON structure (before encryption)

{
  "kty": "DEX",
  "ver": 1,
  "privateKeyB64": "<base64-32-bytes>",
  "associatedData": "user:123:scope:profile",
  "created_at": "2025-10-29T12:34:56Z",
  "exp": "2026-01-01T00:00:00Z",
  "status": "ACTIVE",
  "meta": { "label": "Main profile" }
}

⚙️ Installation

Requirements

• PHP 8.2+
• ext-sodium enabled
• No external dependencies

Usage

use SentinelVault\SentinelVault;

// Initialize the vault
$vault = (new SentinelVault())
    ->setMasterKeyB64($_ENV['MASTER_KEY_B64']);

// Generate a DEX key for a user
$dex = $vault->createDexKey(
    'dex:user:123:key:main',
    'user:123:scope:profile',
    ['exp' => '2026-01-01T00:00:00Z', 'status' => 'ACTIVE']
);

// Encrypt and decrypt user data
$cipher = $vault->encryptWithDex($dex['dex_blob'], 'dex:user:123:key:main', 'Sensitive Data');
$plain  = $vault->decryptWithDex($dex['dex_blob'], 'dex:user:123:key:main', $cipher);

🕓 DEX Lifecycle Management

Metadata fields

Access control

When using encryptWithDex() or decryptWithDex():

• If status is SUSPENDED or REVOKED, operation fails.
• If exp date is in the past, operation fails.

🔁 Master Key Rotation

Rotate all stored DEX blobs when the master key changes.

$newDexBlob = $vault->rotateDexMasterKey(
    $oldDexBlob,
    'dex:user:123:key:main',
    $_ENV['NEW_MASTER_KEY_B64'],
    'dex:user:123:key:main:v2'
);

♻️ DEX Rekeying

Regenerate the internal user encryption key while keeping metadata intact.

$rekeyedDexBlob = $vault->rekeyDexUserKey($dexBlob, 'dex:user:123:key:main');

🧪 DEX Metadata Access

You can safely read non-sensitive information from a DEX without exposing its internal key.

$meta = $vault->getDexMeta($dexBlob, 'dex:user:123:key:main');
print_r($meta);

🧱 Security Design

• The master key never leaves the environment (MASTER_KEY_B64 in .env or secret manager).
• Each DEX is sealed using AEAD (XChaCha20-Poly1305) with unique associated data.
• Each user data chunk is encrypted with its own per-DEX key, isolated from others.
• AEAD ensures authentication: ciphertext tampering causes decryption to fail.
• status and exp ensure fine-grained key control for suspension and expiration.

🧰 Advanced Operations

🧿 Example Workflow

1. System initialization

   $master = SentinelVault::generateMasterKeyB64();
   putenv("MASTER_KEY_B64=$master");

2. Create a user DEX

   $dex = $vault->createDexKey("dex:user:1:key:default", "user:1:data");

3. Encrypt user data

   $cipher = $vault->encryptWithDex($dex['dex_blob'], "dex:user:1:key:default", "hello world");

4. Rotate master key later

   $new = SentinelVault::generateMasterKeyB64();
   $vault->rotateDexMasterKey($dex['dex_blob'], "dex:user:1:key:default", $new);

🧠 Design Principles

• Simple, self-contained, no external dependencies.
• One class = one KMS engine.
• Secure by design: AEAD, zero-copy key handling, context binding via AD.
• Extensible for multi-tenant or multi-service contexts.

🧭 Operational Separation & Service Model (Recommended)

For stronger security, run SentinelVault in an isolated environment, separate from your main application.

Why

Running the vault as an independent service ensures that even if your app is compromised, attackers cannot access the master key or decrypt sensitive data.
It also allows independent deployment, scaling, auditing, and key rotation.

How

• Deploy SentinelVault as a dedicated container, host, or microservice.
• Expose only a minimal internal API (private network or mTLS) to handle DEX creation and encryption/decryption.
• Keep the master key outside your project files — use environment secrets, HSM, or a managed KMS.
• The main app never stores or reads the master key; it only calls the API.

Example API endpoints

POST /dex       → create new DEX
POST /encrypt   → encrypt with DEX
POST /decrypt   → decrypt with DEX
POST /rotate    → rotate master key or DEX AD
POST /rekey     → regenerate DEX internal key
GET  /dex/meta  → retrieve DEX metadata

Summary

Separating SentinelVault from your main stack:

• Prevents direct access to cryptographic materials
• Reduces attack surface and lateral movement risk
• Simplifies auditing, compliance, and recovery

📄 License

MIT License (c) 2025 Jimmy NATIVEL