216 lines
5.1 KiB
Markdown
216 lines
5.1 KiB
Markdown
# 加密二维码使用说明
|
||
|
||
## 概述
|
||
|
||
本系统提供了基于token的二维码加密和解密功能，可以安全地生成包含敏感信息的二维码，并设置过期时间。
|
||
|
||
## 主要特性
|
||
|
||
1. **AES加密**：使用AES对称加密算法保护二维码数据
|
||
2. **Token机制**：每个二维码都有唯一的token作为密钥
|
||
3. **过期控制**：可设置二维码的有效期（1-1440分钟）
|
||
4. **Redis存储**：token和原始数据存储在Redis中，支持自动过期
|
||
5. **数据验证**：解密时会验证数据完整性
|
||
|
||
## API接口
|
||
|
||
### 1. 生成普通二维码
|
||
|
||
```http
|
||
GET /api/qr-code/create-qr-code?data=https://example.com&size=200x200
|
||
```
|
||
|
||
**参数：**
|
||
- `data`: 要编码的数据（必需）
|
||
- `size`: 二维码尺寸，格式：宽x高 或 单个数字（可选，默认200x200）
|
||
|
||
**响应：** 直接返回PNG图片流
|
||
|
||
### 2. 生成加密二维码（返回JSON）
|
||
|
||
```http
|
||
POST /api/qr-code/create-encrypted-qr-code
|
||
```
|
||
|
||
**参数：**
|
||
- `data`: 要加密的数据（必需）
|
||
- `width`: 二维码宽度（可选，默认200）
|
||
- `height`: 二维码高度（可选，默认200）
|
||
- `expireMinutes`: 过期时间分钟数（可选，默认30，最大1440）
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "生成加密二维码成功",
|
||
"data": {
|
||
"qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
|
||
"token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
|
||
"originalData": "https://example.com/user/123",
|
||
"expireMinutes": "30"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 生成加密二维码（返回图片流）
|
||
|
||
```http
|
||
GET /api/qr-code/create-encrypted-qr-image?data=https://example.com&size=300x300&expireMinutes=60
|
||
```
|
||
|
||
**参数：**
|
||
- `data`: 要加密的数据（必需）
|
||
- `size`: 二维码尺寸（可选，默认200x200）
|
||
- `expireMinutes`: 过期时间分钟数（可选，默认30）
|
||
|
||
**响应：** 直接返回PNG图片流，并在响应头中包含token信息
|
||
- `X-QR-Token`: 二维码的token
|
||
- `X-QR-Expire-Minutes`: 过期时间
|
||
|
||
### 4. 解密二维码数据
|
||
|
||
```http
|
||
POST /api/qr-code/decrypt-qr-data
|
||
```
|
||
|
||
**参数：**
|
||
- `token`: token密钥（必需）
|
||
- `encryptedData`: 加密的数据（必需）
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "解密成功",
|
||
"data": "https://example.com/user/123"
|
||
}
|
||
```
|
||
|
||
### 5. 验证并解密二维码内容
|
||
|
||
```http
|
||
POST /api/qr-code/verify-and-decrypt-qr
|
||
```
|
||
|
||
**参数：**
|
||
- `qrContent`: 二维码扫描得到的完整JSON内容（必需）
|
||
|
||
**二维码内容格式：**
|
||
```json
|
||
{
|
||
"token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
|
||
"data": "encrypted_data_here",
|
||
"type": "encrypted"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "验证和解密成功",
|
||
"data": "https://example.com/user/123"
|
||
}
|
||
```
|
||
|
||
### 6. 检查token是否有效
|
||
|
||
```http
|
||
GET /api/qr-code/check-token?token=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "检查完成",
|
||
"data": true
|
||
}
|
||
```
|
||
|
||
### 7. 使token失效
|
||
|
||
```http
|
||
POST /api/qr-code/invalidate-token
|
||
```
|
||
|
||
**参数：**
|
||
- `token`: 要使失效的token（必需）
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "token已失效"
|
||
}
|
||
```
|
||
|
||
## 使用场景
|
||
|
||
### 场景1：用户身份验证二维码
|
||
|
||
```javascript
|
||
// 生成包含用户ID的加密二维码
|
||
const response = await fetch('/api/qr-code/create-encrypted-qr-code', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
|
||
body: 'data=user_id:12345&expireMinutes=10'
|
||
});
|
||
|
||
const result = await response.json();
|
||
// 显示二维码图片：result.data.qrCodeBase64
|
||
// 保存token用于后续验证：result.data.token
|
||
```
|
||
|
||
### 场景2：临时访问链接
|
||
|
||
```javascript
|
||
// 生成临时访问链接的二维码
|
||
const accessUrl = 'https://example.com/temp-access?session=abc123';
|
||
const response = await fetch('/api/qr-code/create-encrypted-qr-image?' +
|
||
new URLSearchParams({
|
||
data: accessUrl,
|
||
size: '250x250',
|
||
expireMinutes: '5'
|
||
}));
|
||
|
||
// 直接使用返回的图片流
|
||
// token信息在响应头 X-QR-Token 中
|
||
```
|
||
|
||
### 场景3：扫码验证
|
||
|
||
```javascript
|
||
// 扫描二维码后验证
|
||
const qrContent = '{"token":"...","data":"...","type":"encrypted"}';
|
||
const response = await fetch('/api/qr-code/verify-and-decrypt-qr', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
|
||
body: 'qrContent=' + encodeURIComponent(qrContent)
|
||
});
|
||
|
||
const result = await response.json();
|
||
if (result.code === 200) {
|
||
console.log('原始数据:', result.data);
|
||
} else {
|
||
console.log('验证失败:', result.message);
|
||
}
|
||
```
|
||
|
||
## 安全注意事项
|
||
|
||
1. **token保护**：token是解密的关键，应妥善保管
|
||
2. **过期时间**：根据安全需求设置合适的过期时间
|
||
3. **HTTPS传输**：生产环境中应使用HTTPS传输
|
||
4. **访问控制**：可根据需要添加接口访问权限控制
|
||
5. **日志记录**：建议记录二维码生成和验证的操作日志
|
||
|
||
## 错误处理
|
||
|
||
常见错误及处理：
|
||
|
||
- `token已过期或无效`：二维码已过期，需要重新生成
|
||
- `数据验证失败`：加密数据被篡改或token不匹配
|
||
- `尺寸必须在50-1000像素之间`：二维码尺寸超出允许范围
|
||
- `过期时间必须在1-1440分钟之间`：过期时间设置不合理
|