# encryption

**Repository Path**: fiberphp/encryption

## Basic Information

- **Project Name**: encryption
- **Description**: 🔐 FiberPHP 加密组件 —— AES-CBC/GCM 认证加密、bcrypt/argon2 密码哈希、HMAC 与 RSA 签名，零依赖纯库。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP Encryption

AES 对称认证加密、密码哈希、HMAC 签名与 RSA 非对称加密的统一加密组件，零 Composer 依赖的纯库实现（仅依赖 `ext-openssl`）。CBC 模式采用 Encrypt-then-MAC，GCM 模式自带 AEAD 认证。

## 环境要求

- PHP >= 8.3
- `ext-openssl`

## 安装

```bash
composer require fiberphp/encryption
```

## 快速开始

### 对称加密（AES）

```php
use FiberPHP\Encryption\Encrypter;
use FiberPHP\Encryption\KeyGenerator;

// 生成密钥（Base64 编码）
$key = KeyGenerator::generateKey('AES-256-CBC');

$enc = new Encrypter($key, 'AES-256-CBC');

// 加密（返回 Base64 字符串，支持字符串 / 数组）
$cipher = $enc->encrypt(['user_id' => 1, 'role' => 'admin']);

// 解密（返回原始数据，JSON 自动还原为数组）
$data = $enc->decrypt($cipher);
```

### 密码哈希

```php
use FiberPHP\Encryption\Hasher;

$hasher = new Hasher();  // 默认 bcrypt

$hash = $hasher->make('user-password');
$hasher->check('user-password', $hash);          // true
$hasher->needsRehash($hash);                    // 算法升级时返回 true

// 切换 argon2id（需 PHP 编译启用 argon2）
$hasher = new Hasher(PASSWORD_ARGON2ID, ['memory_cost' => 65536, 'time_cost' => 4]);
```

### HMAC 签名

```php
use FiberPHP\Encryption\Signer;

$signer = new Signer('your-hmac-secret', 'sha256');

$signature = $signer->sign('data-to-sign');        // Base64
$signer->verify('data-to-sign', $signature);       // true（恒定时间比较）
```

### RSA 非对称加密

```php
use FiberPHP\Encryption\Rsa\PublicKey;
use FiberPHP\Encryption\Rsa\PrivateKey;

// 生成密钥对
[$privatePem, $publicPem] = KeyGenerator::generateRsaKeyPair(2048);

// 公钥加密 / 私钥解密
$publicKey = new PublicKey($publicPem);
$cipher = $publicKey->encrypt('敏感数据');

$privateKey = new PrivateKey($privatePem);
$plain = $privateKey->decrypt($cipher);

// 私钥签名 / 公钥验签（PrivateKey 实现 SignerInterface，可与 HMAC Signer 互换）
$signature = $privateKey->sign('data-to-sign');
$publicKey->verify('data-to-sign', $signature); // true
```

## 配置说明

`Encrypter` 支持算法：`AES-128-CBC`、`AES-256-CBC`、`AES-128-GCM`、`AES-256-GCM`。

密文结构：

| 模式                    | 结构（Base64 解码后）             |
|-------------------------|-----------------------------------|
| CBC（Encrypt-then-MAC） | `[IV 16B][HMAC-SHA256 32B][密文]` |
| GCM（AEAD）             | `[IV 12B][Tag 16B][密文]`         |

`KeyGenerator` 还提供以下静态方法：

```php
use FiberPHP\Encryption\KeyGenerator;

KeyGenerator::generateRawKey('AES-256-GCM');      // 原始二进制密钥（不做 Base64 编码）
KeyGenerator::validateKey($key, 'AES-256-CBC');   // 校验密钥长度是否匹配（raw 或 Base64 均可），返回 bool

// PBKDF2 从密码派生密钥（迭代次数建议不少于 100000，盐值建议不少于 16 字节）
$derived = KeyGenerator::deriveFromPassword($password, $salt, 'AES-256-CBC', 100000);
```

RSA 明文长度受密钥位数与 padding 限制（如 2048 位密钥 PKCS1 最多加密 245 字节），大数据量请采用「RSA 加密 AES 密钥 + AES 加密数据」的混合方案。

## 错误处理

所有失败均抛出异常，命名空间 `FiberPHP\Encryption\Exception`：

| 异常 | 触发场景 |
|---|---|
| `EncryptionException` | 算法/密钥配置错误、加密与签名失败（继承 `RuntimeException`） |
| `DecryptException` | 解密失败：密文被篡改、MAC/Tag 认证失败、密钥不匹配（继承 `EncryptionException`） |

```php
use FiberPHP\Encryption\Exception\DecryptException;

try {
    $data = $enc->decrypt($payload);
} catch (DecryptException $e) {
    // 密文不可信或密钥错误，按认证失败处理（勿向前端泄露具体原因）
}
```

注意 `Hasher::check()`、`Signer::verify()`、`Rsa\PublicKey::verify()` 等验证类方法返回 `bool`，不抛异常。

## 特性

| 能力             | 说明                                                                         |
|------------------|------------------------------------------------------------------------------|
| Encrypt-then-MAC | CBC 模式先加密再认证，密文篡改在 MAC 阶段被拒                                |
| AEAD             | GCM 模式 OpenSSL 原生认证，无额外 HMAC                                       |
| 密码哈希         | bcrypt / argon2i / argon2id，自包含算法元信息                                |
| 算法升级         | `needsRehash` 检测旧哈希并静默升级                                           |
| 接口抽象         | `EncrypterInterface` / `HasherInterface` / `SignerInterface`，业务按接口注入 |
| RSA 密钥对       | `generateRsaKeyPair` 一键生成，私钥实现 `SignerInterface` 可替换 HMAC        |

## License

MIT License (c) 2026 庞斌，详见 [LICENSE](LICENSE)。