# java-signature

**Repository Path**: nacker/java-signature

## Basic Information

- **Project Name**: java-signature
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 雨后java签名接入工具使用文档

## 1. 工具说明

本工具是一个 JavaFX 桌面端应用，用于辅助接口接入过程中的 RSA + MD5 签名生成和本地验签。

主要能力：

1. 维护商户接入配置。
2. 导入 RSA 私钥和公钥。
3. 校验并格式化请求 JSON。
4. 按 `MD5withRSA` 规则生成请求签名。
5. 自动生成请求 Header。
6. 生成可复制的 cURL 示例。
7. 使用 RSA 公钥进行本地验签。
8. 查看 RSA 密钥生成和 PKCS8 转换说明。
9. 支持应用图标和系统托盘图标，关闭窗口时隐藏到托盘。

## 2. 运行环境

### 2.1 必要环境

本机需要安装：

1. JDK 17 或以上。
2. Windows PowerShell。

当前项目已提供本地 Maven 下载脚本。如果电脑没有安装 Maven，也可以直接运行脚本，脚本会自动下载 Maven 到项目目录下的 `.tools` 文件夹。

### 2.2 项目目录

项目目录示例：

```text
C:\Users\Administrator\Desktop\java-signature
```

主要文件：

| 文件 | 说明 |
| --- | --- |
| `run.ps1` | 启动桌面应用 |
| `build.ps1` | 编译项目 |
| `package.ps1` | 生成独立绿色包和 Windows `.exe` 安装器 |
| `pom.xml` | Maven 项目配置 |
| `需求.md` | 需求规划文档 |
| `使用文档.md` | 当前使用文档 |
| `src/main/java` | Java 源码 |
| `src/main/resources/app.css` | JavaFX 样式 |

## 3. 启动应用

打开 PowerShell，进入项目目录：

```powershell
cd C:\Users\Administrator\Desktop\java-signature
```

启动桌面应用：

```powershell
powershell -ExecutionPolicy Bypass -File .\run.ps1
```

首次启动时，如果本机没有 Maven，脚本会自动下载 Maven，耗时取决于网络情况。下载完成后会启动 JavaFX 桌面窗口。

也可以直接双击项目目录下的：

```text
启动.bat
```

如果已经执行过 `build.ps1` 或 `run.ps1`，也可以直接执行：

```powershell
java -jar target\yuhou-java-signature-tool-1.0.0.jar
```

注意：不要只复制 `target\yuhou-java-signature-tool-1.0.0.jar` 单个文件到其他目录运行。该 JAR 需要同目录下的 `target\lib` 依赖目录配合使用。如果缺少 `target\lib`，可能出现：

```text
错误: 缺少 JavaFX 运行时组件, 需要使用该组件来运行此应用程序
```

推荐优先使用 `启动.bat` 或 `run.ps1` 启动，它们会自动构建并带上 `target\lib` 目录中的 JavaFX 依赖。

## 4. 编译项目

如果只想检查项目是否能正常编译，可以执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\build.ps1
```

编译成功后，会在以下位置生成 JAR：

```text
target\yuhou-java-signature-tool-1.0.0.jar
```

注意：这个 JAR 不是完整的独立安装包，推荐仍然使用 `run.ps1` 启动，因为 JavaFX 依赖由 Maven 处理。

## 4.1 独立安装包 / 绿色包打包

执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\package.ps1
```

脚本会生成自带 Java 运行时的绿色独立包：

```text
dist\雨后java签名接入工具-1.0.0-windows-portable.zip
```

同时会生成 Windows `.exe` 安装器：

```text
dist\雨后java签名接入工具-1.0.0.exe
```

使用方式：

1. 解压这个 zip。
2. 进入解压后的 `雨后java签名接入工具` 目录。
3. 双击 `雨后java签名接入工具.exe`。

该绿色包不要求用户电脑安装 JDK 或 Maven。应用配置文件会写到软件同级目录：

```text
雨后java签名接入工具\config.json
```

`package.ps1` 会自动下载本地 WiX Toolset 3.11 到 `.tools` 目录，用于生成 Windows `.exe` 安装器。WiX 不会安装到系统目录。

## 5. 页面功能说明

应用启动后，顶部有 4 个页面：

1. 商户配置
2. 生成签名
3. 本地验签
4. 帮助

窗口右上角关闭按钮不会直接退出程序，而是隐藏到系统托盘。双击托盘图标或右键选择“显示主窗口”可以恢复窗口；右键选择“退出”会真正关闭应用。

## 6. 商户配置

### 6.1 进入配置页

点击顶部的“商户配置”页签。

左侧是配置列表，右侧是当前配置详情。

### 6.2 新增配置

点击左侧“新增”按钮，会创建一个新的商户配置。

建议填写：

| 字段 | 是否必填 | 说明 |
| --- | --- | --- |
| 配置名称 | 否 | 方便区分不同商户或环境 |
| businessId | 是 | 商户编号 |
| 环境 | 是 | 默认生产环境 |
| 基础 URL | 是 | 默认 `https://api.example.com` |
| 回调地址 | 否 | 记录回调通知地址 |
| RSA 私钥 | 签名时必填 | 用于生成请求签名 |
| RSA 公钥 | 验签时必填 | 用于本地验签 |

### 6.3 导入私钥

支持两种方式：

1. 点击“导入私钥文件”，选择 `.pem`、`.key`、`.txt` 等文件。
2. 直接将私钥内容粘贴到“RSA 私钥”输入框。

私钥要求：

1. 必须是 RSA 私钥。
2. 必须是 PKCS8 格式。
3. 可以包含 PEM 头尾，例如：

```text
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
```

工具会自动忽略 PEM 头尾和换行。

### 6.4 检查私钥

点击“检查私钥”。

如果私钥格式正确，会提示：

```text
私钥可以被 Java 识别，格式为 PKCS8 RSA 私钥。
```

如果提示无法识别，通常说明私钥不是 PKCS8 格式，需要按本文档第 10 节进行转换。

### 6.5 导入公钥

支持两种方式：

1. 点击“导入公钥文件”。
2. 直接粘贴公钥内容。

公钥可以包含 PEM 头尾：

```text
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
```

工具会自动忽略头尾标识。

### 6.6 检查公钥

点击“检查公钥”。

如果公钥格式正确，会提示公钥可以被 Java 识别。

### 6.7 是否保存私钥

页面中有一个选项：

```text
保存私钥到本地配置文件
```

默认不建议勾选。

如果不勾选：

1. 私钥只在当前应用运行期间使用。
2. 保存配置时不会把私钥写入本地配置文件。
3. 下次打开应用需要重新导入私钥。

如果勾选：

1. 私钥会以明文保存到本地配置文件。
2. 保存前会弹出确认提示。
3. 只建议在受信任的个人电脑上使用。

本地配置文件路径：

```text
软件同级目录\config.json
```

例如：

```text
C:\Users\Administrator\Desktop\java-signature\config.json
```

### 6.8 保存配置

填写完成后，点击“保存配置”。

保存成功后，页面底部会显示配置文件保存路径。

## 7. 生成签名

### 7.1 进入签名页

点击顶部“生成签名”页签。

页面左侧用于输入请求 JSON，右侧用于选择配置、生成签名并查看结果。

### 7.2 选择商户配置

在“商户配置”下拉框中选择要使用的商户。

生成签名前，请确保该配置已经填写：

1. `businessId`
2. RSA 私钥
3. 基础 URL

### 7.3 输入请求 JSON

在左侧“请求 JSON”输入框中输入接口请求体，例如：

```json
{"orderNo":"TEST001","amount":100}
```

可以点击“校验 JSON”检查格式是否合法。

可以点击“格式化 JSON”整理格式，例如：

```json
{
  "orderNo" : "TEST001",
  "amount" : 100
}
```

注意：签名和实际发送请求时，JSON 文本必须保持一致。空格、换行、字段顺序变化，都可能导致签名不一致。

### 7.4 Timestamp

`Timestamp` 默认使用当前系统毫秒时间。

如果需要重新生成当前时间，点击：

```text
使用当前时间
```

服务端通常只接受 5 分钟内的时间戳。如果时间戳与当前时间相差超过 5 分钟，工具会显示风险提示。

### 7.5 签名模式

工具支持两种签名模式：

| 模式 | 说明 |
| --- | --- |
| 原文签名 | 默认模式，直接使用输入框里的 JSON 原文参与签名 |
| 格式化后签名 | 先将 JSON 格式化，再使用格式化后的文本参与签名 |

推荐使用“原文签名”。

原因是接口真实发送的请求体通常就是某一段具体 JSON 文本。签名时使用的文本必须和实际发送的请求体完全一致。

### 7.6 生成签名

点击“生成签名”按钮。

成功后会生成：

1. MD5 值。
2. Signature-Data。
3. 请求 Header。
4. cURL 示例。

### 7.7 输出结果说明

#### MD5 值

工具会先对 JSON 文本计算 MD5，输出 32 位小写十六进制字符串。

示例：

```text
3fe8bf3dafdaf1534949f245dcb8e078
```

#### Signature-Data

工具使用 RSA 私钥和 `MD5withRSA` 对 MD5 字符串签名，再将结果 Base64 编码。

该值需要放入请求 Header：

```text
Signature-Data: ...
```

#### 请求 Header

工具会生成如下 Header：

```text
Signature-Type: RSA
Timestamp: 1716364800000
Signature-Data: Base64签名数据
businessId: 商户编号
```

可以点击“复制 Header”。

#### cURL 示例

工具会基于基础 URL 生成一个 cURL 示例：

```bash
curl -X POST 'https://api.example.com/your/api/path' \
  -H 'Content-Type: application/json' \
  -H 'Signature-Type: RSA' \
  -H 'Timestamp: 1716364800000' \
  -H 'Signature-Data: ...' \
  -H 'businessId: C11112033827767895863296' \
  --data-raw '{"orderNo":"TEST001","amount":100}'
```

其中 `/your/api/path` 是占位路径，需要替换为真实接口路径。

## 8. 本地验签

### 8.1 进入验签页

点击顶部“本地验签”页签。

本地验签用于确认：

1. 请求 JSON 是否与签名匹配。
2. 公钥是否与私钥匹配。
3. Signature-Data 是否完整有效。

### 8.2 选择商户配置

选择商户配置后，工具会自动带入该配置中的 RSA 公钥。

如果没有配置公钥，也可以手动粘贴。

### 8.3 输入验签数据

需要填写：

1. RSA 公钥。
2. 请求 JSON。
3. Signature-Data。

请求 JSON 必须和生成签名时使用的 JSON 完全一致。

### 8.4 验签模式

验签模式与签名模式一致：

| 模式 | 说明 |
| --- | --- |
| 原文验签 | 使用输入框原文参与验签 |
| 格式化后验签 | 先格式化 JSON，再参与验签 |

如果签名时使用“原文签名”，验签时也应使用“原文验签”。

### 8.5 开始验签

点击“开始验签”。

可能结果：

#### 验签通过

说明：

1. JSON 文本正确。
2. Signature-Data 正确。
3. 公钥与私钥匹配。

#### 验签不通过

常见原因：

1. JSON 与签名时的原文不一致。
2. JSON 被格式化后再验签，导致空格或换行发生变化。
3. 字段顺序变了。
4. 使用了错误的公钥。
5. Signature-Data 复制不完整。
6. 签名算法或 MD5 计算口径与服务端不一致。

## 9. 签名规则说明

当前工具实现的签名规则如下：

```text
签名文本 = 请求 JSON 文本
MD5值 = MD5(签名文本 UTF-8 字节)
Signature-Data = Base64(RSA签名(MD5值字符串, MD5withRSA))
```

详细步骤：

1. 用户输入请求 JSON。
2. 工具校验 JSON 是否合法。
3. 工具对 JSON 文本计算 MD5。
4. 工具使用 RSA 私钥对 MD5 字符串签名。
5. 工具将签名结果做 Base64 编码。
6. 工具输出 Header。

当前 MD5 输出为：

```text
32 位小写十六进制字符串
```

当前 RSA 签名算法为：

```text
MD5withRSA
```

## 10. RSA 密钥生成

### 10.1 前置要求

需要安装 Git Bash 或 OpenSSL。

检查 OpenSSL 是否可用：

```bash
openssl version
```

### 10.2 生成 RSA 私钥

生成 2048 位 RSA 私钥：

```bash
openssl genrsa -out rsa_private_key.pem 2048
```

生成后会得到：

```text
rsa_private_key.pem
```

### 10.3 根据私钥生成公钥

方式一：

```bash
openssl rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem
```

方式二：

```bash
openssl rsa -in rsa_private_key.pem -pubout -out rsa_public_key_2048.pub
```

### 10.4 私钥转换为 PKCS8 格式

Java 读取私钥时需要 PKCS8 格式。

执行：

```bash
openssl pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt > rsa_private_key_pkcs8.pem
```

生成后，在工具中导入：

```text
rsa_private_key_pkcs8.pem
```

不要直接导入第一步生成的 `rsa_private_key.pem`，否则可能提示私钥无法被 Java 识别。

### 10.5 公钥处理

接口文档中要求公钥删除头尾：

```text
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
```

只保留中间 Base64 内容。

本工具为了方便使用，会自动忽略 PEM 头尾，所以粘贴完整公钥或只粘贴 Base64 内容都可以。

## 11. 常见问题

### 11.1 启动时报 PowerShell 脚本权限错误

请使用以下命令启动：

```powershell
powershell -ExecutionPolicy Bypass -File .\run.ps1
```

### 11.2 启动很慢

首次启动会自动下载 Maven 和项目依赖，可能需要等待一段时间。

下载完成后，后续启动会快很多。

### 11.3 私钥检查失败

常见原因：

1. 私钥不是 PKCS8 格式。
2. 私钥复制不完整。
3. 私钥文件不是 RSA 私钥。
4. 误导入了公钥文件。

解决方式：

```bash
openssl pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt > rsa_private_key_pkcs8.pem
```

然后重新导入 `rsa_private_key_pkcs8.pem`。

### 11.4 公钥检查失败

常见原因：

1. 公钥复制不完整。
2. 文件不是 X509 格式 RSA 公钥。
3. 文件内容混入了无关字符。

建议重新生成公钥：

```bash
openssl rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem
```

### 11.5 验签失败但看起来参数一样

请重点检查：

1. JSON 空格是否一致。
2. JSON 换行是否一致。
3. 字段顺序是否一致。
4. 签名时是否使用“格式化后签名”。
5. 验签时是否使用了同样的模式。
6. Signature-Data 是否复制完整。
7. 公钥和私钥是否是一对。

### 11.6 服务端提示 Timestamp 超时

点击“使用当前时间”，重新生成签名。

注意：Timestamp 是毫秒，不是秒。

正确示例：

```text
1716364800000
```

错误示例：

```text
1716364800
```

### 11.7 Header 已生成但接口仍验签失败

排查顺序：

1. 确认服务端使用的签名规则是否也是 `MD5withRSA`。
2. 确认服务端是否对 MD5 字符串签名，而不是直接对 JSON 原文签名。
3. 确认 MD5 是否为 32 位小写十六进制。
4. 确认请求实际发送的 Body 与工具签名文本完全一致。
5. 确认 `businessId` 是否正确。
6. 确认时间戳是否在 5 分钟内。
7. 确认服务端保存的公钥与本地私钥匹配。

## 12. 安全注意事项

1. 私钥不要发送给他人。
2. 私钥不要提交到 Git 仓库。
3. 私钥不要放入接口请求、日志、截图或聊天记录。
4. 默认不建议勾选“保存私钥到本地配置文件”。
5. 如果必须保存私钥，请确认电脑环境可信。
6. 离职交接、电脑报废或共享电脑使用后，应删除本地配置文件。

本地配置文件位置：

```text
软件同级目录\config.json
```

## 13. 推荐使用流程

首次使用：

1. 使用 OpenSSL 生成 RSA 私钥和公钥。
2. 将私钥转换为 PKCS8 格式。
3. 打开工具。
4. 进入“商户配置”。
5. 填写 `businessId`、基础 URL。
6. 导入 PKCS8 私钥。
7. 导入公钥。
8. 点击“检查私钥”和“检查公钥”。
9. 保存配置。

每次联调：

1. 进入“生成签名”。
2. 选择商户配置。
3. 输入请求 JSON。
4. 点击“使用当前时间”。
5. 点击“生成签名”。
6. 复制 Header。
7. 将 Header 和请求 Body 放入接口调试工具中发送。

排查签名问题：

1. 进入“本地验签”。
2. 粘贴请求 JSON。
3. 粘贴 Signature-Data。
4. 使用同一商户公钥。
5. 点击“开始验签”。
6. 如果本地验签失败，优先检查 JSON 原文、公钥和签名值。
7. 如果本地验签通过但服务端失败，优先检查服务端公钥、实际请求 Body 和签名规则口径。

## 14. 当前版本限制

当前版本是 MVP，实现了签名接入的核心能力，但暂未实现：

1. 内置 HTTP 请求发送。
2. 回调签名校验。
3. 私钥加密存储。
4. 多签名算法切换。

后续可以继续扩展为完整接口调试工具。