Download the PHP package initphp/encryption without Composer
On this page you can find all versions of the php package initphp/encryption. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download initphp/encryption
More information about initphp/encryption
Files in initphp/encryption
Package encryption
Short Description Secure, modern symmetric encryption for PHP built on top of OpenSSL and libsodium.
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package encryption
initphp/encryption
Secure, modern symmetric encryption for PHP on top of OpenSSL and libsodium.
Why
PHP's encryption primitives are powerful but unforgiving. Pick the wrong cipher, mix up IV and HMAC ordering, forget constant-time comparison, or hand libsodium a 14-byte "key" and you ship a vulnerability — or, more often, a silent failure that "works on my machine".
This package wraps ext-openssl and ext-sodium behind a small, opinionated
API:
- Authenticated by default. OpenSSL uses encrypt-then-MAC; Sodium uses the built-in AEAD construction.
- Keys of any non-empty length are accepted and derived to the size the primitive actually requires.
- Ciphertexts are self-describing: a 2-byte header (version + serializer flag) lets the library reject malformed or out-of-date input with a clear error instead of returning garbage.
- A single
EncryptionExceptioncovers every failure mode, so atry/catchis enough to handle all error paths. - JSON is the default payload serializer, so the historical
unserialize()-on-attacker-controlled-bytes pitfall is closed by default.
Requirements
- PHP 8.1 or higher
ext-opensslfor the OpenSSL handlerext-sodiumfor the Sodium handler
Both extensions ship with mainstream PHP distributions, but the package only loads the one you actually instantiate — you can use one handler without the other being available.
Installation
Quickstart
The Sodium handler has the same surface:
Configuration
Every option is optional except key. Unknown keys are ignored. Keys are
case-insensitive on input ('CIPHER' and 'cipher' are the same option).
| Option | Used by | Default | Description |
|---|---|---|---|
key |
both | required | The user-supplied secret. Any non-empty string; the handler derives a key of the correct length internally. |
cipher |
OpenSSL | AES-256-CTR |
Any algorithm from openssl_get_cipher_methods(). |
algo |
OpenSSL | SHA256 |
Any algorithm from hash_hmac_algos(). Used both for HKDF key derivation and for the HMAC tag. |
blocksize |
Sodium | 16 |
Block size for sodium_pad() / sodium_unpad(). Must be a positive integer. |
serializer |
both | 'json' |
One of 'json', 'php_serialize', 'php', 'serialize'. See Serialization. |
Options can be set in three places, in order of precedence (highest wins):
Per-call options do not mutate the handler — they are merged into a fresh array for that single call only.
Serialization
encrypt() accepts mixed and round-trips the value through a serializer
chosen via the serializer option. The flag is embedded in the ciphertext, so
decrypt() always restores the original type without you having to track the
choice yourself.
serializer value |
On-the-wire flag | Behaviour |
|---|---|---|
'json' (default) |
0x00 |
Uses json_encode/json_decode with JSON_THROW_ON_ERROR. Safe: no PHP class is ever instantiated during decoding. Cannot carry raw binary bytes — use php_serialize if you need that. |
'php_serialize', 'php', 'serialize' |
0x01 |
Uses serialize()/unserialize() with ['allowed_classes' => false]. Round-trips scalars, arrays and binary strings; custom objects degrade to __PHP_Incomplete_Class on decode. |
The PHP serializer is opt-in for one reason only: even though we always pass
allowed_classes:false, the safer default lets you not have to think about
object-injection vectors at all.
Writing a Custom Handler
Extend BaseHandler (not OpenSSL / Sodium — those are final) and
implement encrypt() and decrypt():
BaseHandler gives you resolveOptions(), requireKey(),
serializerFlag(), serializePayload() and unserializePayload() for free,
so you only write the cryptographic glue.
Error Handling
Every failure path raises InitPHP\Encryption\Exceptions\EncryptionException
(which extends \RuntimeException). A single catch covers everything:
Notable messages you may see:
Unsupported ciphertext format version 0x01; expected 0x02. Ciphertexts produced by 1.x are not readable by 2.x.HMAC verification failed; ciphertext is corrupted or has been tampered with.Sodium decryption failed; ciphertext is corrupted or has been tampered with.The "key" option is required and must be a non-empty string.Unknown OpenSSL cipher "…".
Security Notes
- Key management is your job. Store the key outside the code repository — environment variable, secret manager, KMS, etc. — and rotate it like any other secret.
- Key strength matters. The handler accepts any non-empty user key and
derives one of the right length, but it cannot add entropy that the input
does not contain. Use a random 256-bit string (
bin2hex(random_bytes(32))) in production rather than a passphrase. - Authentication is always on. OpenSSL ciphertexts include an HMAC of the header, IV, and ciphertext; Sodium uses its built-in AEAD. There is no "encrypt without authenticate" mode.
- Format is versioned. The first byte of every ciphertext identifies the format. A future major release that changes the layout will bump this byte and reject older ciphertexts with a clear error.
- Found something concerning? See SECURITY.md — please do not open a public issue for vulnerabilities.
Upgrading from 1.x
Version 2.0 is a hard reset of the public surface and the on-wire format:
- Minimum PHP version is now 8.1.
- Ciphertexts produced by 1.x cannot be decrypted by 2.x. Plan a re-encryption migration before upgrading.
- The default payload serializer is JSON (was
serialize). Pass'serializer' => 'php_serialize'to keep the old behaviour. Encrypt::create()has been removed; useEncrypt::use().- The Sodium handler no longer requires a 32-byte key — any non-empty string is now accepted and derived internally.
ext-mbstringis no longer required.
A full migration walk-through lives in
docs/08-migration-v1-to-v2.md (shipped
with the package; see also the docs/ index).
Contributing
PRs are welcome. Please read CONTRIBUTING.md first — it
covers the local quality gates (composer test, composer phpstan,
composer cs-check) and the security-review process for changes touching the
cryptographic primitives.
License
MIT — see LICENSE.
