jose 通用 JWS 签名构建器 Signature 接口深度解析:General JSON Serialization 多签名实战指南

发布时间:2026/11/19 8:11:08

jose 通用 JWS 签名构建器 Signature 接口深度解析:General JSON Serialization 多签名实战指南 网络安全认证鉴权后端【免费下载链接】joseJWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes项目地址https://gitcode.com/gh_mirrors/jo/jose点击查看免费下载导读本文围绕 jose 库中 Signature 接口src/jws/general/sign.ts展开它是在 General JSON Serialization 序列化下构建一个 JWS 携带多条独立签名的核心 API。读完本文你将掌握 Signature 接口全部五个方法setProtectedHeader、setUnprotectedHeader、addSignature、sign、done的签名与语义、它与父级 GeneralSign 的委托关系、底层校验逻辑头部互斥、crit/b64一致性并能直接写出可运行的多签名 JWS 生产代码。一、背景为什么需要 Signature 接口JWSJSON Web Signature除了常见的 Compact Serialization三段式紧凑字符串之外还定义了General JSON Serialization整个 JWS 是一个 JSON 对象其signatures数组成员各自携带独立的签名与头部。这种形态特别适合多方联合背书同一份 payload 需要 EC 密钥与 RSA 密钥或不同算法分别签名供不同类型的验签方校验兼容不同消费方签发方无法预知接收方支持哪种算法便一次性提供多种算法签名受保护与不受保护头部并存部分头部如kid只需完整性保护即可部分头部可放在未受保护的header成员中。jose 用 GeneralSign 类来构建这种多签名对象而Signature 接口正是 GeneralSign 为每一条待添加的签名返回的构建器句柄——每条签名都有自己独立的头部与密钥状态最后统一由sign()落盘。官方文档对它的定位是Used to build General JWS objects individual signatures用于构建 General JWS 对象的单条签名对应源码中的注释与实现src/jws/general/sign.ts。二、Signature 接口方法全景依据 Signature.md该接口共声明五个方法全部支持链式调用。逐一说明1.setProtectedHeader(protectedHeader): Signature参数protectedHeader类型为 JWSHeaderParameters即 JWS 受保护头部。语义为当前这条Signature 设置受保护头部。受保护头部的全部成员会参与签名输入的计算被 BASE64URL 编码后拼入protected成员因此受到完整性保护。返回值Signature便于继续链式调用。从源码可见该方法内部通过assertNotSet保证每个签名只能设置一次重复调用会抛出TypeError: setProtectedHeader can only be called oncesrc/jws/general/sign.ts测试见 test/jws/general.test.ts。2.setUnprotectedHeader(unprotectedHeader): Signature参数unprotectedHeader同为 JWSHeaderParameters。语义为当前这条 Signature 设置不受保护的头部。该头部作为未编码的 JSON 对象写入最终 JWS 的header成员不参与签名输入计算因此不具完整性保护详见 FlattenedJWSInput.md 对header成员的说明。.addSignature(secret) .setProtectedHeader({ bar: baz }) // 完整性保护 .setUnprotectedHeader({ alg: HS256 }) // 仅展示不参与签名输入同样只允许调用一次src/jws/general/sign.ts。关键约束源码级createSignature在 src/lib/jws_sign.ts 中强制两条规则——setProtectedHeader与setUnprotectedHeader至少调用一个否则抛JWSInvalideither setProtectedHeader or setUnprotectedHeader must be called before #sign()受保护与不受保护头部的成员名必须互斥disjoint否则抛JWSInvalidJWS Protected and JWS Unprotected Header Parameter names must be disjoint。3.addSignature(key, options?): Signature参数key为 KeyInput即CryptoKey | KeyObject | JWK | Uint8Array之一私钥或对称密钥/口令options?为可选的 SignOptions。语义它是在父级 GeneralSign 上再添加一条新签名的便捷转发方法shorthand。调用它会命中父实例的addSignature()并返回新签名对应的 Signature 构建器。源码实现一目了然src/jws/general/sign.tsaddSignature(...args: ParametersGeneralSign[addSignature]) { return this.#parent.addSignature(...args) }这意味着你可以在任一条签名构建的过程中岔开去追加新的签名链式写法非常自由见下文完整示例。4.sign(): PromiseGeneralJWS语义同样是转发方法调用父级 GeneralSign.sign()对已收集的所有签名统一执行签名计算返回Promise[GeneralJWS](https://link.gitcode.com/i/d198364201864eddad43317d248077a9)。它不接收任何参数——每条签名各自的密钥已在各自的addSignature中提供。sign(...args: ParametersGeneralSign[sign]) { return this.#parent.sign(...args) }5.done(): GeneralSign语义返回包裹当前签名的父级 GeneralSign 实例用于在链式调用的中途需要跳出回父级继续操作例如追加新签名后再回到原构建器的场景。done() { return this.#parent }三、完整实战示例EC 与 RSA 双签名官方文档给出的典型示例GeneralSign.md直观展示了上述方法的组合const jws await new jose.GeneralSign( new TextEncoder().encode(It’s a dangerous business, Frodo, going out your door.), ) .addSignature(ecPrivateKey) .setProtectedHeader({ alg: ES256 }) .addSignature(rsaPrivateKey) .setProtectedHeader({ alg: PS256 }) .sign() console.log(jws)先new jose.GeneralSign(payload)payload 必须是Uint8Array构造器签名GeneralSign.md第一条签名用 EC 私钥alg: ES256第二条用 RSA 私钥alg: PS256注意第二条addSignature是在第一条签名返回的 Signature 构建器上调用的——这正是addSignature转发语义的威力所在。输出形如{ payload: SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IHlvdXIgZG9vci4, signatures: [ { protected: eyJhbGciOiJFUzI1NiJ9, signature: ... }, { protected: eyJhbGciOiJQUzI1NiJ9, signature: ... } ] }依据 GeneralJWS.md顶层对象由payload字符串与signatures若干去掉payload成员的 FlattenedJWS 输入组成。算法与密钥对应关系alg必须与密钥类型/长度匹配例如ES256需要 P-256 曲线 EC 私钥、PS256需要 RSA 私钥。jose 官方以 Algorithm Key Requirements 形式维护了各算法的密钥要求清单JWSHeaderParameters.md 中alg字段的说明。若密钥与算法不匹配sign()会在密钥准备阶段抛错对应 src/lib/jws_sign.ts 中prepareKey(entry, key, sign)的校验。四、底层实现IndividualSignature 与状态元组从源码结构看Signature接口的默认实现是IndividualSignature类src/jws/general/sign.ts可以推断其设计要点状态集中管理每条签名的状态被放进一个四元组SignatureState [protectedHeader, unprotectedHeader, key, crit]构造时初始化为[undefined, undefined, key, options?.crit]父引用私有字段#parent: GeneralSign保存父实例四个转发/返回方法addSignature、sign、done均围绕它实现一次性设置setProtectedHeader/setUnprotectedHeader都通过assertNotSet拒绝重复调用保护状态不被覆盖。父级GeneralSign维护#signatures: IndividualSignature[]数组sign()逐条调用createSignaturesrc/lib/jws_sign.ts核心流程为serializeProtectedHeader → 校验 protected/unprotected 至少一个且互斥 → 合并 joseHeader → validateSignatureHeadercrit/b64 校验 → signatureAlgorithm(alg) 解析算法 → signSignature 拼接签名输入并计算 → 组装 FlattenedJWSsignature / payload / protected / header五、签名级校验与多签名一致性约束GeneralSign.sign()src/jws/general/sign.ts在生成阶段还施加三条重要约束测试用例覆盖如下约束触发条件异常至少一条签名未调用addSignature直接sign()JWSInvalid: at least one signature must be addedpayload 类型payload 非Uint8ArrayTypeError: payload must be an instance of Uint8Arrayb64 模式一致不同签名对b64RFC 7797 非编码载荷的使用不一致JWSInvalid: inconsistent use of JWS Unencoded Payload (RFC7797)最后一条尤其关键同一个 General JWS 的所有签名必须统一使用或统一不使用b64: false因为多条签名共享同一个payload成员。测试 test/jws/general.test.ts 专门验证了混合 b64 模式会被拒绝而 test/jws/general.test.ts 验证了全部使用b64: false时payload返回空字符串原始载荷需要接收方另行提供。其余校验还包括JOSE 头部值必须是普通对象null、数组、Date、数字、布尔值等均被拒绝见 test/jws/general.test.ts、crit数组去重validateCritDuplicates、alg缺失或非法时报JWSInvalid: JWS alg (Algorithm) Header Parameter missing or invalidsrc/lib/jws_sign.ts。六、头部参数与 SignOptions 实战速查JWSHeaderParameters 常用成员受保护/不受保护头部都接受 JWSHeaderParameters除alg外的常用成员包括成员类型说明algstring签名算法必填kidstringKey ID便于验签方在 JWKS 中选钥critstring[]关键头部扩展名列表标记必须被理解并处理的头部b64booleanRFC 7797 扩展头部控制 payload 是否做 BASE64URL 编码typstring类型声明通常用于声明JWT等媒体类型ctystring内容类型jkustringJWK Set URL指向可公开获取的密钥集jwkobject内联公钥不允许携带私钥/对称密钥参数x5u/x5c/x5tstring/string[]/stringX.509 URL、证书链、SHA-1 指纹此外该接口允许任意自定义成员索引签名[propName: string]: unknown例如测试中使用的bar: baz。SignOptions.crit 详解SignOptions.md 中crit是唯一选项一个{ [name: string]: boolean }映射值为true表示该扩展头部必须被完整性保护即必须出现在受保护头部中false表示无关紧要。内置处理的是b64扩展头部其余注册头部并不享受内置特殊处理。文档同时给出重要警告该选项只做语法与完整性保护层面的检查不会替你处理该头部的业务语义——签名成功后调用方仍必须按协议 profile 自行校验其存在性并完成相应处理。七、常见陷阱与建议忘记设置头部setProtectedHeader与setUnprotectedHeader至少调用一个否则sign()直接抛JWSInvalid头部名冲突同一签名内受保护与不受保护头部不允许出现同名成员b64 模式必须全局一致多条签名要么全部b64: true默认要么全部b64: false配合crit: [b64]混用即报错重复设置同一头部同一条签名上setProtectedHeader/setUnprotectedHeader只能各调用一次payload 必须是Uint8Array字符串等类型会在sign()时被拒绝文本记得先用TextEncoder().encode()转换。结语Signature 接口是 jose 通用 JWS 签名能力的每签名构建器配合 GeneralSign 使用即可轻松产出多算法、多方背书的 General JSON Serialization JWS。建议进一步阅读src/jws/general/sign.ts接口与实现、src/lib/jws_sign.ts签名输入与头部校验、test/jws/general.test.ts边界与一致性测试以及配套的 JWSHeaderParameters、SignOptions 与 GeneralJWS 类型文档。赞分享网络安全认证鉴权后端【免费下载链接】joseJWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes项目地址https://gitcode.com/gh_mirrors/jo/jose点击查看免费下载相关推荐KubeSphere 中的 Go JOSEgo-jose v2JWE / JWS / JWT 加密签名库深度解析KubeSphere 中的 Go JOSEgo jose v2JWE / JWS / JWT 加密签名库深度解析 本文以 KubeSphere 仓库中 v后端云原生容器编排微服务windows-services用 Rust 实现 Windows 服务的完整实战指南windows services用 Rust 实现 Windows 服务的完整实战指南 导读 windows services 是 windows rsRu网络安全认证鉴权后端Quartz 插件系统完全指南插件类型、内置插件清单与配置管理Quartz 插件系统完全指南插件类型、内置插件清单与配置管理 本文以 Quartzv5插件系统的官方索引文档为核心系统梳理插件生态的组成方式从内部插网络安全认证鉴权后端上一篇UE5-MCP如何用AI在3天内完成虚幻引擎5游戏开发工作下一篇零代码RPA自动化工具taskt3天掌握办公自动化的完整指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/19 8:41:23

QQ 飞车 Agentic 研发转型过程中的 Loop Engineering

👋 Hi,带娃的我热爱 AI 大模型应用落地、意识解码与 AI 开发工具链 。 💡 创业路上,用技术换时间,一起把 AI 变成生产力 🚀 >QQ 飞车 Agentic 研发转型过程中的 Loop Engineering 背景与痛点 当一个研发…

2026/11/19 12:33:44

潍坊电工证考什么内容考前押题帮你一次过

潍坊电工证考什么内容考前押题帮你一次过 你缺证就缺工作机会,缺机会就缺收入来源, 潍坊电工证考什么内容 ,你真的了解吗?别再被培训机构忽悠了, 考前押题…

2026/11/19 12:33:44

电工证互通怎么操作保姆级教程:工地太忙根本没时间复习考试

电工证互通怎么操作保姆级教程:工地太忙根本没时间复习考试 工地太忙根本没时间复习考试,你是过来人,知道现在施工队的节奏有多快。项目赶工期、人手紧张、天天加班,哪还有空去翻那些考试资料?特别是像你这样刚毕业的南阳卧龙区工程类学生,手里一堆证还…

2026/11/19 12:33:44

新乡水利工程从业者怎么报名加拿大电工证有几种

新乡水利工程从业者怎么报名加拿大电工证有几种 工地太忙根本没时间复习考试,这是很多一线施工人员的真实写照。特别是像新乡这样的水利工程重镇,项目节奏快、任务重,很多人一边扛着活,一边还得抽时间备考。而加拿大电工证有几种,这个话题背后,其实关系…

2026/11/19 12:33:44

长宁电工证在哪里办 2026河南最新政策你必须知道

长宁电工证在哪里办 2026河南最新政策你必须知道 现在找工作, 急需特种作业证才能上岗 ,尤其是电工证,几乎是进入建筑、电力、制造业等行业的“通行证”。如果你在河南长宁地区,正为 长宁电工证在哪里办…

2026/11/19 12:33:44

电工证别乱考!高级电工证抵扣个税千万别踩坑

电工证别乱考!高级电工证抵扣个税千万别踩坑 找电工工作前必须有证,这事儿不夸张。你要是没证,连面试资格都没有,更别说谈工资了。现在不少电工朋友想走个捷径,把高级电工证和个税抵扣联系起来,以为能省不少钱,结果一查政策,发现根本不是那么回事。…

2026/11/19 12:28:43

宁波电工证如何考取多少钱 你在外省的证还能用吗

宁波电工证如何考取多少钱 你在外省的证还能用吗 之前考的证在外省能不能转过来?这几乎是每个准备考电工证的朋友最先问的问题。尤其现在很多人在外地工作,手里拿着的证可能是在别的省考的,想在宁波用,但不知道能不能直接用,或者怎么转。其实,…

2026/11/18 21:12:58

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/18 21:55:23

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/19 0:04:42

深圳电工证培训考场模拟考试题库:郑州报考避坑指南

深圳电工证培训考场模拟考试题库:郑州报考避坑指南 证书过期了不知道怎么复审延期,很多人在遇到这个问题的时候才意识到特种作业证的重要性。其实,不管是电工证、焊工证还是高处作业证,这些证书不仅是上岗的“通行证”,更是法律对安全操作的硬性要求。尤…

2026/11/19 0:04:42

天津电工证查询入口多少钱能报上名

天津电工证查询入口多少钱能报上名 学历不高怕报不上名?别急,天津电工证查询入口其实没你想的那么难。今天咱们就来聊聊,怎么用最低的门槛、最少的钱,把电工证拿下来,还能查得到、用得上。 电工证到底值不值?先搞清楚它的作用…

2026/11/18 12:37:05

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/18 1:15:04

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑