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

Field	Type	Description
`status`	string	`ACTIVE`, `SUSPENDED`, or `REVOKED`
`exp`	string	ISO-8601 UTC expiration date
`meta`	object	Arbitrary metadata (tags, labels, etc.)

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

Method	Description
`createDexKey($dexAd, $userAD, $opts)`	Create a new DEX with optional metadata
`getDexMeta($dexBlob, $dexAd)`	Read DEX metadata without revealing the private key
`encryptWithDex($dexBlob, $dexAd, $plaintext)`	Encrypt data using a DEX
`decryptWithDex($dexBlob, $dexAd, $ciphertext)`	Decrypt data using a DEX
`rotateDexMasterKey($dexBlob, $currentDexAd, $newMasterKeyB64, $newDexAd = null)`	Re-encrypt DEX with a new master key
`rekeyDexUserKey($dexBlob, $dexAd)`	Regenerate internal DEX key

🧿 Example Workflow

System initialization

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

Create a user DEX

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

Encrypt user data

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

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

jnativel / sentinel-vault

Maintainers

Details