PHPackages                             erikwang2013/encryption - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. erikwang2013/encryption

ActiveLibrary[Security](/categories/security)

erikwang2013/encryption
=======================

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.

v1.0.3(1mo ago)1412↑83%MITPHPPHP ^8.1

Since Mar 31Pushed 1mo agoCompare

[ Source](https://github.com/erikwang2013/encryption)[ Packagist](https://packagist.org/packages/erikwang2013/encryption)[ RSS](/packages/erikwang2013-encryption/feed)WikiDiscussions main Synced 4w ago

READMEChangelog (4)Dependencies (4)Versions (5)Used By (0)

erikwang2013/encryption
=======================

[](#erikwang2013encryption)

**Languages:** **English** | [简体中文](README.zh-CN.md)

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.

About the project
-----------------

[](#about-the-project)

### What it is

[](#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.

### Why it exists

[](#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

[](#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
-----------------

[](#table-of-contents)

- [Framework compatibility](#framework-compatibility)
- [Integration per framework](#integration-per-framework)
- [Quick start](#quick-start)
- [Architecture overview](#architecture-overview)
- [Requirements](#requirements)
- [Installation](#installation)
- [Built-in algorithms and identifiers](#built-in-algorithms-and-identifiers)
- [Usage](#usage)
- [Package layout](#package-layout)
- [FAQ](#faq)
- [Security notes](#security-notes)
- [Running tests](#running-tests)
- [License](#license)

---

Framework compatibility
-----------------------

[](#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.1** and the extensions/dependencies listed under [Requirements](#requirements). With that, the following framework versions work (alongside each framework’s own crypto APIs; inject `EncryptionManager` etc. as needed):

FrameworkNotes**Laravel** 7 / 8 / 9 / 10 / 11Install in a **PHP 8.1+** runtime. If Laravel 7 still runs on PHP 7.x or 8.0 only, this package’s PHP constraint is not satisfied—upgrade PHP first.**ThinkPHP** 6 / 8Add the package to the app’s standard `composer.json` `require`.**Hyperf** 2 / 3Require in the service’s `composer.json`; register a singleton in `config` or a factory as you usually do in Hyperf.**webman** 1 / 2`composer require` at the project root; use from business classes or `support` helpers.### Integration per framework

[](#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)**

```
use Erikwang2013\Encryption\EncryptionManagerFactory;

public function register(): void
{
    $this->app->singleton(\Erikwang2013\Encryption\EncryptionManager::class, function () {
        $raw = config('app.custom_master_key'); // e.g. base64 for 32 bytes
        $master = is_string($raw) ? base64_decode($raw, true) : '';
        if ($master === false || strlen($master) !== 32) {
            throw new \RuntimeException('Invalid 32-byte master key.');
        }
        return EncryptionManagerFactory::fromMasterKey($master, 'aes-256-gcm');
    });
}
```

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`)**

```
use Erikwang2013\Encryption\EncryptionManagerFactory;

function app_encryption_manager(): \Erikwang2013\Encryption\EncryptionManager
{
    static $mgr = null;
    if ($mgr === null) {
        $master = base64_decode(config('app.master_key'), true);
        $mgr = EncryptionManagerFactory::fromMasterKey($master, 'aes-256-gcm');
    }
    return $mgr;
}
```

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)**

```
use Erikwang2013\Encryption\EncryptionManager;
use Erikwang2013\Encryption\EncryptionManagerFactory;

return [
    EncryptionManager::class => function () {
        $master = base64_decode((string) config('encryption.master_key'), true);
        return EncryptionManagerFactory::fromMasterKey($master, 'aes-256-gcm');
    },
];
```

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**.

### Unrelated to this library

[](#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
-----------

[](#quick-start)

1. In your project root: `composer require erikwang2013/encryption:^1.0` (or your published version constraint).
2. Ensure `php -v` is **8.1+** 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](#usage).

---

Architecture overview
---------------------

[](#architecture-overview)

Capabilities are split into four contract families, each with its own registry and optional facade (`*Manager`) for composition and testing.

 ```
flowchart TB
  subgraph symmetric [Symmetric encryption]
    SI["SymmetricCipherInterface / EncryptorInterface"]
    ER["EncryptorRegistry"]
    EM["EncryptionManager"]
  end
  subgraph asymmetric [Asymmetric encryption]
    AI["AsymmetricCipherInterface"]
    AR["AsymmetricCipherRegistry"]
    AM["AsymmetricCryptoManager"]
  end
  subgraph hash [Hashing]
    HI["HasherInterface"]
    HR["HasherRegistry"]
    HM["HashingManager"]
  end
  subgraph kdf [Key derivation]
    KI["KeyDerivationInterface"]
    PI["PasswordBasedKdfInterface"]
    KR["KeyDerivationRegistry / PasswordBasedKdfRegistry"]
    KM["KeyDerivationManager / PasswordBasedKdfManager"]
  end
  SI --> ER --> EM
  AI --> AR --> AM
  HI --> HR --> HM
  KI --> KR --> KM
  PI --> KR
```

      Loading CapabilityContractRegistryFacade (default algorithm)Symmetric`SymmetricCipherInterface` (`EncryptorInterface` alias)`EncryptorRegistry``EncryptionManager`Asymmetric`AsymmetricCipherInterface``AsymmetricCipherRegistry``AsymmetricCryptoManager`Hashing`HasherInterface``HasherRegistry``HashingManager`Key derivation (IKM)`KeyDerivationInterface``KeyDerivationRegistry``KeyDerivationManager`Password-based KDF`PasswordBasedKdfInterface``PasswordBasedKdfRegistry``PasswordBasedKdfManager`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).

---

Requirements
------------

[](#requirements)

ItemDetailsPHP`^8.1` (when combined with frameworks above, this constraint wins)Extension`ext-openssl` (required)Extension`ext-sodium` (optional, for `sodium-xchacha20`)Extension`ext-gmp` (optional, **SM2** encryption/decryption and key generation)Composer`pohoc/crypto-sm` (dependency; SM2/SM3/SM4 wrappers)Installation
------------

[](#installation)

### From a local path (development)

[](#from-a-local-path-development)

In the consuming project’s `composer.json`:

```
{
    "repositories": [
        {
            "type": "path",
            "url": "/absolute/path/to/encryption"
        }
    ],
    "require": {
        "erikwang2013/encryption": "@dev"
    }
}
```

Then:

```
composer update erikwang2013/encryption
```

### From Git / Packagist (after release)

[](#from-git--packagist-after-release)

```
composer require erikwang2013/encryption:^1.0
```

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

---

Built-in algorithms and identifiers
-----------------------------------

[](#built-in-algorithms-and-identifiers)

### Symmetric encryption (`SymmetricCipherInterface`)

[](#symmetric-encryption-symmetriccipherinterface)

Identifier (`getIdentifier`)ClassKey lengthNotes`aes-256-gcm``Aes256GcmEncryptor`32 bytesAEAD; recommended default for new systems`sodium-xchacha20``SodiumXChaCha20Encryptor`32 bytesRequires `ext-sodium``aes-256-cbc-hmac``OpenSslAes256CbcEncryptor`32 bytesCBC + HMAC for legacy compatibility`sm4-cbc``Sm4CbcEncryptor`16 bytesSM4-CBC (OpenSSL SM4)`zuc-128``ZucEncryptor`16 bytesZUC-128 stream cipher### Asymmetric encryption (`AsymmetricCipherInterface`)

[](#asymmetric-encryption-asymmetriccipherinterface)

IdentifierClassNotes`sm2``Sm2AsymmetricCipher`SM2; keys and ciphertext as hex; requires `ext-gmp`You can also use the static facade `Sm2EncryptionService`; behavior matches `Sm2AsymmetricCipher`.

### Hashing (`HasherInterface`)

[](#hashing-hasherinterface)

IdentifierClassOutput length`sha256``Sha256Hasher`32 bytes`sm3``Sm3Hasher`32 bytes### Key derivation

[](#key-derivation)

IdentifierClassContractNotes`hkdf-sha256``HkdfSha256``KeyDerivationInterface`RFC 5869: IKM + salt + info`pbkdf2-sha256``Pbkdf2Sha256``PasswordBasedKdfInterface`Password + salt + iterations (constructor)Ciphertexts and digests are usually binary; for JSON/text storage, apply `base64_encode` / `base64_decode` yourself.

---

Usage
-----

[](#usage)

### 1. Symmetric encryption: single algorithm and registry

[](#1-symmetric-encryption-single-algorithm-and-registry)

```