Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: CI

on:
push:
branches: [main]
branches: [main, 'release/**']
pull_request:
schedule:
- cron: '0 2 * * 1' # 每周一 02:00 UTC 跑 mutation(低频收集 PIT 基线)
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ target/
dependency-reduced-pom.xml
.flattened-pom.xml

# 本地代码审查报告(不随仓库分发)
.zcode-review/

# python
__pycache__
.pytest_cache
Expand Down
23 changes: 17 additions & 6 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ wire byte formats.

- Protocol sources: [crypto-strategy-spec.md](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-strategy-spec.md) (v0.4-draft) + [wop-sdk-spec.md](https://github.com/wop-platform/wop-specs/blob/main/docs/specs/wop-sdk-spec.md) (v1.0-ratified)
- Vector source of truth: [crypto-vectors.json](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-vectors.json) (fetched at build time from the pinned commit SHA with sha256 verification; no copy kept in this repo)
- JDK 8+, Maven multi-module (`groupId: com.wanlianyida`, version 0.3.0; the unirest adapter requires Java 11+ at runtime — JDK 8 users should use the okhttp/jdkhttp adapters)
- Single runtime dependency: BouncyCastle (the only supported path for SM2/SM3/SM4)
- JDK 8+, Maven multi-module (`groupId: com.wanlianyida`, version 0.3.0-jdk15on.1; the unirest adapter requires Java 11+ at runtime — JDK 8 users should use the okhttp/jdkhttp adapters)
- Single runtime dependency: BouncyCastle (the only supported path for SM2/SM3/SM4); this release line uses `bcprov-jdk15on`

| Module | Description |
|--------|-------------|
Expand All @@ -23,6 +23,17 @@ wire byte formats.

Supported suites: `WOP-RSA2048-SHA256` / `WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`.

> **Release line selection (important)**: the SDK ships two BouncyCastle lines, and they **must not coexist on one classpath** (`jdk15on` and `jdk18on` are distinct artifacts sharing the same packages).
>
> | Release line | Coordinates | Intended for |
> |---|---|---|
> | `jdk15on` (this branch) | `0.3.0-jdk15on.1` | Projects already using `bcprov-jdk15on` (≥1.65); no exclusions needed |
> | `jdk18on` (main) | `0.3.0` | Projects without BC, or already on `bcprov-jdk18on` |
>
> Pick with `mvn dependency:tree -Dincludes=org.bouncycastle`: if you see `bcprov-jdk15on`, use this line; otherwise use `main`. The `jdk15on` branch is no longer security-maintained (1.70 is the final release); new projects should prefer the `jdk18on` line.
>
> Both release lines share one coordinate space: Maven orders an unrecognized qualifier after the release version (`0.3.0-jdk15on.1 > 0.3.0`), so **users on either line can be pulled across by update tools**. Pin an exact version and configure Renovate/Dependabot as described in [docs/release-lines.md](docs/release-lines.md); see [SECURITY.md](SECURITY.md) for the security boundary.

> **JDK adapter memory profile (`wop-sdk-jdkhttp`)**: request bodies are sent through `HttpURLConnection`'s default buffering mode — in streaming mode the JDK discards 401/407 challenge response bodies (`getErrorStream()` is always null), so buffering is the only correct option — meaning peak memory during a send is roughly 2x the request body size; response reading still streams under the 11MB cap. For very large request bodies prefer the okhttp/unirest adapters.

## Quick Start
Expand All @@ -31,26 +42,26 @@ Supported suites: `WOP-RSA2048-SHA256` / `WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-core</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>

<!-- Optional adapter (pick one): okhttp / unirest client dependencies are provided (bring your own; for unirest that is com.konghq:unirest-java-core) / jdkhttp has zero extra dependencies. The unirest adapter creates its own UnirestInstance by default — for long-running services, inject a shared instance via the constructor and close it on shutdown. Adapters register via META-INF/services and can be resolved through core's TransportFactory.discover() (ServiceLoader) — it requires exactly one adapter on the classpath; zero or multiple fail fast with a configuration error -->
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-okhttp</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>
<!-- or -->
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-jdkhttp</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>
<!-- or -->
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-unirest</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>
```

Expand Down
25 changes: 18 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ WOP 网关商户侧官方 Java 客户端:封装协议核心(签名 / 摘要

- 协议真源:[crypto-strategy-spec.md](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-strategy-spec.md)(v0.4-draft)+ [wop-sdk-spec.md](https://github.com/wop-platform/wop-specs/blob/main/docs/specs/wop-sdk-spec.md)(v1.0-ratified)
- 向量真源:[crypto-vectors.json](https://github.com/wop-platform/wop-specs/blob/main/crypto/crypto-vectors.json)(构建期按 commit SHA 钉版拉取 + sha256 校验,本仓不保留副本)
- JDK 8+,Maven 多模块(`groupId: com.wanlianyida`,版本 0.3.0;unirest 适配器运行时要求 Java 11+,JDK 8 用户请用 okhttp/jdkhttp 适配器)
- 运行时依赖仅 BouncyCastle(国密 SM2/SM3/SM4 唯一路径)
- JDK 8+,Maven 多模块(`groupId: com.wanlianyida`,版本 0.3.0-jdk15on.1;unirest 适配器运行时要求 Java 11+,JDK 8 用户请用 okhttp/jdkhttp 适配器)
- 运行时依赖仅 BouncyCastle(国密 SM2/SM3/SM4 唯一路径);本发行线使用 `bcprov-jdk15on`

| 模块 | 说明 |
|------|------|
Expand All @@ -23,6 +23,17 @@ WOP 网关商户侧官方 Java 客户端:封装协议核心(签名 / 摘要

支持套件:`WOP-RSA2048-SHA256` / `WOP-RSA3072-SHA256` / `WOP-RSA4096-SHA256` / `WOP-SM2-SM3`。

> **发行线选择(重要)**:SDK 提供两条 BouncyCastle 依赖线,二者**不可同时出现在同一 classpath**(`jdk15on` 与 `jdk18on` 是不同 artifact、同名包)。
>
> | 发行线 | 坐标版本 | 适用项目 |
> |---|---|---|
> | `jdk15on`(本分支) | `0.3.0-jdk15on.1` | 已有 `bcprov-jdk15on`(≥1.65)的老项目,无需排除任何依赖 |
> | `jdk18on`(main) | `0.3.0` | 无 BC 依赖、或已使用 `bcprov-jdk18on` 的项目 |
>
> 选择规则:运行 `mvn dependency:tree -Dincludes=org.bouncycastle`,看到 `bcprov-jdk15on` 就用本发行线,否则用 `main` 发行线。`jdk15on` 分支已停止安全维护(1.70 为最后一版),新项目优先选择 `jdk18on` 线。
>
> 两条发行线共用同一坐标空间:Maven 把未识别限定符排在发布版之后(`0.3.0-jdk15on.1 > 0.3.0`),**两条线的使用者都可能被更新工具诱导跨线**。请锁定精确版本并按 [docs/release-lines.md](docs/release-lines.md) 配置 Renovate/Dependabot;安全边界见 [SECURITY.md](SECURITY.md)。

> **JDK 适配器内存画像(`wop-sdk-jdkhttp`)**:请求体经 `HttpURLConnection` 默认缓冲模式发送——streaming 模式遇 401/407 挑战会丢弃错误响应体(`getErrorStream()` 恒 null),缓冲是唯一正确解——发送期间峰值内存约为请求体字节数的 2 倍;响应侧仍为 11MB 流式读取。超大请求体场景建议改用 okhttp/unirest 适配器。

## 配置层一站式接入(wop-sdk-config-spec)
Expand All @@ -34,7 +45,7 @@ WOP 网关商户侧官方 Java 客户端:封装协议核心(签名 / 摘要
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-jdkhttp</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>
```

Expand Down Expand Up @@ -94,26 +105,26 @@ trim;可打印 ASCII、无内部空白、≤128 字符,控制字符含 tab/
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-core</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>

<!-- 可选适配器(三选一):okhttp / unirest 的客户端依赖 scope=provided(商户自带版本,unirest 即 com.konghq:unirest-java-core) / jdkhttp 零额外依赖。unirest 适配器默认自建 UnirestInstance,长期运行建议经构造器注入复用单例并统一关闭。适配器经 META-INF/services 注册,可由 core 的 TransportFactory.discover()(ServiceLoader)解析——要求 classpath 恰一适配器,零/多均以配置错误 fail-fast -->
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-okhttp</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>
<!-- 或 -->
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-jdkhttp</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>
<!-- 或 -->
<dependency>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-sdk-unirest</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</dependency>
```

Expand Down
31 changes: 31 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# 安全策略

## 支持的版本

| 发行线 | 版本示例 | 状态 |
|---|---|---|
| jdk18on(`main`) | `0.3.x` | 正常维护,接收安全修复 |
| jdk15on(`release/jdk15on-*`) | `0.3.0-jdk15on.x` | 过渡发行线,尽力修复;底层 BC 已停止维护 |

15on 线使用 `bcprov-jdk15on` 1.70(该 artifact 的最后一版,2021-12)。此后
BouncyCastle 的安全修复只进入 `bcprov-jdk18on` 分支,1.70 不会获得回灌补丁。
两条线的差异与选择方法见 [docs/release-lines.md](docs/release-lines.md)。

## 上报漏洞

请**不要**通过公开 issue 披露未修复的安全问题。使用 GitHub 仓库的
**Security → Report a vulnerability** 私密上报,并尽量包含:

- 受影响版本与发行线(`mvn dependency:tree -Dincludes=org.bouncycastle` 输出);
- 最小复现步骤或 PoC(不要附带真实密钥、证书或生产数据);
- 影响评估(机密性 / 完整性 / 可用性)。

我们会在确认后同步修复计划;需要协调披露时,请在报告中说明期望的时间线。

## 不在范围内

- 消费者自行替换或排除 SDK 依赖后产生的组合问题;
- 消费者 classpath 上同时存在 `bcprov-jdk15on` 与 `bcprov-jdk18on` 的配置错误
(这属于依赖冲突,不是 SDK 漏洞);
- 已停止维护的 15on 线中、且仅存在于 EOL BouncyCastle 1.70 自身的问题——
此类问题应推动迁移到 18on 线。
123 changes: 123 additions & 0 deletions docs/release-lines.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
# 发行线(jdk15on / jdk18on)

本仓库对外提供两条 BouncyCastle 依赖线。两条线**代码同源、二进制行为一致**,唯一差异是
BC 的 Maven 坐标;它们**不能出现在同一个 classpath**(`bcprov-jdk15on` 与 `bcprov-jdk18on`
是不同 artifact,但包含同名 `org.bouncycastle.*` 包,同名类随机取胜)。

## 如何选择

```bash
mvn dependency:tree -Dincludes=org.bouncycastle
```

| 依赖树结果 | 选择 | 坐标示例 |
|---|---|---|
| 无 BouncyCastle | 18on 线(`main`) | `0.3.0` |
| `bcprov-jdk18on` | 18on 线(`main`) | `0.3.0` |
| `bcprov-jdk15on`(≥1.65) | 15on 线 | `0.3.0-jdk15on.1` |
| `bcprov-jdk15on`(<1.65) | 先升级 BC,再选 15on 线 | — |

15on 线由 `BouncyCastleVersionGuard` 在运行时校验版本,低于 1.65 会抛
`WopError`(`category=configuration`)并给出升级提示。

## 为什么不能"自动升级"

Maven 的 `ComparableVersion` 会把未识别限定符排在发布版本**之后**,因此:

```
0.3.0-jdk15on.1 > 0.3.0
```

这带来两个方向的跨线风险:

- **18on 使用者**(当前 `0.3.0`)会被 Renovate / Dependabot / `mvn versions:display-dependency-updates`
提示升级到 `0.3.0-jdk15on.1`——这会把项目迁到 15on 线,并在 classpath 上同时引入
`bcprov-jdk18on` 与 `bcprov-jdk15on`;
- **15on 使用者**(当前 `0.3.0-jdk15on.1`)暂时不会被拉回 `0.3.0`,但主干发布 `0.3.1+`
之后,同样会被提示跨线升级。

单一坐标空间无法靠版本排序隔离两条发行线。**结构性方案是给 15on 线使用独立
artifactId**(例如 `wop-sdk-core-jdk15on`);在完成该改造之前,两条线都必须锁定
精确版本并限制更新工具。

Renovate(15on 项目限制在本发行线):

```json
{
"packageRules": [
{
"matchPackageNames": [
"com.wanlianyida:wop-sdk-core",
"com.wanlianyida:wop-sdk-jdkhttp",
"com.wanlianyida:wop-sdk-okhttp",
"com.wanlianyida:wop-sdk-unirest"
],
"allowedVersions": "/^0\\.3\\.0-jdk15on\\.\\d+$/"
}
]
}
```

Renovate(18on 项目排除 15on 发行线):

```json
{
"packageRules": [
{
"matchPackageNames": [
"com.wanlianyida:wop-sdk-core",
"com.wanlianyida:wop-sdk-jdkhttp",
"com.wanlianyida:wop-sdk-okhttp",
"com.wanlianyida:wop-sdk-unirest"
],
"allowedVersions": "/^\\d+\\.\\d+\\.\\d+$/"
}
]
}
```

Dependabot 的 `ignore` 只能列举具体版本,必须覆盖**全部四个构件**;15on 项目需忽略
18on 线的版本,18on 项目需忽略 15on 线的版本,且两条线每次发版都要补充:

```yaml
version: 2
updates:
- package-ecosystem: "maven"
directory: "/"
schedule:
interval: "weekly"
ignore:
# 示例:15on 项目忽略 18on 线;反向场景把版本列表换成 15on 线
- dependency-name: "com.wanlianyida:wop-sdk-core"
Comment thread
sourcery-ai[bot] marked this conversation as resolved.
Resolved
versions: ["0.3.0"]
- dependency-name: "com.wanlianyida:wop-sdk-jdkhttp"
versions: ["0.3.0"]
- dependency-name: "com.wanlianyida:wop-sdk-okhttp"
versions: ["0.3.0"]
- dependency-name: "com.wanlianyida:wop-sdk-unirest"
versions: ["0.3.0"]
```

不论使用哪种工具,都必须在 pom 中写死精确版本(不要用范围),并在升级 PR 中检查
`dependency:tree` 是否仍只有一个 `bcprov-*`。

## 维护者约定

1. **版本格式**:`<基线版本>-jdk15on.<序号>`,序号从 1 递增;同一基线只发布一次,不可覆盖。
该方案是单坐标空间下的临时折中(排序无法隔离两条线);长期应改为独立 artifactId。
2. **发布**:`tag = v<完整版本>`,与根 pom 一致(`release.yml` 会校验);发布前跑
`mvn -B -ntp verify`,覆盖率与 japicmp 门禁必须全绿。
3. **BC 升级**:15on 分支已冻结在 1.70(最后一版)。若确需变更,必须同步更新
`BouncyCastleVersionGuard.MIN_VERSION`、CI 兼容矩阵与 README 的适用版本。
4. **不要合回 main**:15on 分支的 BC 坐标变更是发行线差异,不是可合并的功能提交。
5. **变更同步**:15on 线只接受安全修复与兼容性修复;功能开发仍以 `main` 为准,
需要时手工 cherry-pick 并单独发版。

## 安全边界

`bcprov-jdk15on` 的最后一个版本是 1.70(2021-12)。此后 BouncyCastle 只在
`bcprov-jdk18on` 分支修复安全问题,**1.70 不会获得回灌补丁**。

- 15on 线定位为存量项目的过渡发行线,不承诺长期安全维护;
- 新项目应使用 18on 线;
- 上报渠道与处理流程见仓库根目录 [SECURITY.md](../SECURITY.md)。
11 changes: 8 additions & 3 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@

<groupId>com.wanlianyida</groupId>
<artifactId>wop-java-sdk</artifactId>
<version>0.3.0</version>
<!-- 双发行线共用同一坐标空间:Maven 把未知限定符排在发布版之后,
0.3.0-jdk15on.1 > 0.3.0,两条线的使用者都可能被更新工具诱导跨线。
因此必须锁定精确版本;结构性隔离需改用独立 artifactId,见 docs/release-lines.md。 -->
<version>0.3.0-jdk15on.1</version>
Comment thread
zhouweiye marked this conversation as resolved.
Resolved
<packaging>pom</packaging>
<name>WOP Java SDK</name>
<description>WOP 商户侧官方 Java SDK:签名/摘要/L2 数字信封/验签解密协议核心 + HTTP 适配器</description>
Expand All @@ -24,7 +27,9 @@
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<maven.compiler.release>8</maven.compiler.release>
<bc.version>1.85</bc.version>
<!-- jdk15on 发行线:bcprov-jdk15on 最后一版为 1.70(之后仅维护 jdk18on)。
本分支面向已有 bcprov-jdk15on 的老项目,避免与 jdk18on 同名类冲突。 -->
<bc.version>1.70</bc.version>
<junit.version>5.12.2</junit.version>
<okhttp.version>4.12.0</okhttp.version>
<unirest.version>4.10.1</unirest.version>
Expand All @@ -42,7 +47,7 @@
</dependency>
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-jdk18on</artifactId>
<artifactId>bcprov-jdk15on</artifactId>
<version>${bc.version}</version>
</dependency>
<dependency>
Expand Down
6 changes: 3 additions & 3 deletions wop-sdk-core/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<parent>
<groupId>com.wanlianyida</groupId>
<artifactId>wop-java-sdk</artifactId>
<version>0.3.0</version>
<version>0.3.0-jdk15on.1</version>
</parent>

<artifactId>wop-sdk-core</artifactId>
Expand All @@ -28,7 +28,7 @@
<!-- 唯一运行时依赖:BouncyCastle(国密 SM2/SM3/SM4) -->
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-jdk18on</artifactId>
<artifactId>bcprov-jdk15on</artifactId>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
Expand Down Expand Up @@ -99,7 +99,7 @@
<oldClassPathDependencies>
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-jdk18on</artifactId>
<artifactId>bcprov-jdk15on</artifactId>
<version>${bc.version}</version>
</dependency>
</oldClassPathDependencies>
Expand Down
Loading
Loading