Skip to content

Commit affdc2b

Browse files
author
苏青安
committed
feat(docs): 添加README
1 parent 190637b commit affdc2b

File tree

2 files changed

+286
-0
lines changed

2 files changed

+286
-0
lines changed

‎README.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# hejunjie/encrypted-request
2+
3+
<div align="center">
4+
<a href="./README.md">English</a>｜<a href="./README.zh-CN.md">简体中文</a>
5+
<hr width="50%"/>
6+
</div>
7+
8+
A PHP package for request encryption, designed for quickly implementing secure communication between frontend and backend.
9+
10+
In real-world development, there are often scenarios where requests need extra security: data must be encrypted to prevent sniffing, and requests should be protected against tampering or replay attacks. Coordinating encryption methods and signature rules with frontend teams each time can be cumbersome. To simplify this workflow, I created this PHP package and a companion npm package, allowing frontend developers to generate encrypted request parameters with a single function call, making it easy to implement secure API communication.
11+
12+
Frontend companion npm package: [npm-encrypted-request](https://github.com/zxc7563598/npm-encrypted-request)
13+
14+
**This project has been parsed by Zread. If you need a quick overview of the project, you can click here to view it：[Understand this project](https://zread.ai/zxc7563598/php-encrypted-request)**
15+
16+
## Features
17+
18+
- 🔐 AES-128-CBC decryption of frontend-encrypted data to prevent leaks
19+
- ✍️ Dynamic MD5 signature verification to prevent forged signatures
20+
- ⏰ Timestamp validation (in seconds) with configurable tolerance, to prevent request hijacking
21+
- ⚙️ Configurable via `.env` file or array
22+
- 🧩 Extensible with custom decryptors
23+
24+
## Installation
25+
26+
```bash
27+
composer require hejunjie/encrypted-request
28+
```
29+
30+
## Configuration Example
31+
32+
You can configure via `.env` file:
33+
34+
```dotenv
35+
APP_KEY=your-app-key
36+
DEFAULT_TIMESTAMP_DIFF=60
37+
38+
# Optional when using a custom decryptor
39+
AES_KEY=your-aes-key
40+
AES_IV=your-aes-iv
41+
```
42+
43+
Or pass configuration as an array:
44+
45+
```php
46+
$config = [
47+
'APP_KEY' => 'your-app-key', // Required: key used for signature verification (32 alphanumeric characters)
48+
'DEFAULT_TIMESTAMP_DIFF' => 60, // Required: maximum allowed timestamp difference in seconds
49+
'AES_KEY' => 'your-aes-key', // Optional: AES encryption key (16 characters); not needed for custom decryptor
50+
'AES_IV' => 'your-aes-iv' // Optional: AES initialization vector (16 characters); not needed for custom decryptor
51+
];
52+
```
53+
54+
## Usage
55+
56+
### Basic Example
57+
58+
```php
59+
use Hejunjie\EncryptedRequest\EncryptedRequestHandler;
60+
61+
$param = $_POST; // Fetch frontend request parameters
62+
63+
$handler = new EncryptedRequestHandler();
64+
try {
65+
$data = $handler->handle(
66+
$param['en_data'] ?? '',
67+
$param['timestamp'] ?? '',
68+
$param['sign'] ?? ''
69+
);
70+
// $data contains the decrypted array
71+
} catch (\Hejunjie\EncryptedRequest\Exceptions\SignatureException $e) {
72+
echo "Signature error: " . $e->getMessage();
73+
} catch (\Hejunjie\EncryptedRequest\Exceptions\TimestampException $e) {
74+
echo "Timestamp error: " . $e->getMessage();
75+
} catch (\Hejunjie\EncryptedRequest\Exceptions\DecryptionException $e) {
76+
echo "Decryption error: " . $e->getMessage();
77+
}
78+
```
79+
80+
### Custom Decryptor
81+
82+
> In most cases, if your `AES_KEY`, `AES_IV`, and `APP_KEY` remain confidential, the default AES-128-CBC decryption is sufficient for secure API communication.
83+
84+
> Custom decryptors are mainly for special scenarios, such as using a completely different encryption algorithm or requiring higher security standards.
85+
86+
> If your project demands extremely high confidentiality, it is recommended to design your own encryption rules rather than relying solely on the default AES implementation.
87+
88+
```php
89+
class MyCustomDecryptor implements \Hejunjie\EncryptedRequest\Contracts\DecryptorInterface
90+
{
91+
/**
92+
* Decrypt method
93+
*
94+
* @param string $data Encrypted data
95+
*
96+
* @return array Decrypted array
97+
* @throws \Hejunjie\EncryptedRequest\Exceptions\DecryptionException
98+
*/
99+
public function decrypt(string $data): array
100+
{
101+
// Custom decryption logic
102+
}
103+
}
104+
105+
$customDecryptor = new MyCustomDecryptor();
106+
$handler = new EncryptedRequestHandler($customDecryptor);
107+
```
108+
109+
## Frontend Integration
110+
111+
Frontend can use the [hejunjie-encrypted-request](https://github.com/zxc7563598/npm-encrypted-request) npm package to generate encrypted data and send it to the PHP backend:
112+
113+
```typescript
114+
import { encryptRequest } from "hejunjie-encrypted-request";
115+
116+
const encrypted = encryptRequest(
117+
{ message: "Hello" },
118+
{
119+
appKey: "your-app-key",
120+
aesKey: "your-aes-key",
121+
aesIv: "your-aes-iv",
122+
token: "your-token",
123+
}
124+
);
125+
```
126+
127+
The PHP backend can directly use `EncryptedRequestHandler` to decrypt.
128+
129+
## Notes
130+
131+
1. AES key and IV must be 16 characters.
132+
2. Timestamp is in seconds; `DEFAULT_TIMESTAMP_DIFF` is the maximum allowed difference. Be mindful of time zones.
133+
3. Frontend `appKey`, `aesKey`, and `aesIv` must match backend, otherwise signature verification will fail.
134+
4. ​`token` is optional and will be passed together with encrypted data.
135+
136+
## Compatibility
137+
138+
- PHP \>\= 8.1
139+
- Compatible with any PSR-4 autoloading framework or plain PHP project
140+
141+
## Development & Contribution
142+
143+
Feel free to submit issues or pull requests, contribute new decryptors, optimize functionality, or add examples.

‎README.zh-CN.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# hejunjie/encrypted-request
2+
3+
<div align="center">
4+
<a href="./README.md">English</a>｜<a href="./README.zh-CN.md">简体中文</a>
5+
<hr width="50%"/>
6+
</div>
7+
8+
PHP 请求加密处理工具包，用于快速实现安全的前后端通信。
9+
10+
在实际开发中，经常会遇到前后端请求有安全要求的情况：数据需要加密防止抓包，同时也要防止请求被篡改或重复发送。每次写接口还要和前端协调，加密方式和签名规则可能不一致。为了简化这一流程，我开发了这个 PHP 仓库，并顺便发布了一个配套的 npm 包，让前端只需调用一个方法即可在原本请求上生成加密请求参数，从而快速实现接口数据加密与安全通信。
11+
12+
前端配套 npm 包：[npm-encrypted-request](https://github.com/zxc7563598/npm-encrypted-request)
13+
14+
**本项目已经经由 Zread 解析完成，如果需要快速了解项目，可以点击此处进行查看：[了解本项目](https://zread.ai/zxc7563598/php-encrypted-request)**
15+
16+
## 功能特性
17+
18+
- 🔐 AES-128-CBC 解密前端加密数据，防止数据泄露
19+
- ✍️ 动态 MD5 签名校验，防止伪造签名
20+
- ⏰ 秒级时间戳验证，可自定义误差范围，防止劫持请求
21+
- ⚙️ 支持通过 `.env` 或数组传入配置
22+
- 🧩 可扩展自定义解密器
23+
24+
## 安装
25+
26+
```bash
27+
composer require hejunjie/encrypted-request
28+
```
29+
30+
## 配置示例
31+
32+
可以通过 `.env` 文件配置：
33+
34+
```dotenv
35+
APP_KEY=your-app-key
36+
DEFAULT_TIMESTAMP_DIFF=60
37+
38+
# 自定义解密器时可不传
39+
AES_KEY=your-aes-key
40+
AES_IV=your-aes-iv
41+
```
42+
43+
也可以通过数组直接传入：
44+
45+
```php
46+
$config = [
47+
'APP_KEY' => 'your-app-key', // 必传，签名密钥，用于接口签名校验（32位字母或数字）
48+
'DEFAULT_TIMESTAMP_DIFF' => 60, // 必传，用于验证请求是否过期，秒级
49+
'AES_KEY' => 'your-aes-key', // 非必传，AES 加密的密钥（16位），自定义解密器时可不传
50+
'AES_IV' => 'your-aes-iv' // 非必传，AES 加密的初始化向量（16位），自定义解密器时可不传
51+
];
52+
```
53+
54+
## 使用方法
55+
56+
### 基本示例
57+
58+
```php
59+
use Hejunjie\EncryptedRequest\EncryptedRequestHandler;
60+
61+
$param = $_POST; // 自行获取前端请求的参数
62+
63+
$handler = new EncryptedRequestHandler();
64+
try {
65+
$data = $handler->handle(
66+
$param['en_data'] ?? '',
67+
$param['timestamp'] ?? '',
68+
$param['sign'] ?? ''
69+
);
70+
// $data 为解密后的数组
71+
} catch (\Hejunjie\EncryptedRequest\Exceptions\SignatureException $e) {
72+
echo "签名错误: " . $e->getMessage();
73+
} catch (\Hejunjie\EncryptedRequest\Exceptions\TimestampException $e) {
74+
echo "时间戳错误: " . $e->getMessage();
75+
} catch (\Hejunjie\EncryptedRequest\Exceptions\DecryptionException $e) {
76+
echo "解密错误: " . $e->getMessage();
77+
}
78+
```
79+
80+
### 自定义解密器
81+
82+
> 实际上，对于绝大多数场景，如果你的 AES_KEY、AES_IV 和 APP_KEY 保密，默认的 AES-128-CBC 解密已经足够满足接口数据加密的需求。
83+
84+
> 自定义解密器主要适用于特殊场景，比如需要使用完全不同的加密算法或对加密规则有更高安全要求。
85+
86+
> 如果你的项目对保密性有极高要求，建议自行设计和实现接口数据的加密规则，而不是使用公开方案。
87+
88+
```php
89+
class MyCustomDecryptor implements \Hejunjie\EncryptedRequest\Contracts\DecryptorInterface
90+
{
91+
/**
92+
* 解密方法
93+
*
94+
* @param string $data 加密数据
95+
*
96+
* @return array 解密后的数组
97+
* @throws \Hejunjie\EncryptedRequest\Exceptions\DecryptionException
98+
*/
99+
public function decrypt(string $data): array
100+
{
101+
// 自定义解密逻辑
102+
}
103+
}
104+
105+
$customDecryptor = new MyCustomDecryptor();
106+
$handler = new EncryptedRequestHandler($customDecryptor);
107+
```
108+
109+
## 前端配合
110+
111+
前端使用 [hejunjie-encrypted-request](https://github.com/zxc7563598/npm-encrypted-request) npm 包生成加密数据，并发送给 PHP 后端：
112+
113+
```typescript
114+
import { encryptRequest } from "hejunjie-encrypted-request";
115+
116+
const encrypted = encryptRequest(
117+
{ message: "Hello" },
118+
{
119+
appKey: "your-app-key",
120+
aesKey: "your-aes-key",
121+
aesIv: "your-aes-iv",
122+
token: "your-token",
123+
}
124+
);
125+
```
126+
127+
PHP 后端直接使用 `EncryptedRequestHandler` 解密即可。
128+
129+
## 注意事项
130+
131+
1. AES 密钥和向量必须为 16 位。
132+
2. 时间戳单位为秒，`DEFAULT_TIMESTAMP_DIFF` 为允许的最大时间差；需要注意时区问题。
133+
3. 前端 `appKey` / `aesKey` / `aesIv` 与后端保持一致，否则签名验证失败。
134+
4. ​`token` 可选，会与密文一起传给 PHP 后端
135+
136+
## 兼容性
137+
138+
- PHP \>\= 8.1
139+
- 支持任何遵循 PSR-4 自动加载的框架或原生 PHP 项目
140+
141+
## 开发与贡献
142+
143+
欢迎提交 Issue 或 Pull Request，贡献新解密器、优化功能或增加示例。

0 commit comments

Comments
 (0)