648 lines
21 KiB
Markdown
648 lines
21 KiB
Markdown
# 工具箱端 - 报告加密与签名生成指南
|
||
|
||
## 概述
|
||
|
||
本文档说明工具箱端如何生成加密和签名的检查报告 ZIP 文件，以确保：
|
||
1. **授权校验**：只有合法授权的工具箱才能生成有效的报告
|
||
2. **防篡改校验**：确保报告内容在传输过程中未被篡改
|
||
|
||
> ### UX 集成模式补充（当前项目实现）
|
||
>
|
||
> 在当前集成模式中，工具箱可将原始报告 ZIP 直接上传到 UX 的 `crypto.signAndPackReport`：
|
||
>
|
||
> 1. 工具箱先通过 `config.setLicence` 完成本地 licence 配置；
|
||
> 2. 工具箱传入 `pgpPrivateKey`、`signingContext`、`summaryJson` 与 `rawZip`；
|
||
> 3. UX 从本地配置读取 licence/fingerprint，执行签名与打包能力，生成 `summary.json`、`META-INF/manifest.json`、`META-INF/signature.asc`；
|
||
> 4. UX 返回签名后的 ZIP（二进制文件响应），工具箱再用于离线介质回传平台。
|
||
|
||
## 一、ZIP 文件结构要求
|
||
|
||
工具箱生成的 ZIP 文件必须包含以下文件：
|
||
|
||
```
|
||
report.zip
|
||
├── summary.json # 摘要信息（必须包含授权和签名字段）
|
||
├── assets.json # 资产信息（用于签名校验）
|
||
├── vulnerabilities.json # 漏洞信息（用于签名校验）
|
||
├── weakPasswords.json # 弱密码信息（用于签名校验）
|
||
├── 漏洞评估报告.html # 漏洞评估报告（用于签名校验）
|
||
└── META-INF/
|
||
├── manifest.json # 文件清单（用于 OpenPGP 签名）
|
||
└── signature.asc # OpenPGP 签名文件（防篡改）
|
||
```
|
||
|
||
## 二、授权校验 - 设备签名（device_signature）
|
||
|
||
### 2.1 目的
|
||
|
||
设备签名用于验证报告是由合法授权的工具箱生成的，防止第三方伪造扫描结果。
|
||
|
||
### 2.2 密钥派生
|
||
|
||
使用 **HKDF-SHA256** 从设备的 `licence` 和 `fingerprint` 派生签名密钥：
|
||
|
||
```
|
||
K = HKDF(
|
||
input = licence + fingerprint, # 输入密钥材料（字符串拼接）
|
||
salt = "AUTH_V3_SALT", # 固定盐值
|
||
info = "device_report_signature", # 固定信息参数
|
||
hash = SHA-256, # 哈希算法
|
||
length = 32 # 输出密钥长度（32字节 = 256位）
|
||
)
|
||
```
|
||
|
||
**伪代码示例**：
|
||
```python
|
||
import hkdf
|
||
|
||
# 输入密钥材料
|
||
ikm = licence + fingerprint # 字符串直接拼接
|
||
|
||
# HKDF 参数
|
||
salt = "AUTH_V3_SALT"
|
||
info = "device_report_signature"
|
||
key_length = 32 # 32字节 = 256位
|
||
|
||
# 派生密钥
|
||
derived_key = hkdf.HKDF(
|
||
algorithm=hashlib.sha256,
|
||
length=key_length,
|
||
salt=salt.encode('utf-8'),
|
||
info=info.encode('utf-8'),
|
||
ikm=ikm.encode('utf-8')
|
||
).derive()
|
||
```
|
||
|
||
### 2.3 签名数据组装（严格顺序）
|
||
|
||
签名数据必须按照以下**严格顺序**组装：
|
||
|
||
```
|
||
sign_payload =
|
||
taskId + # 任务ID（字符串）
|
||
inspectionId + # 检查ID（数字转字符串）
|
||
SHA256(assets.json) + # assets.json 的 SHA256（hex字符串，小写）
|
||
SHA256(vulnerabilities.json) + # vulnerabilities.json 的 SHA256（hex字符串，小写）
|
||
SHA256(weakPasswords.json) + # weakPasswords.json 的 SHA256（hex字符串，小写）
|
||
SHA256(漏洞评估报告.html) # 漏洞评估报告.html 的 SHA256（hex字符串，小写）
|
||
```
|
||
|
||
**重要说明**：
|
||
- 所有字符串直接拼接，**不添加任何分隔符**
|
||
- SHA256 哈希值必须是 **hex 字符串（小写）**，例如：`a1b2c3d4...`
|
||
- 文件内容必须是**原始字节**，不能进行任何编码转换
|
||
- 顺序必须严格一致，任何顺序错误都会导致签名验证失败
|
||
|
||
**伪代码示例**：
|
||
```python
|
||
import hashlib
|
||
|
||
# 1. 读取文件内容（原始字节）
|
||
assets_content = read_file("assets.json")
|
||
vulnerabilities_content = read_file("vulnerabilities.json")
|
||
weak_passwords_content = read_file("weakPasswords.json")
|
||
report_html_content = read_file("漏洞评估报告.html")
|
||
|
||
# 2. 计算 SHA256（hex字符串，小写）
|
||
def sha256_hex(content: bytes) -> str:
|
||
return hashlib.sha256(content).hexdigest()
|
||
|
||
assets_sha256 = sha256_hex(assets_content)
|
||
vulnerabilities_sha256 = sha256_hex(vulnerabilities_content)
|
||
weak_passwords_sha256 = sha256_hex(weak_passwords_content)
|
||
report_html_sha256 = sha256_hex(report_html_content)
|
||
|
||
# 3. 组装签名数据（严格顺序，直接拼接）
|
||
sign_payload = (
|
||
str(task_id) +
|
||
str(inspection_id) +
|
||
assets_sha256 +
|
||
vulnerabilities_sha256 +
|
||
weak_passwords_sha256 +
|
||
report_html_sha256
|
||
)
|
||
```
|
||
|
||
### 2.4 生成设备签名
|
||
|
||
使用 **HMAC-SHA256** 计算签名：
|
||
|
||
```
|
||
device_signature = Base64(HMAC-SHA256(key=K, data=sign_payload))
|
||
```
|
||
|
||
**伪代码示例**：
|
||
```python
|
||
import hmac
|
||
import base64
|
||
|
||
# 使用派生密钥计算 HMAC-SHA256
|
||
mac = hmac.new(
|
||
key=derived_key, # 派生密钥（32字节）
|
||
msg=sign_payload.encode('utf-8'), # 签名数据（UTF-8编码）
|
||
digestmod=hashlib.sha256
|
||
)
|
||
|
||
# 计算签名
|
||
signature_bytes = mac.digest()
|
||
|
||
# Base64 编码
|
||
device_signature = base64.b64encode(signature_bytes).decode('utf-8')
|
||
```
|
||
|
||
### 2.5 写入 summary.json
|
||
|
||
将 `device_signature` 写入 `summary.json`：
|
||
|
||
```json
|
||
{
|
||
"orgId": 1173040813421105152,
|
||
"checkId": 702286470691215417,
|
||
"taskId": "TASK-20260115-4875",
|
||
"licence": "LIC-8F2A-XXXX",
|
||
"fingerprint": "FP-2c91e9f3",
|
||
"deviceSignature": "Base64编码的签名值",
|
||
"summary": "检查摘要信息",
|
||
...其他字段...
|
||
}
|
||
```
|
||
|
||
**必需字段**：
|
||
- `licence`：设备授权码（字符串）
|
||
- `fingerprint`：设备硬件指纹（字符串）
|
||
- `taskId`：任务ID（字符串）
|
||
- `deviceSignature`：设备签名（Base64字符串）
|
||
- `checkId` 或 `inspectionId`：检查ID（数字）
|
||
|
||
## 三、防篡改校验 - OpenPGP 签名
|
||
|
||
### 3.1 目的
|
||
|
||
OpenPGP 签名用于验证 ZIP 文件在传输过程中未被篡改，确保文件完整性。
|
||
|
||
### 3.2 生成 manifest.json
|
||
|
||
创建 `META-INF/manifest.json` 文件，包含所有文件的 SHA-256 哈希值：
|
||
|
||
```json
|
||
{
|
||
"files": {
|
||
"summary.json": "a1b2c3d4e5f6...",
|
||
"assets.json": "b2c3d4e5f6a1...",
|
||
"vulnerabilities.json": "c3d4e5f6a1b2...",
|
||
"weakPasswords.json": "d4e5f6a1b2c3...",
|
||
"漏洞评估报告.html": "e5f6a1b2c3d4..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**伪代码示例**：
|
||
```python
|
||
import hashlib
|
||
import json
|
||
|
||
def calculate_sha256_hex(content: bytes) -> str:
|
||
return hashlib.sha256(content).hexdigest()
|
||
|
||
# 计算所有文件的 SHA256
|
||
files_hashes = {
|
||
"summary.json": calculate_sha256_hex(summary_content),
|
||
"assets.json": calculate_sha256_hex(assets_content),
|
||
"vulnerabilities.json": calculate_sha256_hex(vulnerabilities_content),
|
||
"weakPasswords.json": calculate_sha256_hex(weak_passwords_content),
|
||
"漏洞评估报告.html": calculate_sha256_hex(report_html_content)
|
||
}
|
||
|
||
# 生成 manifest.json
|
||
manifest = {
|
||
"files": files_hashes
|
||
}
|
||
|
||
manifest_json = json.dumps(manifest, ensure_ascii=False, indent=2)
|
||
```
|
||
|
||
### 3.3 生成 OpenPGP 签名
|
||
|
||
使用工具箱的**私钥**对 `manifest.json` 进行 OpenPGP 签名，生成 `META-INF/signature.asc`：
|
||
|
||
**伪代码示例（使用 Python gnupg）**：
|
||
```python
|
||
import gnupg
|
||
|
||
# 初始化 GPG
|
||
gpg = gnupg.GPG()
|
||
|
||
# 导入私钥（或使用已配置的密钥）
|
||
# gpg.import_keys(private_key_data)
|
||
|
||
# 对 manifest.json 进行签名
|
||
with open('META-INF/manifest.json', 'rb') as f:
|
||
signed_data = gpg.sign_file(
|
||
f,
|
||
detach=True, # 分离式签名
|
||
clearsign=False, # 不使用明文签名
|
||
output='META-INF/signature.asc'
|
||
)
|
||
```
|
||
|
||
**伪代码示例（使用 BouncyCastle - Java/Kotlin）**：
|
||
```kotlin
|
||
import org.bouncycastle.openpgp.*
|
||
import org.bouncycastle.openpgp.operator.jcajce.JcaPGPContentSignerBuilder
|
||
import org.bouncycastle.openpgp.operator.jcajce.JcaPGPPrivateKey
|
||
import java.io.ByteArrayOutputStream
|
||
import java.io.FileOutputStream
|
||
|
||
fun generatePGPSignature(
|
||
manifestContent: ByteArray,
|
||
privateKey: PGPPrivateKey,
|
||
publicKey: PGPPublicKey
|
||
): ByteArray {
|
||
val signatureGenerator = PGPSignatureGenerator(
|
||
JcaPGPContentSignerBuilder(publicKey.algorithm, PGPUtil.SHA256)
|
||
)
|
||
signatureGenerator.init(PGPSignature.BINARY_DOCUMENT, privateKey)
|
||
signatureGenerator.update(manifestContent)
|
||
|
||
val signature = signatureGenerator.generate()
|
||
val signatureList = PGPSignatureList(signature)
|
||
|
||
val out = ByteArrayOutputStream()
|
||
val pgpOut = PGPObjectFactory(PGPUtil.getEncoderStream(out))
|
||
signatureList.encode(out)
|
||
|
||
return out.toByteArray()
|
||
}
|
||
```
|
||
|
||
### 3.4 打包 ZIP 文件
|
||
|
||
将所有文件打包成 ZIP 文件，确保包含：
|
||
- 所有报告文件（summary.json、assets.json 等）
|
||
- `META-INF/manifest.json`
|
||
- `META-INF/signature.asc`
|
||
|
||
**伪代码示例**：
|
||
```python
|
||
import zipfile
|
||
|
||
def create_signed_zip(output_path: str):
|
||
with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
|
||
# 添加报告文件
|
||
zipf.write('summary.json', 'summary.json')
|
||
zipf.write('assets.json', 'assets.json')
|
||
zipf.write('vulnerabilities.json', 'vulnerabilities.json')
|
||
zipf.write('weakPasswords.json', 'weakPasswords.json')
|
||
zipf.write('漏洞评估报告.html', '漏洞评估报告.html')
|
||
|
||
# 添加签名文件
|
||
zipf.write('META-INF/manifest.json', 'META-INF/manifest.json')
|
||
zipf.write('META-INF/signature.asc', 'META-INF/signature.asc')
|
||
```
|
||
|
||
## 四、完整流程示例
|
||
|
||
### 4.1 Python 完整示例
|
||
|
||
```python
|
||
import hashlib
|
||
import hmac
|
||
import base64
|
||
import json
|
||
import zipfile
|
||
import hkdf
|
||
import gnupg
|
||
|
||
def generate_report_zip(
|
||
licence: str,
|
||
fingerprint: str,
|
||
task_id: str,
|
||
inspection_id: int,
|
||
output_path: str
|
||
):
|
||
"""
|
||
生成带签名和加密的检查报告 ZIP 文件
|
||
"""
|
||
|
||
# ========== 1. 读取报告文件 ==========
|
||
assets_content = read_file("assets.json")
|
||
vulnerabilities_content = read_file("vulnerabilities.json")
|
||
weak_passwords_content = read_file("weakPasswords.json")
|
||
report_html_content = read_file("漏洞评估报告.html")
|
||
|
||
# ========== 2. 生成设备签名 ==========
|
||
|
||
# 2.1 密钥派生
|
||
ikm = licence + fingerprint
|
||
salt = "AUTH_V3_SALT"
|
||
info = "device_report_signature"
|
||
key_length = 32
|
||
|
||
derived_key = hkdf.HKDF(
|
||
algorithm=hashlib.sha256,
|
||
length=key_length,
|
||
salt=salt.encode('utf-8'),
|
||
info=info.encode('utf-8'),
|
||
ikm=ikm.encode('utf-8')
|
||
).derive()
|
||
|
||
# 2.2 计算文件 SHA256
|
||
def sha256_hex(content: bytes) -> str:
|
||
return hashlib.sha256(content).hexdigest()
|
||
|
||
assets_sha256 = sha256_hex(assets_content)
|
||
vulnerabilities_sha256 = sha256_hex(vulnerabilities_content)
|
||
weak_passwords_sha256 = sha256_hex(weak_passwords_content)
|
||
report_html_sha256 = sha256_hex(report_html_content)
|
||
|
||
# 2.3 组装签名数据（严格顺序）
|
||
sign_payload = (
|
||
str(task_id) +
|
||
str(inspection_id) +
|
||
assets_sha256 +
|
||
vulnerabilities_sha256 +
|
||
weak_passwords_sha256 +
|
||
report_html_sha256
|
||
)
|
||
|
||
# 2.4 计算 HMAC-SHA256
|
||
mac = hmac.new(
|
||
key=derived_key,
|
||
msg=sign_payload.encode('utf-8'),
|
||
digestmod=hashlib.sha256
|
||
)
|
||
device_signature = base64.b64encode(mac.digest()).decode('utf-8')
|
||
|
||
# 2.5 生成 summary.json
|
||
summary = {
|
||
"orgId": 1173040813421105152,
|
||
"checkId": inspection_id,
|
||
"taskId": task_id,
|
||
"licence": licence,
|
||
"fingerprint": fingerprint,
|
||
"deviceSignature": device_signature,
|
||
"summary": "检查摘要信息"
|
||
}
|
||
summary_content = json.dumps(summary, ensure_ascii=False).encode('utf-8')
|
||
|
||
# ========== 3. 生成 OpenPGP 签名 ==========
|
||
|
||
# 3.1 生成 manifest.json
|
||
files_hashes = {
|
||
"summary.json": sha256_hex(summary_content),
|
||
"assets.json": assets_sha256,
|
||
"vulnerabilities.json": vulnerabilities_sha256,
|
||
"weakPasswords.json": weak_passwords_sha256,
|
||
"漏洞评估报告.html": report_html_sha256
|
||
}
|
||
manifest = {"files": files_hashes}
|
||
manifest_content = json.dumps(manifest, ensure_ascii=False, indent=2).encode('utf-8')
|
||
|
||
# 3.2 生成 OpenPGP 签名
|
||
gpg = gnupg.GPG()
|
||
with open('META-INF/manifest.json', 'wb') as f:
|
||
f.write(manifest_content)
|
||
|
||
with open('META-INF/manifest.json', 'rb') as f:
|
||
signed_data = gpg.sign_file(
|
||
f,
|
||
detach=True,
|
||
output='META-INF/signature.asc'
|
||
)
|
||
|
||
# ========== 4. 打包 ZIP 文件 ==========
|
||
with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
|
||
zipf.writestr('summary.json', summary_content)
|
||
zipf.writestr('assets.json', assets_content)
|
||
zipf.writestr('vulnerabilities.json', vulnerabilities_content)
|
||
zipf.writestr('weakPasswords.json', weak_passwords_content)
|
||
zipf.writestr('漏洞评估报告.html', report_html_content)
|
||
zipf.writestr('META-INF/manifest.json', manifest_content)
|
||
zipf.write('META-INF/signature.asc', 'META-INF/signature.asc')
|
||
|
||
print(f"报告 ZIP 文件生成成功: {output_path}")
|
||
```
|
||
|
||
### 4.2 Java/Kotlin 完整示例
|
||
|
||
```kotlin
|
||
import org.bouncycastle.crypto.digests.SHA256Digest
|
||
import org.bouncycastle.crypto.generators.HKDFBytesGenerator
|
||
import org.bouncycastle.crypto.params.HKDFParameters
|
||
import java.security.MessageDigest
|
||
import javax.crypto.Mac
|
||
import javax.crypto.spec.SecretKeySpec
|
||
import java.util.Base64
|
||
import java.util.zip.ZipOutputStream
|
||
import java.io.FileOutputStream
|
||
|
||
fun generateReportZip(
|
||
licence: String,
|
||
fingerprint: String,
|
||
taskId: String,
|
||
inspectionId: Long,
|
||
outputPath: String
|
||
) {
|
||
// ========== 1. 读取报告文件 ==========
|
||
val assetsContent = readFile("assets.json")
|
||
val vulnerabilitiesContent = readFile("vulnerabilities.json")
|
||
val weakPasswordsContent = readFile("weakPasswords.json")
|
||
val reportHtmlContent = readFile("漏洞评估报告.html")
|
||
|
||
// ========== 2. 生成设备签名 ==========
|
||
|
||
// 2.1 密钥派生
|
||
val ikm = (licence + fingerprint).toByteArray(Charsets.UTF_8)
|
||
val salt = "AUTH_V3_SALT".toByteArray(Charsets.UTF_8)
|
||
val info = "device_report_signature".toByteArray(Charsets.UTF_8)
|
||
val keyLength = 32
|
||
|
||
val hkdf = HKDFBytesGenerator(SHA256Digest())
|
||
hkdf.init(HKDFParameters(ikm, salt, info))
|
||
val derivedKey = ByteArray(keyLength)
|
||
hkdf.generateBytes(derivedKey, 0, keyLength)
|
||
|
||
// 2.2 计算文件 SHA256
|
||
fun sha256Hex(content: ByteArray): String {
|
||
val digest = MessageDigest.getInstance("SHA-256")
|
||
val hashBytes = digest.digest(content)
|
||
return hashBytes.joinToString("") { "%02x".format(it) }
|
||
}
|
||
|
||
val assetsSha256 = sha256Hex(assetsContent)
|
||
val vulnerabilitiesSha256 = sha256Hex(vulnerabilitiesContent)
|
||
val weakPasswordsSha256 = sha256Hex(weakPasswordsContent)
|
||
val reportHtmlSha256 = sha256Hex(reportHtmlContent)
|
||
|
||
// 2.3 组装签名数据（严格顺序）
|
||
val signPayload = buildString {
|
||
append(taskId)
|
||
append(inspectionId)
|
||
append(assetsSha256)
|
||
append(vulnerabilitiesSha256)
|
||
append(weakPasswordsSha256)
|
||
append(reportHtmlSha256)
|
||
}
|
||
|
||
// 2.4 计算 HMAC-SHA256
|
||
val mac = Mac.getInstance("HmacSHA256")
|
||
val secretKey = SecretKeySpec(derivedKey, "HmacSHA256")
|
||
mac.init(secretKey)
|
||
val signatureBytes = mac.doFinal(signPayload.toByteArray(Charsets.UTF_8))
|
||
val deviceSignature = Base64.getEncoder().encodeToString(signatureBytes)
|
||
|
||
// 2.5 生成 summary.json
|
||
val summary = mapOf(
|
||
"orgId" to 1173040813421105152L,
|
||
"checkId" to inspectionId,
|
||
"taskId" to taskId,
|
||
"licence" to licence,
|
||
"fingerprint" to fingerprint,
|
||
"deviceSignature" to deviceSignature,
|
||
"summary" to "检查摘要信息"
|
||
)
|
||
val summaryContent = objectMapper.writeValueAsString(summary).toByteArray(Charsets.UTF_8)
|
||
|
||
// ========== 3. 生成 OpenPGP 签名 ==========
|
||
|
||
// 3.1 生成 manifest.json
|
||
val filesHashes = mapOf(
|
||
"summary.json" to sha256Hex(summaryContent),
|
||
"assets.json" to assetsSha256,
|
||
"vulnerabilities.json" to vulnerabilitiesSha256,
|
||
"weakPasswords.json" to weakPasswordsSha256,
|
||
"漏洞评估报告.html" to reportHtmlSha256
|
||
)
|
||
val manifest = mapOf("files" to filesHashes)
|
||
val manifestContent = objectMapper.writeValueAsString(manifest).toByteArray(Charsets.UTF_8)
|
||
|
||
// 3.2 生成 OpenPGP 签名（使用 BouncyCastle）
|
||
val signatureAsc = generatePGPSignature(manifestContent, privateKey, publicKey)
|
||
|
||
// ========== 4. 打包 ZIP 文件 ==========
|
||
ZipOutputStream(FileOutputStream(outputPath)).use { zipOut ->
|
||
zipOut.putNextEntry(ZipEntry("summary.json"))
|
||
zipOut.write(summaryContent)
|
||
zipOut.closeEntry()
|
||
|
||
zipOut.putNextEntry(ZipEntry("assets.json"))
|
||
zipOut.write(assetsContent)
|
||
zipOut.closeEntry()
|
||
|
||
zipOut.putNextEntry(ZipEntry("vulnerabilities.json"))
|
||
zipOut.write(vulnerabilitiesContent)
|
||
zipOut.closeEntry()
|
||
|
||
zipOut.putNextEntry(ZipEntry("weakPasswords.json"))
|
||
zipOut.write(weakPasswordsContent)
|
||
zipOut.closeEntry()
|
||
|
||
zipOut.putNextEntry(ZipEntry("漏洞评估报告.html"))
|
||
zipOut.write(reportHtmlContent)
|
||
zipOut.closeEntry()
|
||
|
||
zipOut.putNextEntry(ZipEntry("META-INF/manifest.json"))
|
||
zipOut.write(manifestContent)
|
||
zipOut.closeEntry()
|
||
|
||
zipOut.putNextEntry(ZipEntry("META-INF/signature.asc"))
|
||
zipOut.write(signatureAsc)
|
||
zipOut.closeEntry()
|
||
}
|
||
|
||
println("报告 ZIP 文件生成成功: $outputPath")
|
||
}
|
||
```
|
||
|
||
## 五、平台端验证流程
|
||
|
||
平台端会按以下顺序验证：
|
||
|
||
1. **OpenPGP 签名验证**（防篡改）
|
||
- 读取 `META-INF/manifest.json` 和 `META-INF/signature.asc`
|
||
- 使用平台公钥验证签名
|
||
- 验证所有文件的 SHA256 是否与 manifest.json 中的哈希值匹配
|
||
|
||
2. **设备签名验证**（授权）
|
||
- 从 `summary.json` 提取 `licence`、`fingerprint`、`taskId`、`deviceSignature`
|
||
- 验证 `licence + fingerprint` 是否已绑定
|
||
- 验证 `taskId` 是否存在且属于该设备
|
||
- 使用相同的 HKDF 派生密钥
|
||
- 重新计算签名并与 `deviceSignature` 比较
|
||
|
||
## 六、常见错误和注意事项
|
||
|
||
### 6.1 设备签名验证失败
|
||
|
||
**可能原因**：
|
||
1. **密钥派生错误**：确保使用正确的 `salt` 和 `info` 参数
|
||
2. **签名数据顺序错误**：必须严格按照 `taskId + inspectionId + SHA256(...)` 的顺序
|
||
3. **SHA256 格式错误**：必须是 hex 字符串（小写），不能包含分隔符
|
||
4. **文件内容错误**：确保使用原始文件内容，不能进行编码转换
|
||
5. **licence 或 fingerprint 不匹配**：确保与平台绑定的值一致
|
||
|
||
### 6.2 OpenPGP 签名验证失败
|
||
|
||
**可能原因**：
|
||
1. **私钥不匹配**：确保使用与平台公钥对应的私钥
|
||
2. **manifest.json 格式错误**：确保 JSON 格式正确
|
||
3. **文件哈希值错误**：确保 manifest.json 中的哈希值与实际文件匹配
|
||
|
||
### 6.3 文件缺失
|
||
|
||
**必需文件**：
|
||
- `summary.json`（必须包含授权字段）
|
||
- `assets.json`
|
||
- `vulnerabilities.json`
|
||
- `weakPasswords.json`（文件名大小写不敏感）
|
||
- `漏洞评估报告.html`（文件名包含"漏洞评估报告"且以".html"结尾）
|
||
- `META-INF/manifest.json`
|
||
- `META-INF/signature.asc`
|
||
|
||
## 七、安全设计说明
|
||
|
||
### 7.1 为什么第三方无法伪造
|
||
|
||
1. **设备签名**：
|
||
- 只有拥有正确 `licence + fingerprint` 的设备才能派生正确的签名密钥
|
||
- 即使第三方获取了某个设备的签名，也无法用于其他任务（`taskId` 绑定）
|
||
- 即使第三方修改了报告内容，签名也会失效（多个文件的 SHA256 绑定）
|
||
|
||
2. **OpenPGP 签名**：
|
||
- 只有拥有私钥的工具箱才能生成有效签名
|
||
- 任何文件修改都会导致哈希值不匹配
|
||
|
||
### 7.2 密钥分离
|
||
|
||
使用 HKDF 的 `info` 参数区分不同用途的密钥：
|
||
- `device_report_signature`：用于设备签名
|
||
- 其他用途可以使用不同的 `info` 值，确保密钥隔离
|
||
|
||
## 八、测试建议
|
||
|
||
1. **单元测试**：
|
||
- 测试密钥派生是否正确
|
||
- 测试签名生成和验证是否匹配
|
||
- 测试文件 SHA256 计算是否正确
|
||
|
||
2. **集成测试**：
|
||
- 使用真实数据生成 ZIP 文件
|
||
- 上传到平台验证是否通过
|
||
- 测试篡改文件后验证是否失败
|
||
|
||
3. **边界测试**：
|
||
- 测试文件缺失的情况
|
||
- 测试签名数据顺序错误的情况
|
||
- 测试错误的 `licence` 或 `fingerprint` 的情况
|
||
|
||
## 九、参考实现
|
||
|
||
- **HKDF 实现**：BouncyCastle（Java/Kotlin）、`hkdf` 库（Python）
|
||
- **HMAC-SHA256**：Java `javax.crypto.Mac`、Python `hmac`
|
||
- **OpenPGP**：BouncyCastle（Java/Kotlin）、`gnupg` 库（Python）
|
||
|
||
## 十、联系支持
|
||
|
||
如有问题，请联系平台技术支持团队。
|
||
|