NSP-SM JWT Inspector 使用手册

本手册面向联调测试人员与后端/安全工程师，介绍如何通过 https://jwt-inspector.qxj.nsp.ac.cn/ 解析与验证 QXJ 体系签发的国密 JWT（NSP-SM Token），覆盖 Token 解析、SM2 外层验签、内层 HMAC 校验与常见问题排查。

快速开始

1. 打开 https://jwt-inspector.qxj.nsp.ac.cn/，等待顶栏显示 SM2 lib ready；
2. 粘贴完整的 JWT Token，点击 解析；
3. 填入服务器 SM2 公钥（hex，128 字符，不带 04 前缀）→ 验证外层签名；
4. 如需校验内层签名，再填入握手协商的 会话密钥 → 需使用debug版应用或通过后台Redis查询获得。

一、工具作用

QXJ 体系的 JWT 采用 SM2withSM3（国密非对称签名算法），jwt.io 等通用工具只能拆开看、无法验签。本工具是纯前端实现（SM2/SM3 能力经 CDN 加载 sm-crypto，Token 不会上传到任何服务器），完整复刻后端 BlacklistJWTAuthentication 的双重校验口径：

• 外层：SM3 摘要后 SM2 验签 —— 证明 Token 确为本系统签发、未被篡改；
• 内层：对 custom 载荷做 SM3-HMAC 校验 —— 证明会话密钥绑定关系成立。

二、界面布局

区域	说明
顶栏	工具名 + 加密库加载状态（Loading SM2 lib… → SM2 lib ready）
Encoded JWT	Token 粘贴区，附 解析 / 清空 按钮
SM2 Public Key	服务器公钥输入框（hex 128 字符，不带 04 前缀）
Session Key	会话密钥输入框（hex，用于内层 HMAC 校验，可选）
状态条	三枚徽章：外层签名 / exp 有效期 / 内层 HMAC，附 Copy Token
三栏展示	Header（红点）/ Payload（紫点）/ Signature（蓝点）解码结果

三、使用步骤

1. 粘贴 Token

• 将完整 Token（三段 base64url，以 . 分隔）粘贴到 Encoded JWT 输入框，点击 解析；
• 也支持 URL 参数直达：https://jwt-inspector.qxj.nsp.ac.cn/?token=xxx，打开即自动填充，便于在 bug 单里分享链接；
• 即使不填任何密钥，解析 也会完成三段拆分与 Payload 解码（先看结构，再验签）。

2. 填入 SM2 公钥（外层验签）

• 输入 128 字符 hex 公钥（不带 04 前缀，工具会自动补 04 前缀参与运算）；
• 公钥来源（管理员）：
  • 后端执行 python -m tools.setup qrcode；
• 公钥或会话密钥每次修改都会立即重新验签，无需再点解析。

3. 填入会话密钥（内层 HMAC 校验，可选）

• 输入 SM2 握手协商得到的会话密钥（hex），工具将校验 custom.hmac；
• 期望载荷 = device_id(UTF-8) || user_id(64 位大端) || exp_s(64 位大端) 的 SM3-HMAC；
• 工具同时检查 custom.exp_s 与外层 exp 是否一致，不一致直接判失败。

4. 读取验证结论（状态条徽章）

徽章	绿色 ✓	红色 ✗	灰色 —
签名	Signature Verified	Invalid Signature / Invalid format / 验签异常	无公钥，无法验签
有效期	显示剩余有效时间	显示已过期时长	无 exp 字段
HMAC	Inner HMAC Verified	Inner HMAC Mismatch / exp_s 与外层 exp 不一致	外层未通过，或未填会话密钥

排查顺序建议：签名 ✗ → 检查公钥是否为对应环境的服务器公钥；HMAC ✗ → 检查会话密钥是否为本次握手协商值（换服务器/重连后旧密钥会失效）；有效期 ✗ → Token 已过期，重新登录获取。

5. 查看三栏详情

• Header：算法（alg）与令牌类型（typ），附 Copy 按钮；
• Payload：逐字段中文说明 + 原始 JSON（点 ▾ Raw JSON 折叠/展开），字段含义见下表；
• Signature：签名 hex 及拆解出的 r、s 两个分量。

Payload 字段	含义
exp	过期时间（Unix timestamp）
iat	签发时间（Unix timestamp）
jti	Token ID
user_id	用户 ID
token_type	令牌类型（access / refresh）
custom	内层签名载荷（device_id / user_id / exp_s / hmac）

四、常见问题

Q：顶栏一直显示 Loading / lib load failed？ SM2/SM3 库从 cdn.jsdelivr.net 动态加载，网络不通会加载失败。检查网络或代理后刷新页面重试。

Q：外层验签通过，内层 HMAC 不通过？ 会话密钥不对。内层 HMAC 用的是本次握手协商的会话密钥，不是任何长期密钥；切换服务器或重新登录后需更新。

Q：公钥填了却提示验签异常？ 确认复制完整（128 位 hex、无空格换行），且不带 04 前缀——工具会自动处理前缀，重复添加会导致坐标越界异常。

Q：Token 里有敏感信息吗？ JWT 只是 base64 编码并非加密，Payload 任何拿到 Token 的人都能读。本工具纯本地解析，Token 不出浏览器，但分享 ?token= 链接时请注意对象与时效。

五、关联文档

• SM2 密钥协商与握手流程：国密算法与密钥协商
• 加密体系总览：加密方案
• 双重校验的服务端实现：qxj-backend-admin/apps/auth/sm2_jwt.py