645 lines
22 KiB
Markdown
645 lines
22 KiB
Markdown
# 工具箱端 - 任务二维码解密指南
|
||
|
||
## 概述
|
||
|
||
本文档说明工具箱端如何解密任务二维码数据。App 创建任务后，平台会生成加密的任务数据并返回给 App，App 将其生成二维码。工具箱扫描二维码后，需要使用自己的 `licence` 和 `fingerprint` 解密任务数据。
|
||
|
||
> ### UX 集成模式补充（当前项目实现）
|
||
>
|
||
> 在当前集成模式中，工具箱扫描二维码后将密文提交给 UX 的 `crypto.decryptTask`，
|
||
> 由 UX 使用设备绑定的 `licence + fingerprint` 执行 AES-256-GCM 解密并返回任务明文。
|
||
|
||
## 一、业务流程
|
||
|
||
```
|
||
App创建任务 → 平台加密任务数据 → 返回加密数据 → App生成二维码
|
||
↓
|
||
工具箱扫描二维码 → 提取加密数据 → AES-256-GCM解密 → 获取任务信息
|
||
```
|
||
|
||
## 二、任务数据结构
|
||
|
||
### 2.1 任务数据 JSON 格式
|
||
|
||
解密后的任务数据为 JSON 格式，包含以下字段：
|
||
|
||
```json
|
||
{
|
||
"taskId": "TASK-20260115-4875",
|
||
"enterpriseId": "1173040813421105152",
|
||
"orgName": "超艺科技有限公司",
|
||
"inspectionId": "702286470691215417",
|
||
"inspectionPerson": "警务通",
|
||
"issuedAt": 1734571234567
|
||
}
|
||
```
|
||
|
||
### 2.2 字段说明
|
||
|
||
| 字段名 | 类型 | 说明 | 示例 |
|
||
|--------|------|------|------|
|
||
| `taskId` | String | 任务唯一ID（格式：TASK-YYYYMMDD-XXXX） | `"TASK-20260115-4875"` |
|
||
| `enterpriseId` | String | 企业ID | `"1173040813421105152"` |
|
||
| `orgName` | String | 单位名称 | `"超艺科技有限公司"` |
|
||
| `inspectionId` | String | 检查ID | `"702286470691215417"` |
|
||
| `inspectionPerson` | String | 检查人 | `"警务通"` |
|
||
| `issuedAt` | Number | 任务发布时间戳（毫秒） | `1734571234567` |
|
||
|
||
## 三、加密算法说明
|
||
|
||
### 3.1 加密方式
|
||
|
||
- **算法**：AES-256-GCM（Galois/Counter Mode）
|
||
- **密钥长度**：256 位（32 字节）
|
||
- **IV 长度**：12 字节（96 位）
|
||
- **认证标签长度**：16 字节（128 位）
|
||
|
||
### 3.2 密钥生成
|
||
|
||
密钥由工具箱的 `licence` 和 `fingerprint` 生成：
|
||
|
||
```
|
||
密钥 = SHA-256(licence + fingerprint)
|
||
```
|
||
|
||
**重要说明**：
|
||
- `licence` 和 `fingerprint` 直接字符串拼接（无分隔符）
|
||
- 使用 SHA-256 哈希算法的全部 32 字节作为 AES-256 密钥
|
||
- 工具箱必须使用与平台绑定时相同的 `licence` 和 `fingerprint`
|
||
|
||
### 3.3 加密数据格式
|
||
|
||
加密后的数据格式（Base64 编码前）：
|
||
|
||
```
|
||
[IV(12字节)] + [加密数据] + [认证标签(16字节)]
|
||
```
|
||
|
||
**数据布局**：
|
||
```
|
||
+------------------+------------------+------------------+
|
||
| IV (12字节) | 加密数据 | 认证标签(16字节)|
|
||
+------------------+------------------+------------------+
|
||
```
|
||
|
||
## 四、解密步骤
|
||
|
||
### 4.1 解密流程
|
||
|
||
1. **扫描二维码**：获取 Base64 编码的加密数据
|
||
2. **Base64 解码**：将 Base64 字符串解码为字节数组
|
||
3. **分离数据**：从字节数组中分离 IV、加密数据和认证标签
|
||
4. **生成密钥**：使用 `licence + fingerprint` 生成 AES-256 密钥
|
||
5. **解密数据**：使用 AES-256-GCM 解密（自动验证认证标签）
|
||
6. **解析 JSON**：将解密后的字符串解析为 JSON 对象
|
||
|
||
### 4.2 Python 实现示例
|
||
|
||
```python
|
||
import base64
|
||
import json
|
||
import hashlib
|
||
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
|
||
from cryptography.hazmat.backends import default_backend
|
||
|
||
def decrypt_task_data(
|
||
encrypted_data_base64: str,
|
||
licence: str,
|
||
fingerprint: str
|
||
) -> dict:
|
||
"""
|
||
解密任务二维码数据
|
||
|
||
Args:
|
||
encrypted_data_base64: Base64编码的加密数据
|
||
licence: 设备授权码
|
||
fingerprint: 设备硬件指纹
|
||
|
||
Returns:
|
||
解密后的任务数据（字典）
|
||
"""
|
||
# 1. Base64 解码
|
||
encrypted_bytes = base64.b64decode(encrypted_data_base64)
|
||
|
||
# 2. 分离 IV 和加密数据（包含认证标签）
|
||
if len(encrypted_bytes) < 12:
|
||
raise ValueError("加密数据格式错误：数据长度不足")
|
||
|
||
iv = encrypted_bytes[:12] # IV: 前12字节
|
||
ciphertext_with_tag = encrypted_bytes[12:] # 加密数据 + 认证标签
|
||
|
||
# 3. 生成密钥：SHA-256(licence + fingerprint)
|
||
combined = licence + fingerprint
|
||
key = hashlib.sha256(combined.encode('utf-8')).digest()
|
||
|
||
# 4. 使用 AES-256-GCM 解密
|
||
aesgcm = AESGCM(key)
|
||
decrypted_bytes = aesgcm.decrypt(iv, ciphertext_with_tag, None)
|
||
|
||
# 5. 解析 JSON
|
||
decrypted_json = decrypted_bytes.decode('utf-8')
|
||
task_data = json.loads(decrypted_json)
|
||
|
||
return task_data
|
||
|
||
# 使用示例
|
||
if __name__ == "__main__":
|
||
# 从二维码扫描获取的加密数据
|
||
encrypted_data = "Base64编码的加密数据..."
|
||
|
||
# 工具箱的授权信息（必须与平台绑定时一致）
|
||
licence = "LIC-8F2A-XXXX"
|
||
fingerprint = "FP-2c91e9f3"
|
||
|
||
# 解密任务数据
|
||
task_data = decrypt_task_data(encrypted_data, licence, fingerprint)
|
||
|
||
print("任务ID:", task_data["taskId"])
|
||
print("企业ID:", task_data["enterpriseId"])
|
||
print("单位名称:", task_data["orgName"])
|
||
print("检查ID:", task_data["inspectionId"])
|
||
print("检查人:", task_data["inspectionPerson"])
|
||
print("发布时间:", task_data["issuedAt"])
|
||
```
|
||
|
||
### 4.3 Java/Kotlin 实现示例
|
||
|
||
```kotlin
|
||
import com.fasterxml.jackson.databind.ObjectMapper
|
||
import java.nio.charset.StandardCharsets
|
||
import java.security.MessageDigest
|
||
import java.util.Base64
|
||
import javax.crypto.Cipher
|
||
import javax.crypto.spec.GCMParameterSpec
|
||
import javax.crypto.spec.SecretKeySpec
|
||
|
||
object TaskDecryptionUtil {
|
||
|
||
private const val ALGORITHM = "AES"
|
||
private const val TRANSFORMATION = "AES/GCM/NoPadding"
|
||
private const val GCM_IV_LENGTH = 12 // GCM 推荐使用 12 字节 IV
|
||
private const val GCM_TAG_LENGTH = 16 // GCM 认证标签长度（128位）
|
||
private const val KEY_LENGTH = 32 // AES-256 密钥长度（256位 = 32字节）
|
||
|
||
private val objectMapper = ObjectMapper()
|
||
|
||
/**
|
||
* 解密任务二维码数据
|
||
*
|
||
* @param encryptedDataBase64 Base64编码的加密数据
|
||
* @param licence 设备授权码
|
||
* @param fingerprint 设备硬件指纹
|
||
* @return 解密后的任务数据（Map）
|
||
*/
|
||
fun decryptTaskData(
|
||
encryptedDataBase64: String,
|
||
licence: String,
|
||
fingerprint: String
|
||
): Map<String, Any> {
|
||
// 1. Base64 解码
|
||
val encryptedBytes = Base64.getDecoder().decode(encryptedDataBase64)
|
||
|
||
// 2. 分离 IV 和加密数据（包含认证标签）
|
||
if (encryptedBytes.size < GCM_IV_LENGTH) {
|
||
throw IllegalArgumentException("加密数据格式错误：数据长度不足")
|
||
}
|
||
|
||
val iv = encryptedBytes.sliceArray(0 until GCM_IV_LENGTH)
|
||
val ciphertextWithTag = encryptedBytes.sliceArray(GCM_IV_LENGTH until encryptedBytes.size)
|
||
|
||
// 3. 生成密钥：SHA-256(licence + fingerprint)
|
||
val combined = "$licence$fingerprint"
|
||
val digest = MessageDigest.getInstance("SHA-256")
|
||
val keyBytes = digest.digest(combined.toByteArray(StandardCharsets.UTF_8))
|
||
val key = SecretKeySpec(keyBytes, ALGORITHM)
|
||
|
||
// 4. 使用 AES-256-GCM 解密
|
||
val cipher = Cipher.getInstance(TRANSFORMATION)
|
||
val parameterSpec = GCMParameterSpec(GCM_TAG_LENGTH * 8, iv) // 标签长度以位为单位
|
||
cipher.init(Cipher.DECRYPT_MODE, key, parameterSpec)
|
||
|
||
// 解密数据（GCM 会自动验证认证标签）
|
||
val decryptedBytes = cipher.doFinal(ciphertextWithTag)
|
||
|
||
// 5. 解析 JSON
|
||
val decryptedJson = String(decryptedBytes, StandardCharsets.UTF_8)
|
||
@Suppress("UNCHECKED_CAST")
|
||
return objectMapper.readValue(decryptedJson, Map::class.java) as Map<String, Any>
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
fun main() {
|
||
// 从二维码扫描获取的加密数据
|
||
val encryptedData = "Base64编码的加密数据..."
|
||
|
||
// 工具箱的授权信息（必须与平台绑定时一致）
|
||
val licence = "LIC-8F2A-XXXX"
|
||
val fingerprint = "FP-2c91e9f3"
|
||
|
||
// 解密任务数据
|
||
val taskData = TaskDecryptionUtil.decryptTaskData(encryptedData, licence, fingerprint)
|
||
|
||
println("任务ID: ${taskData["taskId"]}")
|
||
println("企业ID: ${taskData["enterpriseId"]}")
|
||
println("单位名称: ${taskData["orgName"]}")
|
||
println("检查ID: ${taskData["inspectionId"]}")
|
||
println("检查人: ${taskData["inspectionPerson"]}")
|
||
println("发布时间: ${taskData["issuedAt"]}")
|
||
}
|
||
```
|
||
|
||
### 4.4 C# 实现示例
|
||
|
||
```csharp
|
||
using System;
|
||
using System.Security.Cryptography;
|
||
using System.Text;
|
||
using System.Text.Json;
|
||
|
||
public class TaskDecryptionUtil
|
||
{
|
||
private const int GcmIvLength = 12; // GCM 推荐使用 12 字节 IV
|
||
private const int GcmTagLength = 16; // GCM 认证标签长度（128位）
|
||
|
||
/// <summary>
|
||
/// 解密任务二维码数据
|
||
/// </summary>
|
||
public static Dictionary<string, object> DecryptTaskData(
|
||
string encryptedDataBase64,
|
||
string licence,
|
||
string fingerprint
|
||
)
|
||
{
|
||
// 1. Base64 解码
|
||
byte[] encryptedBytes = Convert.FromBase64String(encryptedDataBase64);
|
||
|
||
// 2. 分离 IV 和加密数据（包含认证标签）
|
||
if (encryptedBytes.Length < GcmIvLength)
|
||
{
|
||
throw new ArgumentException("加密数据格式错误：数据长度不足");
|
||
}
|
||
|
||
byte[] iv = new byte[GcmIvLength];
|
||
Array.Copy(encryptedBytes, 0, iv, 0, GcmIvLength);
|
||
|
||
byte[] ciphertextWithTag = new byte[encryptedBytes.Length - GcmIvLength];
|
||
Array.Copy(encryptedBytes, GcmIvLength, ciphertextWithTag, 0, ciphertextWithTag.Length);
|
||
|
||
// 3. 生成密钥：SHA-256(licence + fingerprint)
|
||
string combined = licence + fingerprint;
|
||
byte[] keyBytes = SHA256.Create().ComputeHash(Encoding.UTF8.GetBytes(combined));
|
||
|
||
// 4. 使用 AES-256-GCM 解密
|
||
using (AesGcm aesGcm = new AesGcm(keyBytes))
|
||
{
|
||
byte[] decryptedBytes = new byte[ciphertextWithTag.Length - GcmTagLength];
|
||
byte[] tag = new byte[GcmTagLength];
|
||
Array.Copy(ciphertextWithTag, ciphertextWithTag.Length - GcmTagLength, tag, 0, GcmTagLength);
|
||
Array.Copy(ciphertextWithTag, 0, decryptedBytes, 0, decryptedBytes.Length);
|
||
|
||
aesGcm.Decrypt(iv, decryptedBytes, tag, null, decryptedBytes);
|
||
|
||
// 5. 解析 JSON
|
||
string decryptedJson = Encoding.UTF8.GetString(decryptedBytes);
|
||
return JsonSerializer.Deserialize<Dictionary<string, object>>(decryptedJson);
|
||
}
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
class Program
|
||
{
|
||
static void Main()
|
||
{
|
||
// 从二维码扫描获取的加密数据
|
||
string encryptedData = "Base64编码的加密数据...";
|
||
|
||
// 工具箱的授权信息（必须与平台绑定时一致）
|
||
string licence = "LIC-8F2A-XXXX";
|
||
string fingerprint = "FP-2c91e9f3";
|
||
|
||
// 解密任务数据
|
||
var taskData = TaskDecryptionUtil.DecryptTaskData(encryptedData, licence, fingerprint);
|
||
|
||
Console.WriteLine($"任务ID: {taskData["taskId"]}");
|
||
Console.WriteLine($"企业ID: {taskData["enterpriseId"]}");
|
||
Console.WriteLine($"单位名称: {taskData["orgName"]}");
|
||
Console.WriteLine($"检查ID: {taskData["inspectionId"]}");
|
||
Console.WriteLine($"检查人: {taskData["inspectionPerson"]}");
|
||
Console.WriteLine($"发布时间: {taskData["issuedAt"]}");
|
||
}
|
||
}
|
||
```
|
||
|
||
## 五、完整流程示例
|
||
|
||
### 5.1 Python 完整示例（包含二维码扫描）
|
||
|
||
```python
|
||
import base64
|
||
import json
|
||
import hashlib
|
||
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
|
||
from pyzbar import pyzbar
|
||
from PIL import Image
|
||
|
||
class TaskQRCodeDecoder:
|
||
"""任务二维码解码器"""
|
||
|
||
def __init__(self, licence: str, fingerprint: str):
|
||
"""
|
||
初始化解码器
|
||
|
||
Args:
|
||
licence: 设备授权码
|
||
fingerprint: 设备硬件指纹
|
||
"""
|
||
self.licence = licence
|
||
self.fingerprint = fingerprint
|
||
self._key = self._generate_key()
|
||
|
||
def _generate_key(self) -> bytes:
|
||
"""生成 AES-256 密钥"""
|
||
combined = self.licence + self.fingerprint
|
||
return hashlib.sha256(combined.encode('utf-8')).digest()
|
||
|
||
def scan_qr_code(self, qr_image_path: str) -> dict:
|
||
"""
|
||
扫描二维码并解密任务数据
|
||
|
||
Args:
|
||
qr_image_path: 二维码图片路径
|
||
|
||
Returns:
|
||
解密后的任务数据（字典）
|
||
"""
|
||
# 1. 扫描二维码
|
||
image = Image.open(qr_image_path)
|
||
qr_codes = pyzbar.decode(image)
|
||
|
||
if not qr_codes:
|
||
raise ValueError("未找到二维码")
|
||
|
||
# 获取二维码内容（Base64编码的加密数据）
|
||
encrypted_data_base64 = qr_codes[0].data.decode('utf-8')
|
||
print(f"扫描到二维码内容: {encrypted_data_base64[:50]}...")
|
||
|
||
# 2. 解密任务数据
|
||
return self.decrypt_task_data(encrypted_data_base64)
|
||
|
||
def decrypt_task_data(self, encrypted_data_base64: str) -> dict:
|
||
"""
|
||
解密任务数据
|
||
|
||
Args:
|
||
encrypted_data_base64: Base64编码的加密数据
|
||
|
||
Returns:
|
||
解密后的任务数据（字典）
|
||
"""
|
||
# 1. Base64 解码
|
||
encrypted_bytes = base64.b64decode(encrypted_data_base64)
|
||
|
||
# 2. 分离 IV 和加密数据（包含认证标签）
|
||
if len(encrypted_bytes) < 12:
|
||
raise ValueError("加密数据格式错误：数据长度不足")
|
||
|
||
iv = encrypted_bytes[:12] # IV: 前12字节
|
||
ciphertext_with_tag = encrypted_bytes[12:] # 加密数据 + 认证标签
|
||
|
||
# 3. 使用 AES-256-GCM 解密
|
||
aesgcm = AESGCM(self._key)
|
||
decrypted_bytes = aesgcm.decrypt(iv, ciphertext_with_tag, None)
|
||
|
||
# 4. 解析 JSON
|
||
decrypted_json = decrypted_bytes.decode('utf-8')
|
||
task_data = json.loads(decrypted_json)
|
||
|
||
return task_data
|
||
|
||
# 使用示例
|
||
if __name__ == "__main__":
|
||
# 工具箱的授权信息（必须与平台绑定时一致）
|
||
licence = "LIC-8F2A-XXXX"
|
||
fingerprint = "FP-2c91e9f3"
|
||
|
||
# 创建解码器
|
||
decoder = TaskQRCodeDecoder(licence, fingerprint)
|
||
|
||
# 扫描二维码并解密
|
||
try:
|
||
task_data = decoder.scan_qr_code("task_qr_code.png")
|
||
|
||
print("\n=== 任务信息 ===")
|
||
print(f"任务ID: {task_data['taskId']}")
|
||
print(f"企业ID: {task_data['enterpriseId']}")
|
||
print(f"单位名称: {task_data['orgName']}")
|
||
print(f"检查ID: {task_data['inspectionId']}")
|
||
print(f"检查人: {task_data['inspectionPerson']}")
|
||
print(f"发布时间: {task_data['issuedAt']}")
|
||
|
||
# 可以使用任务信息执行检查任务
|
||
# execute_inspection_task(task_data)
|
||
|
||
except Exception as e:
|
||
print(f"解密失败: {e}")
|
||
```
|
||
|
||
### 5.2 Java/Kotlin 完整示例（包含二维码扫描）
|
||
|
||
```kotlin
|
||
import com.fasterxml.jackson.databind.ObjectMapper
|
||
import com.google.zxing.BinaryBitmap
|
||
import com.google.zxing.MultiFormatReader
|
||
import com.google.zxing.Result
|
||
import com.google.zxing.client.j2se.BufferedImageLuminanceSource
|
||
import com.google.zxing.common.HybridBinarizer
|
||
import java.awt.image.BufferedImage
|
||
import java.io.File
|
||
import java.nio.charset.StandardCharsets
|
||
import java.security.MessageDigest
|
||
import java.util.Base64
|
||
import javax.crypto.Cipher
|
||
import javax.crypto.spec.GCMParameterSpec
|
||
import javax.crypto.spec.SecretKeySpec
|
||
import javax.imageio.ImageIO
|
||
|
||
class TaskQRCodeDecoder(
|
||
private val licence: String,
|
||
private val fingerprint: String
|
||
) {
|
||
|
||
private val key: SecretKeySpec by lazy {
|
||
val combined = "$licence$fingerprint"
|
||
val digest = MessageDigest.getInstance("SHA-256")
|
||
val keyBytes = digest.digest(combined.toByteArray(StandardCharsets.UTF_8))
|
||
SecretKeySpec(keyBytes, "AES")
|
||
}
|
||
|
||
private val objectMapper = ObjectMapper()
|
||
|
||
/**
|
||
* 扫描二维码并解密任务数据
|
||
*/
|
||
fun scanAndDecrypt(qrImagePath: String): Map<String, Any> {
|
||
// 1. 扫描二维码
|
||
val image: BufferedImage = ImageIO.read(File(qrImagePath))
|
||
val source = BufferedImageLuminanceSource(image)
|
||
val bitmap = BinaryBitmap(HybridBinarizer(source))
|
||
val reader = MultiFormatReader()
|
||
val result: Result = reader.decode(bitmap)
|
||
|
||
// 获取二维码内容（Base64编码的加密数据）
|
||
val encryptedDataBase64 = result.text
|
||
println("扫描到二维码内容: ${encryptedDataBase64.take(50)}...")
|
||
|
||
// 2. 解密任务数据
|
||
return decryptTaskData(encryptedDataBase64)
|
||
}
|
||
|
||
/**
|
||
* 解密任务数据
|
||
*/
|
||
fun decryptTaskData(encryptedDataBase64: String): Map<String, Any> {
|
||
// 1. Base64 解码
|
||
val encryptedBytes = Base64.getDecoder().decode(encryptedDataBase64)
|
||
|
||
// 2. 分离 IV 和加密数据（包含认证标签）
|
||
if (encryptedBytes.size < 12) {
|
||
throw IllegalArgumentException("加密数据格式错误：数据长度不足")
|
||
}
|
||
|
||
val iv = encryptedBytes.sliceArray(0 until 12)
|
||
val ciphertextWithTag = encryptedBytes.sliceArray(12 until encryptedBytes.size)
|
||
|
||
// 3. 使用 AES-256-GCM 解密
|
||
val cipher = Cipher.getInstance("AES/GCM/NoPadding")
|
||
val parameterSpec = GCMParameterSpec(16 * 8, iv) // 标签长度以位为单位
|
||
cipher.init(Cipher.DECRYPT_MODE, key, parameterSpec)
|
||
|
||
// 解密数据（GCM 会自动验证认证标签）
|
||
val decryptedBytes = cipher.doFinal(ciphertextWithTag)
|
||
|
||
// 4. 解析 JSON
|
||
val decryptedJson = String(decryptedBytes, StandardCharsets.UTF_8)
|
||
@Suppress("UNCHECKED_CAST")
|
||
return objectMapper.readValue(decryptedJson, Map::class.java) as Map<String, Any>
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
fun main() {
|
||
// 工具箱的授权信息（必须与平台绑定时一致）
|
||
val licence = "LIC-8F2A-XXXX"
|
||
val fingerprint = "FP-2c91e9f3"
|
||
|
||
// 创建解码器
|
||
val decoder = TaskQRCodeDecoder(licence, fingerprint)
|
||
|
||
// 扫描二维码并解密
|
||
try {
|
||
val taskData = decoder.scanAndDecrypt("task_qr_code.png")
|
||
|
||
println("\n=== 任务信息 ===")
|
||
println("任务ID: ${taskData["taskId"]}")
|
||
println("企业ID: ${taskData["enterpriseId"]}")
|
||
println("单位名称: ${taskData["orgName"]}")
|
||
println("检查ID: ${taskData["inspectionId"]}")
|
||
println("检查人: ${taskData["inspectionPerson"]}")
|
||
println("发布时间: ${taskData["issuedAt"]}")
|
||
|
||
// 可以使用任务信息执行检查任务
|
||
// executeInspectionTask(taskData)
|
||
|
||
} catch (e: Exception) {
|
||
println("解密失败: ${e.message}")
|
||
}
|
||
}
|
||
```
|
||
|
||
## 六、常见错误和注意事项
|
||
|
||
### 6.1 解密失败
|
||
|
||
**可能原因**：
|
||
1. **密钥不匹配**：`licence` 或 `fingerprint` 与平台绑定时不一致
|
||
- 确保使用与设备授权时相同的 `licence` 和 `fingerprint`
|
||
- 检查字符串拼接是否正确（无分隔符）
|
||
|
||
2. **数据格式错误**：Base64 编码或数据布局错误
|
||
- 确保 Base64 解码正确
|
||
- 确保 IV 长度正确（12 字节）
|
||
|
||
3. **认证标签验证失败**：数据被篡改或损坏
|
||
- GCM 模式会自动验证认证标签
|
||
- 如果验证失败，说明数据被篡改或密钥错误
|
||
|
||
4. **算法不匹配**：必须使用 `AES/GCM/NoPadding`
|
||
- 确保使用正确的加密算法
|
||
- 确保认证标签长度为 128 位（16 字节）
|
||
|
||
### 6.2 二维码扫描失败
|
||
|
||
**可能原因**：
|
||
1. **二维码图片质量差**：确保图片清晰，有足够的对比度
|
||
2. **二维码内容过长**：如果加密数据过长，可能需要更高版本的二维码
|
||
3. **扫描库不支持**：确保使用支持 Base64 字符串的二维码扫描库
|
||
|
||
### 6.3 JSON 解析失败
|
||
|
||
**可能原因**：
|
||
1. **字符编码错误**：确保使用 UTF-8 编码
|
||
2. **JSON 格式错误**：确保解密后的字符串是有效的 JSON
|
||
3. **字段缺失**：确保所有必需字段都存在
|
||
|
||
## 七、安全设计说明
|
||
|
||
### 7.1 为什么使用 AES-256-GCM
|
||
|
||
1. **认证加密（AEAD）**：GCM 模式提供加密和认证，防止数据被篡改
|
||
2. **强安全性**：AES-256 提供 256 位密钥强度
|
||
3. **自动验证**：GCM 模式会自动验证认证标签，任何篡改都会导致解密失败
|
||
|
||
### 7.2 为什么第三方无法解密
|
||
|
||
1. **密钥绑定**：只有拥有正确 `licence + fingerprint` 的工具箱才能生成正确的密钥
|
||
2. **认证标签**：GCM 模式会验证认证标签，任何篡改都会导致解密失败
|
||
3. **密钥唯一性**：每个设备的 `licence + fingerprint` 组合是唯一的
|
||
|
||
### 7.3 密钥生成的安全性
|
||
|
||
1. **SHA-256 哈希**：使用强哈希算法生成密钥
|
||
2. **密钥长度**：使用全部 32 字节作为 AES-256 密钥
|
||
3. **密钥隔离**：每个设备的密钥是独立的，互不影响
|
||
|
||
## 八、测试建议
|
||
|
||
1. **单元测试**：
|
||
- 测试密钥生成是否正确
|
||
- 测试解密功能是否正常
|
||
- 测试 JSON 解析是否正确
|
||
|
||
2. **集成测试**：
|
||
- 使用真实平台生成的二维码进行测试
|
||
- 测试不同长度的任务数据
|
||
- 测试错误的密钥是否会导致解密失败
|
||
|
||
3. **边界测试**：
|
||
- 测试超长的任务数据
|
||
- 测试特殊字符的处理
|
||
- 测试错误的 Base64 格式
|
||
|
||
## 九、参考实现
|
||
|
||
- **Python**：`cryptography` 库（AES-GCM 加密）、`pyzbar` 库（二维码扫描）
|
||
- **Java/Kotlin**：JDK `javax.crypto`（AES-GCM 加密）、ZXing 库（二维码扫描）
|
||
- **C#**：`System.Security.Cryptography`（AES-GCM 加密）、ZXing.Net 库（二维码扫描）
|
||
|
||
## 十、联系支持
|
||
|
||
如有问题，请联系平台技术支持团队获取：
|
||
- 测试环境地址
|
||
- 技术支持
|
||
|