中国 帮助

包安全与签名

这一页解决什么问题 应用包(zip)的两个部分都是完全可信代码:backend/.jar 是任意 Java 代码,跑在宿主 JVM 里; frontend/ 是跑在宿主同源上下文里的 JS,能拿用户的 token 调任何接口。 所以"能

包安全与签名
封面

> 本文整理自平台文档 docs/wujies/5.x/platform/package/security.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-de294274e0ec-cover.svg)

这一页解决什么问题

应用包(zip)的两个部分都是完全可信代码:backend/*.jar 是任意 Java 代码,跑在宿主 JVM 里; frontend/ 是跑在宿主同源上下文**里的 JS,能拿用户的 token 调任何接口。 所以"能不能装"这件事要由平台回答三个问题,这一页就是这三个问题的答案:

问题管这件事的机制落点
包内允许出现哪些文件?产物白名单PackageSecurityInspector.checkArtifacts
这个包是不是我签发的、上传之后有没有被改过?分离式签名(包根 signature.txt)PackageDigest + PackageSignerMain
检查到什么程度、什么时候拒?三档模式 off / warn / enforceapp-market.security.mode

前两个机制都在共用内核 wujies-platform/wujies-modules/wujies-market-core/src/main/java/cn/wujies/appmarket/security/, 中心上架服务与各平台部署跑的是同一份字节码;本页每条断言都指向那里的类或各应用仓库自带的 package.ps1(wujies-<code>-plugin/package.ps1)—— 看完可以直接去核对。

什么时候必须读:改 app-market/security/** 或打包器的签名流程;要切 app-market.security.mode; 排查"上传 / 部署被安全检查拒绝";要给历史未签名版本补签名。

为什么必须有签名

部分它能干什么
后端 jar跑在宿主 JVM 里 —— 能读数据库、读配置、发任何网络请求
前端 JS跑在宿主同源上下文 —— 能拿用户 token 调任何接口

所以"装一个来路不明的应用"和"让陌生人在你服务器上执行代码"是同一件事。

静态扫描(关键字黑名单、危险 API 检测)挡不住有意作恶的包,只能提高门槛。 签名是唯一真防线:它不判断代码好坏,只回答「这个包是不是我签发的、有没有被改过」。 答不上来的包就不装。这段推导写在 PackageSecurityInspector 的类注释里。

产物白名单管的是另一件事

白名单挡不住恶意代码,但能挡掉「往前端目录塞个 .jsp 让 Web 容器执行」这类结构性问题 —— 因为前端目录就是宿主的静态资源目录,同源。

规则由 PackageSecurityInspector 的两个常量与 checkArtifacts 决定(ALLOWED_TOP_LEVEL / HOME_LEVEL_FILES / FORBIDDEN_FRONTEND_EXT):

位置规则
包根只允许 app.json、signature.txt 与包内路由清单 route-index.json(HOME_LEVEL_FILES),其它文件一律报「包根出现不允许的文件」
顶层目录只允许 backend/、frontend/、migrations/ 三个
backend/只允许 .jar;且清单 assets.backend 声明了哪个 jar 时,目录下的其它 jar 会被报成「清单未声明的产物」
migrations/只允许 .sql
frontend/必须命中配置的白名单扩展名,且再减一层硬禁止

frontend/ 下无论如何都拒绝的扩展名(写进配置也改不掉):

.jsp .jspx .jspf .php .phtml .war .jar .class
.exe .dll .so .dylib .sh .bat .cmd .ps1 .vbs
.properties .xml .yml .yaml .sql

允许的扩展名由 app-market.security.allowed-frontend-extensions 配置,默认值(注解与 application.yml 里是同一串):

.js,.mjs,.cjs,.css,.json,.svg,.png,.jpg,.jpeg,.gif,.webp,.ico,.bmp,
.woff,.woff2,.ttf,.otf,.eot,.map,.txt,.html,.wasm

MAX_REPORTED = 6:问题多于 6 条时报告只保留前 6 条,避免把任务日志刷满(checkArtifacts 末尾)。 包内有重名条目时直接计为问题并跳过白名单检查(zipReadable = false)—— 解包时后者覆盖前者, 而签名只算得出一份。

分离式签名(signature.txt)

签名是分离式的:包根一个 signature.txt,覆盖除它自己以外的全部文件 —— app.json、backend/*.jar、frontend/**、migrations/*.sql(会真实执行的 SQL)、route-index.json 都在内。

JSON 的键序在不同语言 / 库之间不保证一致。把签名放进被签名的 JSON 里,就得先做一套"规范化 JSON", 跨语言极易出错;独立文件完全没有这个问题。这段理由写在 PackageDigest.SIGNATURE_FILE 的注释上。

### 被签名的数据怎么算出来

对包内每个文件(排除 signature.txt 自己),按路径字符串升序依次拼:

<相对路径>\n<内容 SHA-256 十六进制小写>\n

拼出来的整段 UTF-8 字节就是要签名的数据,算法是 SHA256withRSA(PackageKeys.ALGORITHM)。 两条要点(PackageDigest 类注释):

所以「按目录签名」与「按 zip 签名」算出来是同一份数据,这也是打包脚本能先给暂存目录签名、 再打 zip 的原因。

  • 路径参与签名 —— 否则把 A 文件改名成 B 就能逃过校验;
  • 只签名内容、不签名 zip 元数据(时间戳、压缩级别、外部属性)—— 否则重新打一次包签名就废了。

归一化细则(PackageDigest.normalize / canonicalText):

项规则
排序实现里自己 TreeMap 排序,不依赖调用方传进来的是有序 Map
路径分隔符条目名里的 \ 一律先换成 /(Windows 的 Compress-Archive 会写反斜杠)
跳过不参与的条目signature.txt、目录项、__MACOSX/ 下的、绝对路径或含 : 的、含 .. 段的、空名
内容摘要该文件原始字节的 SHA-256,十六进制小写
单条目上限256MB(MAX_ENTRY_BYTES,与解包侧 AppPackageDeployService 一致)
重名条目直接拒绝:应用包内存在重名条目: <name>

### signature.txt 长什么样

PackageSignerMain.sign 写出的就是下面四行(后两行是注释):

app-market-signature/1
SHA256withRSA
<base64 签名>
# 覆盖文件数: <N>
# 内容摘要: <规范化文本的 SHA-256 十六进制小写>

解析侧(PackageSecurityInspector.parseSignatureFile)跳过空行与 # 开头的行; 遇到 app-market-signature/ 前缀的行必须是 app-market-signature/1,否则报「不支持的签名格式」; 第一个非注释行是算法,必须恰好是 SHA256withRSA,否则报「不支持的签名算法」; 第二个非注释行是 base64 签名,解不出来报「签名内容不是合法的 base64」。 后两行只在"手里只有一个签名文件"时用来核对覆盖范围。

签名文件里没有 keyId:服务端只有一把 public-key,所以"换钥"天然是全局作废旧包的操作。

### 四个类与「纯 JDK」这条硬约束

类职责纯 JDK?
PackageDigest规范化(签名与校验共用这一份)是
PackageSignerMain离线命令行 keygen / sign / verify是
PackageKeys密钥解析(签名侧与校验侧共用)是
PackageSecurityInspector白名单 + 验签 + 模式判定(inspectOrThrow 在 enforce 下抛异常)否 —— 带 ServiceException 与 Spring @Value

签名工具是用 `-cp wujies-modules/wu

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-de294274e0ec-guide.svg)

章节导览
THE END

喜欢就支持以下吧

评论区需要浏览器启用 JavaScript 才能加载。

回到内容