Download the PHP package phpnomad/encryption without Composer

phpnomad/encryption

Encryption contracts for PHPNomad — bring your own cipher via an integration package. This package holds only the strategy and key-provider interfaces, the immutable encrypted-value model, the key providers, and the exception types. It makes no assumption about how you store or transport an encrypted value — no serialization format, no column shape. It has no cipher dependency (no ext-sodium, no framework, no ORM) — just PHP.

The default cipher lives in a separate integration: phpnomad/sodium-integration (libsodium XChaCha20-Poly1305 AEAD).

• Contract-first. EncryptionStrategy and KeyProvider are the seams; swap ciphers or key sources without touching call sites.
• Context binding. The contract requires ciphertext to be bound to a caller context (associated data), so a value copied elsewhere won't decrypt.
• Key rotation built in. Keys are versioned; encrypt with the current version, decrypt against whatever version sealed the data.
• Storage-agnostic. EncryptedValue is pure data — ciphertext, nonce, key version, and an opaque cipher tag. How you persist it is entirely yours.

Requirements

• PHP >= 8.2
• A cipher implementation — e.g. phpnomad/sodium-integration.

Install

phpnomad/encryption gives you the contracts; phpnomad/sodium-integration gives you the SodiumEncryptionStrategy to wire in.

Quickstart

Generate a base64 key for your environment:

Where keys come from — an env var, a file, a KMS — is your application's concern: implement Interfaces\KeyProvider (two methods) however you load them. ArrayKeyProvider is the in-memory primitive when you already hold the raw keys.

Associated data (AEAD context)

The second argument to encrypt()/decrypt() is associated data: authenticated but not encrypted. Use it to bind a ciphertext to where it lives. The same context must be supplied to decrypt.

This turns an encrypted-value swap between rows or columns from a silent success into a hard failure. If you encrypt several fields on one record, give each its own context (e.g. "record:{id}:{field}") so ciphertexts can't be swapped between columns.

Key rotation

Keys are addressed by version. Keep every version still referenced by stored ciphertext; point the ring's current version at the newest key.

To fully migrate, decrypt each stored value and re-encrypt it (the new EncryptedValue carries keyVersion = 2), then retire the old key once nothing references it. Multiple keys can also live behind separate providers via KeyRing (one KeyProvider per version).

Writing a cipher integration

Implement Interfaces\EncryptionStrategy and return an EncryptedValue, stamping your own opaque cipher discriminator so decrypt-time can recognize it:

The contract requires that decryption fail (throw DecryptionFailedException) on a wrong key, a mismatched $context, or tampered bytes, and that it decrypt against the key version recorded on the value. The cipher discriminator is owned by the strategy, not this package — the contract names no ciphers. See phpnomad/sodium-integration for the reference implementation.

API at a glance

Testing

The contract suite has no cipher dependency — it exercises the strategy contract against a small in-package reversible fake. The real libsodium cipher is tested in phpnomad/sodium-integration.

License

MIT © Novatorius / Alex Standiford