Download the PHP package erikwang2013/encryption without Composer

erikwang2013/encryption

官网 / Website: https://package.erik.xyz/encryption/

Languages: English | All translations / 全部语言

A pluggable cryptography component library: under a unified contract it provides symmetric encryption, asymmetric encryption, hashing, and key derivation (HKDF / PBKDF2), with implementations including AES/Sodium and Chinese national algorithms SM2/SM3/SM4/ZUC. Installable via Composer.

Locky, the padlock above, is the project mascot: it keeps one key per algorithm, a fresh IV on every call, and a keyhole that never tells. Your own app can show it too — Mascot::svg() returns the artwork for HTML, Mascot::ascii() a terminal banner, and Mascot::NAME is Locky.

About the project

What it is

erikwang2013/encryption is a pure PHP cryptography component library that gives PHP applications type-safe, extensible encryption, hashing, and key derivation. It has zero framework dependencies and works standalone or within Laravel, ThinkPHP, Hyperf, and webman.

Below you will find the docs/.

Why it exists

PHP's cryptography landscape is fragmented: Laravel ships its own Crypt, Chinese national algorithms (SM2/SM3/SM4) lack a unified Composer package, and key derivation primitives (HKDF/PBKDF2) have no common interface. This library converges mainstream symmetric/asymmetric/hash/KDF algorithms under a single contract system, so that:

• Application code only depends on interfaces — switching algorithms requires zero business-logic changes
• Guomi algorithms get first-class treatment — call them through the same Manager as AES/Sodium
• Key management is standardized — derive per-algorithm sub-keys from one master key, preventing key reuse across ciphers
• Secure defaults are built in — authenticated encryption (GCM / encrypt-then-MAC), random IVs, and constant-time comparison come out of the box

Use cases

• Field-level encryption (encrypt PII such as phone numbers or ID numbers before storing to the database)
• Multi-algorithm coexistence and gradual migration (e.g. AES-256-CBC to AES-256-GCM)
• Guomi-compliant back-office systems (SM2 asymmetric, SM3 hashing, SM4 symmetric, ZUC stream cipher)
• API signing and verification (HMAC / SHA-256 / SM3)
• Sub-key derivation from passwords or master keys (PBKDF2 / HKDF)

Table of contents

• Framework compatibility
• Integration per framework
• Quick start
• Architecture overview
• Functional design
• Request lifecycle
• Requirements
• Installation
• Built-in algorithms and identifiers
• Usage
• Project structure
• FAQ
• Security notes
• Running tests
• License

Framework compatibility

This package does not depend on any web framework. It ships as a Composer library with classes and autoloading only. In your application, run composer require erikwang2013/encryption; routing, container, and configuration are irrelevant.

You need PHP ≥ 8.0 and the extensions/dependencies listed under Requirements. With that, the following framework versions work (alongside each framework’s own crypto APIs; inject EncryptionManager etc. as needed):

Integration per framework

There is no dedicated Laravel ServiceProvider or ThinkPHP behavior bundle. You register EncryptionManager (or other managers) in your framework’s DI container or singleton factory, loading a 32-byte master key from config or environment. The snippets below are minimal; follow your own security policy for key material (.env, KMS, config services)—do not hard-code secrets.

Laravel (App\Providers\AppServiceProvider or a dedicated ServiceProvider)

Resolve via app(\Erikwang2013\Encryption\EncryptionManager::class). This does not replace Laravel’s Crypt / encrypt(): this library targets field-level encryption and multi-algorithm registries; Laravel’s helpers cover framework serialization, cookies, etc.

ThinkPHP 6 / 8 (service class or factory in common.php)

You can also define EncryptionService under app\service and inject it in controllers for easier mocking in tests.

Hyperf 2 / 3 (config/autoload/dependencies.php or annotation factories)

In coroutine mode, if keys come from remote config, cache the parsed value.

webman 1 / 2

Register EncryptionManager on the global support container in config/plugin.php, a custom bootstrap, or support/bootstrap.php if you use that pattern, or construct with EncryptionManagerFactory::fromMasterKey(...) inside service classes. webman does not mandate a specific container—follow your project’s conventions.

Vanilla PHP (no framework)

There is no container to hook into: composer require at the project root, then build the manager once and reuse it. A runnable version of this file lives in examples/plain-php/ — php examples/plain-php/demo.php prints a full encrypt → store → read → decrypt → tamper-detection cycle.

Notes for plain PHP projects: the factory is the expensive part (it derives every subkey and registers every encryptor), so call it once per process and reuse the instance rather than per query; keep the key in the process environment or your own secret store, and back it up — losing it means losing the data; catch EncryptionException around reads and log server-side instead of echoing the reason to the client; ciphertext is binary, so store base64_encode(...) in a TEXT column or the raw blob in a BLOB column.

Unrelated to this library

• Framework upgrades (e.g. Laravel 10 → 11) usually do not require API changes here. If Composer reports a PHP version conflict, follow this package’s php constraint in composer.json.
• Chinese national SM2 requires ext-gmp; without it, related classes fail at runtime regardless of framework.

Quick start

1. In your project root: composer require erikwang2013/encryption:^1.0 (or your published version constraint).
2. Ensure php -v is 8.0+ and openssl is enabled; for sodium-xchacha20 or SM2, install the sodium and/or gmp extensions as needed.
3. use Erikwang2013\Encryption\... and pick EncryptionManager, hashing, KDF, etc. as described under Usage.

Architecture overview

Capabilities are split into four contract families, each with its own registry and optional facade (*Manager) for composition and testing. Every family has the same shape — contract interface → registry → facade → implementations — and EncryptionManagerFactory wires the symmetric one from a single master key.

Source: docs/architecture-design.svg

Design notes:

• Symmetric: instances bind a fixed key; payloads are binary—good for bulk field encryption.
• Asymmetric: each call passes public/private key material (format defined by the implementation, e.g. SM2 hex).
• Hashing: one-way digests, no secret key (or standard SM3-style hashing).
• Key derivation: HKDF expands high-entropy key material into subkeys; PBKDF2 stretches human passwords (use random salt and high iteration counts).

Functional design

Six capability families, each shipped with the identifiers listed below. Adding an algorithm is a new class plus one register() call — nothing in the core changes, and application code keeps depending on interfaces only.

Source: docs/functional-design.svg

Request lifecycle

Bootstrap happens once per process; encrypt and decrypt are the per-request hot path. Each payload carries a version prefix (v1), so ciphertext written today stays readable after a rotation.

Source: docs/lifecycle.svg

1. Provision — a 32-byte master key from .env or a KMS; the factory rejects any other length.
2. Derive and register — EncryptionManagerFactory::fromMasterKey() derives one subkey per algorithm with HMAC-SHA256 (distinct info label each) and registers every encryptor at once.
3. Encrypt — $manager->encrypt($data, 'aes-256-gcm'); a random IV/nonce is generated per call and the tag or MAC is computed over the ciphertext.
4. Persist — the binary blob v1 | IV | tag/MAC | ciphertext goes into a BLOB column, or is base64_encoded for text storage.
5. Decrypt — the stored identifier picks the implementation, the prefix and length are checked, the tag/MAC is compared in constant time, and only then is the plaintext returned. Any failure raises EncryptionException.

Requirements

SM3 and SM4-CBC use OpenSSL's native implementations whenever the linked OpenSSL provides sm3 / sm4-cbc (OpenSSL 1.1.1+). Otherwise they fall back to the pure-PHP implementations in pohoc/crypto-sm — byte-for-byte identical output, but far slower: the SM3 fallback is quadratic in memory (~490 MB and ~85 s for a single 1 MiB digest, versus ~4 MB at ~60 MB/s natively). CI runs the suite on both paths.

Installation

From a local path (development)

In the consuming project’s composer.json:

Then:

From Git / Packagist (after release)

(Push the repo to an accessible Git remote and Composer source, or publish on Packagist.)

Built-in algorithms and identifiers

Symmetric encryption (SymmetricCipherInterface)

Asymmetric encryption (AsymmetricCipherInterface)

You can also use the static facade Sm2EncryptionService; behavior matches Sm2AsymmetricCipher.

Hashing (HasherInterface)

Key derivation

Ciphertexts and digests are usually binary; for JSON/text storage, apply base64_encode / base64_decode yourself.

Usage

1. Symmetric encryption: single algorithm and registry

Master-key factory: EncryptionManagerFactory::fromMasterKey($masterKey32, 'aes-256-gcm') derives per-algorithm subkeys and registers aes-256-gcm, aes-256-cbc-hmac, sm4-cbc, zuc-128, and sodium-xchacha20 (if ext-sodium is available) at once. Derivation defaults to 'v1'; pass 'v2' as the third argument for the corrected HMAC argument order (the two are mutually unreadable — see §8).

2. Asymmetric encryption

3. Hashing

4. Key derivation (HKDF / PBKDF2)

5. Chinese national algorithms (SM3 / SM4 / ZUC / SM2)

SM1, SM7, SM9: UnavailableNationalAlgorithms::sm1() and similar throw UnsupportedNationalAlgorithmException.

6. Custom plugins

• Symmetric: implement EncryptorInterface (SymmetricCipherInterface), register in EncryptorRegistry.
• Asymmetric: implement AsymmetricCipherInterface, register in AsymmetricCipherRegistry.
• Hashing: implement HasherInterface, register in HasherRegistry.
• KDF: implement KeyDerivationInterface or PasswordBasedKdfInterface, register in the matching Registry.

7. Exceptions

Failures throw Erikwang2013\Encryption\Exception\EncryptionException; unavailable national algorithms use UnsupportedNationalAlgorithmException. Catch and log in application code; do not leak details to clients.

8. Key-derivation scheme v1 → v2 (opt-in migration)

What was wrong. When deriving the per-algorithm subkeys and the MAC keys of aes-256-cbc-hmac, sm4-cbc and zuc-128, hash_hmac($algo, $data, $key) was called with the constant usage label as the HMAC key and the secret material as the message — the two arguments were swapped. The secret must be the HMAC key.

Why nothing is exploitable. The usage label is a public constant and the secret still feeds the HMAC; an attacker without the master key (or the cipher key) derives nothing and forges nothing. Only the argument order was wrong, not the strength of the derivation.

How to switch. Pass 'v2' as the third argument. Omitting it keeps today's behaviour byte for byte, so every existing call site is unchanged:

Each MAC-based encryptor takes the same switch as a trailing optional argument — new Sm4CbcEncryptor($key16, macDerivation: 'v2'). An unknown scheme name throws EncryptionException instead of silently falling back to v1.

Migration. v1 and v2 derive different subkeys and MAC keys, so they are not interchangeable: a v2 manager cannot decrypt v1 ciphertext and a v1 manager cannot decrypt v2 ciphertext (MAC / authentication failure). There is no on-wire marker for the scheme — both write the same v1 payload prefix — so during a migration a wrong-scheme read is indistinguishable from a tampered ciphertext: both surface as a MAC failure. Log the scheme used for each read while you migrate, and expect such failures to be scheme mismatches before you suspect corruption. Build both managers from the same master key and read-then-write:

Re-encrypt stored data (sessions and tokens included) and retire the v1 manager once no v1 ciphertext remains. The master key itself does not change: switching the derivation scheme is not a key rotation.

Unrelated to the payload prefix. The v1 in the v1 | IV | MAC | ciphertext payload layout is a ciphertext format version, not this derivation scheme — the prefix stays v1 under v2, and old blobs keep theirs. Do not rename it.

Project structure

Namespace prefix: Erikwang2013\Encryption\, aligned with Composer psr-4.

FAQ

Composer reports PHP version mismatch

This package requires php ^8.0. If the app still runs PHP 8.0 or lower, upgrade PHP or do not use this package.

sodium-xchacha20 unavailable

Install and enable the sodium extension (ext-sodium). Without it, EncryptionManagerFactory::fromMasterKey(..., 'sodium-xchacha20') fails; use aes-256-gcm instead.

SM2 errors or key generation fails

Install and enable ext-gmp. SM2 relies on big integers; without GMP, behavior is not guaranteed.

Storing ciphertext in a database / JSON

Use BLOB for binary columns; if you must use text, base64_encode ciphertext and IVs, then base64_decode before decryption.

Difference from Laravel encrypt() / Crypt

Laravel’s API targets framework serialization and cookies; this library targets explicit algorithm IDs, multiple registries, national algorithms, HKDF/PBKDF2, etc. They can coexist—do not mix keying unless you align formats yourself.

Security notes

1. Keys: use random_bytes() or a KMS for high-entropy keys; never use raw passwords as AES keys—stretch with PBKDF2 / Argon2 first.
2. Algorithms: prefer AES-256-GCM or Sodium for new systems; use SM3/SM4/ZUC/SM2 where required; HKDF for subkey expansion; for PBKDF2 password stretching, use sufficient iterations and random salt.
3. Transport: still use TLS in transit; this library handles field-level crypto and digests.
4. Migration: track identifier per algorithm version so old data can be decrypted and re-encrypted.
5. Found a vulnerability? Report it privately — see SECURITY.md.

Running tests

After cloning:

Equivalent to ./vendor/bin/phpunit tests/. If you add phpunit.xml, point the test script in composer.json at it.

Thank you for your support / 开源不易，欢迎支持

License

MIT (see the license field in composer.json).

项目宠物表情形态 · Locky

12 种彩色动态形态：笑 / 欢乐 / 哭 / 沮丧 / 惊恐 / 愤怒 / 撒娇 / 卖萌 / 讨好 / 敲打 / 捂脸 / 吐舌头。每个 SVG 自带表情、情绪特效与整体动效，并遵循 prefers-reduced-motion。

视觉资产授权 / Visual Assets License

本项目的项目宠物、图片、图标、表情（包括 docs/pet-expressions/ 等目录下的 SVG / PNG）不是开源资产，版权归作者所有。未经书面许可不得复制、修改、再分发或 用于商业用途；商业使用需取得商业授权，联系 [email protected]。详见 ASSETS-LICENSE.md。

代码部分仍遵循仓库原有 LICENSE；第三方素材（如明确标注的 Go Gopher 等）仍遵循其原许可证。