README

A modern, high-security PHP 8.4+ envelope encryption library using Libsodium.

php-vault implements the envelope encryption pattern: every record is encrypted with a unique Data Encryption Key (DEK), which is then protected by a Master Key (KEK). This ensures that even if one record is compromised, the rest remain secure, and master keys can be rotated without re-encrypting entire datasets.

Features

• Envelope Encryption: Unique DEK per record.
• Libsodium Powered: Uses xchacha20poly1305_ietf for data and secretbox for keys.
• Memory Safe: Automatically wipes keys from memory (sodium_memzero) when objects are destroyed.
• Leak Proof: Redacts sensitive information in debug dumps (var_dump, print_r).
• Field-Level Protection: Easily encrypt specific fields in associative arrays.
• Key Rotation: Re-encrypt DEKs with a new Master Key without touching the plaintext data.
• Zero Dependencies: Pure PHP 8.4+ logic using native extensions.

Installation

composer require fr3on/php-vault

Usage

Basic Seal/Open

use Fr3on\Vault\Vault;
use Fr3on\Vault\Kek\LocalKek;

$kek = new LocalKek($masterKeyBytes); // 32 bytes
$vault = new Vault($kek);

$sealed = $vault->seal("Sensitive Transaction Data");
// "v1:AAE... (Base64URL encoded envelope)"

$plaintext = $vault->open($sealed);

Field-Level Encryption

use Fr3on\Vault\FieldVault;

$fieldVault = new FieldVault($vault);
$record = [
    'user_id' => 123,
    'email'   => 'user@example.com', // sensitive
    'ssn'     => '000-00-0000',      // sensitive
];

$sealed = $fieldVault->sealFields(['email', 'ssn'], $record);
// Only 'email' and 'ssn' are encrypted; 'user_id' remains plaintext.

Key Rotation

use Fr3on\Vault\KeyRotator;

$rotator = new KeyRotator();
$newKek = new LocalKek($newMasterKey);

// Rotate the master key without decrypting the payload
$newSealed = $rotator->rotate($oldSealed, $oldKek, $newKek);

Security Standards

• PHP 8.4+ required for modern security features.
• Level 9 PHPStan for total type safety.
• IND-CCA2 Secure: Uses AEAD for all data payloads.
• Tamper Evident: Throws exceptions if any bit of the envelope is modified.

License

MIT License. See LICENSE for details.