Download the PHP package temant/encryption-manager without Composer

Temant Encryption Manager

Temant Encryption Manager is a small, focused authenticated-encryption (AEAD) library for PHP, built exclusively on AES-GCM. It provides a simple API for encrypting and decrypting strings and files, with two independent key-derivation modes and support for key rotation and large-file streaming.

• AES-256-GCM or AES-128-GCM only — no legacy unauthenticated modes (CBC/ECB) to misuse.
• Two key-derivation modes: HKDF-SHA256 for high-entropy app secrets, PBKDF2-SHA256 (with a per-message random salt) for human passwords.
• Versioned, self-describing payloads — encrypted strings are safe to store as text.
• Key rotation — decrypt data encrypted under a previous app secret via a retired-key keyring.
• Streaming file encryption — encrypt/decrypt large files in fixed-size chunks with constant memory usage.

Installation

Requires PHP ^8.5 and the openssl extension.

Usage

Encrypting strings (app secret)

encryptString() returns a versioned, printable payload (v1: + base64) safe to store in a database column or JSON field.

Encrypting strings with a password

Pass a password as the second argument to switch to PBKDF2-based key derivation with a random per-message salt, instead of the app-secret-derived key:

Custom configuration

Cipher choice, PBKDF2 iteration count, salt/tag sizes, and the HKDF info string are all configurable via EncryptionConfig:

A manager only decrypts payloads produced with a matching cipher — mixing AES_128_GCM and AES_256_GCM payloads under one manager instance throws. pbkdf2Iterations, saltBytes, and tagBytes must all be positive integers; EncryptionConfig validates this at construction time and throws EncryptionException immediately rather than failing cryptically later inside OpenSSL.

Key rotation

Rotating your app secret doesn't have to invalidate previously-encrypted data. By default, updateSecret() keeps the old secret in an in-memory keyring, so old payloads stay decryptable:

To rotate without keeping the old secret around (immediately invalidating old data), pass retireCurrent: false:

If your process restarts and needs to rebuild the keyring (e.g. from a secrets manager), pass retired secrets at construction time or add them later:

Key rotation only applies to app-secret mode. Password-mode encryption always derives its key from the password you pass in, so there's nothing to rotate on the manager itself.

File encryption

For small files, encryptFile()/decryptFile() load the whole file into memory and reuse the same versioned payload format as encryptString():

Streaming file encryption (large files)

For large files, use encryptStreamedFile()/decryptStreamedFile() instead. They process the file in fixed-size chunks (default 64 KB) instead of loading it fully into memory, and use a distinct binary chunked format — not interchangeable with encryptFile()/decryptFile():

Each chunk is independently authenticated, and the chunk index plus a "final chunk" flag are bound into that chunk's nonce. This means truncating, reordering, duplicating, or splicing chunks is detected as an authentication failure during decryption rather than silently producing corrupted output.

Error handling

All failures — invalid payloads, tampered ciphertext, wrong passwords, cipher mismatches, missing files, I/O errors — throw Temant\EncryptionManager\EncryptionException:

Running Tests

License

This project is licensed under the MIT License.