[TomK]

encrypter accepts only one AES-128 key, so replacing [security] encryption_key makes everything encrypted under the old key (e.g. cookies) undecryptable at once.

EncryptionService now binds Cubex\Encryption\Encrypter, a standalone implementation of Illuminate\Contracts\Encryption\Encrypter. It reads and writes exactly the illuminate/encryption 5.x payload: base64(json({iv, value, mac})), openssl AES-CBC, HMAC-SHA256 MAC checked with the same double-HMAC comparison. It throws the contracts' DecryptException/EncryptException, so Illuminate\Cookie\Middleware\EncryptCookies works unchanged and existing cookies keep decrypting. illuminate/encryption moves to require-dev (tests only), and illuminate/contracts becomes a direct requirement (it was already pulled in by container/support/cookie). The bound object is no longer an instance of Illuminate\Encryption\Encrypter; code that type-hints the contract is unaffected.

encryption_key can be a key or a list. The first key is current: it encrypts, is returned by getKey(), and is tried first on decrypt. Later keys are only used to decrypt, in order, and the first failure is rethrown if none match. Each key's cipher follows its length: 16 bytes is AES-128-CBC, 32 bytes is AES-256-CBC, anything else throws at boot. There is no cipher setting.

[security]
encryption_key[] = {{ENV:COOKIE_ENCRYPTION_KEY}}   ; 32 chars, AES-256-CBC
encryption_key[] = <old 16-char key>               ; AES-128-CBC, decrypt only

A single 16-byte string key behaves as before. Empty later entries are ignored. An empty first entry throws instead of promoting an old key, so an unset env var can't cause new data to be encrypted with a retired key. A missing item or [] uses the existing default key.

Fallback keys are usually being retired because they're compromised, so anything that decrypts with one may be forged. Keep the window short and don't base security decisions on cookie contents during it; consumers can re-issue cookies to move them onto the current key. decrypt() still calls plain unserialize() like Illuminate's; untrusted input should use $unserialize = false with allowed_classes => false.

Test plan

EncrypterTest checks compatibility against the real illuminate/encryption 5.5.44 in both directions for AES-128-CBC and AES-256-CBC, covering serialized values, $unserialize = false and the *String methods. It also covers:

• the payload format
• a tampered MAC or value throwing, and malformed payloads throwing
• implementing the contract
• string and list keys, first key encrypts, fallback decrypts, and a 32-byte current key with a 16-byte fallback decrypting an old AES-128 payload
• no match throwing
• empty-entry rules, and bad key lengths throwing

EncryptionServiceTest covers string, list, 32-byte, missing and [] config.

Results on PHP 7.4 with this branch's own dependencies (PHPUnit 6.5):

• Full suite: 323 tests. The 40 encryption and service manager tests pass. The only 2 errors are the ReflectionType::__toString() deprecations in CubexTest, which fail the same way on 2.6.8.
• Install without dev dependencies: a --no-dev install leaves out illuminate/encryption, and the encrypter still works there.

Rollout

1. Release 2.6.9 from 2.0 with gh release create.
2. megameld bumps cubex/framework and sets encryption_key[] to the new 32-char env key first and the old 16-char key second.
3. After a short window, remove the old key entry.

🤖 Generated with Claude Code

[TomK]

Superseded by #73, which rebuilds this on v2-php74 (target 2.7.0) with a sodium-based format and a decrypt-only path for existing illuminate/encryption payloads. Closing rather than force-pushing so this history stays readable.