Download the PHP package nzo/url-encryptor-bundle without Composer

NzoUrlEncryptorBundle

A Symfony bundle that encrypts the values you put in a URL, and decrypts them before they reach your controller.

Your users see /invoice/AbC3x... instead of /invoice/42. They cannot read the value, and they cannot change it: a value that was modified is refused.

It also encrypts any other value, for example a secret you store in a database.

Which version do I need?

The documentation of version 6 is on the 6.x branch.

Coming from version 6? Read UPGRADE-7.0.md first: the encrypted values have a new format.

Installation

Without Symfony Flex, register the bundle yourself:

Then give it a secret key:

Generate the key once, and keep it out of your repository:

That is all you need. Every other option has a safe default.

Usage

In a Twig template

Encrypt the value when you build the link:

nzo_encrypt and nzo_decrypt exist as filters and as functions:

nzo_decrypt throws an exception when the value cannot be decrypted, so the page fails. Decrypt in the controller when the value comes from the user.

In a controller

List the parameters to decrypt. They are decrypted before your action runs:

#[ParamEncryptor(['id'])] does the opposite: the action receives the encrypted value. For a single parameter, #[ParamDecryptor('id')] is enough.

Each parameter is looked up in the route parameters first, then in the request body. To also look in the query string (?id=...), enable query_string_params.

If a value cannot be decrypted, because someone changed it or made it up, the response is a 404. Your action is not called.

As a service

decrypt() never returns a wrong value: it returns what was encrypted, or it throws.

Going further

Keep a link from being reused elsewhere

By default, the encrypted form of 42 is accepted by every action that decrypts an id: a link to invoice 42 also opens order 42.

Give each kind of link a context, any name you like, and use the same one on both sides:

A value encrypted for another context, or for none, gives a 404.

Bind a stored value to its owner

The context is also the second argument of the service. Use it to tie a value to a user, a tenant or a record:

A value copied from one user to another is refused. The context is not secret and is not stored in the encrypted value.

Get the same output every time

By default, encrypting the same value twice gives two different outputs. This is the safest behaviour.

If you need a stable output, for a URL that must not change or to search a column by its encrypted value, disable random_pseudo_bytes and set a secret_iv:

The trade-off: anyone who sees two outputs can tell whether they hide the same value.

Change the secret key

Put the new key in secret_key and move the old one to previous_secret_keys:

New values are encrypted with the new key. Values encrypted with the old one are still decrypted, so nothing breaks for your users.

For values you store, needsReencryption() tells you which ones to encrypt again:

Once nothing uses the old key any more, remove it.

Configuration reference

A key or an IV written in the configuration file is limited to 100 characters. Read from the environment, it has no limit.

cipher_algorithm accepts the OpenSSL algorithms that work with a key and an IV, such as aes-256-ctr or aes-256-cbc. GCM, CCM, OCB and ChaCha20-Poly1305 are refused: the bundle already authenticates every value, whatever the algorithm. Changing the algorithm makes the existing values unreadable.

On PHP 8.1, only the AES, ARIA and Camellia algorithms are available.

How it is protected

• Each value is encrypted with a new random IV (unless you asked for a stable output), then signed with HMAC-SHA256 (encrypt-then-MAC). The signature is checked before anything is decrypted.
• The encryption key and the signing key are two different keys, both derived from your secret_key with HKDF.
• A value encrypted with one algorithm, one key or one context is never accepted with another.
• The service cannot be serialized and hides its keys from a dump, so they do not leak into a session, a cache or a log.

The security of all this is the security of your key. Use a random one, as shown in the installation.

License

This bundle is under the MIT license. See the LICENSE file.