显示页面讨论过去修订反向链接回到顶部 本页面只读。您可以查看源文件,但不能更改它。如果您觉得这是系统错误,请联系管理员。 ====== 一文讲清楚:JWT 加密中的 FP ====== 先说结论:**JWT / JOSE 规范里并没有一个叫 ''fp'' 的标准字段。** 你在代码里看到的 ''fp'',几乎都是 **fingerprint(指纹)** 的缩写 —— 一串由公钥、证书或令牌内容算出来的**定长摘要**,作用是**标识与比对**,而不是保密。它在 JWT 体系里最典型的位置只有两处:**''kid'' 的取值**,以及 **DPoP 的 ''jkt''**。 ===== 1. FP 到底是什么 ===== FP = fingerprint,指纹。把一段数据喂给哈希函数(现在通用 SHA-256),得到一个固定长度的摘要: <code> 公钥 / 证书 / 令牌内容 --SHA-256--> 32 字节摘要 --base64url 或 hex--> 一串字符 </code> 它的特点,以及和「加密」的分界: * **单向**:从摘要回推不出原文;但原文相同,摘要必然相同 → 可以当「内容身份证」 * **定长**:输入多大都一样长,方便比较、存储、建索引 * **公开无妨**:指纹不是秘密,公钥指纹可以随便公开;它**不是密钥**,**也不能当密码用** * **不参与加解密运算**:指纹只负责「认出这把钥匙是谁」,真正做保密的是 RSA-OAEP、ECDH-ES、AES-GCM 这些算法 > 一句话:**加密算法负责保密,指纹负责认人。** 顺便提醒另一个同形缩写:''FP'' 在安全报表里还常表示 **False Positive(误报)**,与 FN(漏报)相对。如果是在 WAF、风控、告警口径里看到「FP 率高」,那和 JWT 加密无关。 ===== 2. 为什么 JWT 里需要指纹 ===== JWT 的签名与加密都依赖密钥(详见 [[jwt|JWT(JSON Web Token)]])。只要进入多密钥共存的状态,就立刻冒出一个问题:**验证方怎么知道该用哪一把密钥?** 密钥轮换的典型场景: * 发布了新的签名密钥,旧密钥还要继续验证存量令牌 → 至少两把公钥同时在用 * 多租户、多环境、多应用共用一个 JWKS 端点 * 加密(JWE)时,同一个服务持有多把解密钥 于是令牌头里需要一个**密钥标识符**。''kid'' 就是这个位置,而指纹天然是个好 ''kid'':**不用人工起名、不会重复、还能被独立算出来核对**。 ===== 3. 与指纹相关的标准字段 ===== 下面是规范里真实存在的名字,别和自造缩写混淆: ^ 字段 ^ 出现在哪 ^ 说明 ^ | ''kid'' | JWS / JWE 的 Header,以及 JWK | **密钥 ID,字符串**。规范不限定生成方式,实践中常直接放公钥指纹 | | ''x5t'' | Header / JWK | X.509 证书的 **SHA-1** 指纹(base64url)。历史遗留,新系统不要再生成 | | ''x5t#S256'' | Header / JWK | 同一张证书的 **SHA-256** 指纹,**新代码用这个** | | ''jwk'' | Header | 直接内嵌公钥;有指纹就能核对内嵌的公钥有没有被换掉 | | ''jku'' / ''x5u'' | Header | 公钥集 / 证书的下载地址,必须走白名单,不能当可信输入 | | ''x5c'' | Header / JWK | 证书链数组,可对其中证书现算指纹来比对 | | ''jkt'' | DPoP 的 JWT(RFC 9449) | **JWK 的 SHA-256 Thumbprint**,把令牌钉死在一把具体公钥上 | 补充一句:**JWE 加密**里用到的 ''alg''(如 ''RSA-OAEP''、''ECDH-ES'')与 ''enc''(如 ''A256GCM'')都是**算法标识**,不是指纹。指纹在这里只承担「选钥匙」的角色。 ===== 4. 主角:JWK Thumbprint(RFC 7638) ===== 如果只记一种指纹算法,就记它。**JWK Thumbprint = 对 JWK 的必需成员做规范化 JSON 后取 SHA-256,再 base64url 编码。** 步骤必须严格照做,错一步结果就对不上: - ① 按 ''kty'' 只取**必需成员**:EC 取 ''crv, kty, x, y'';RSA 取 ''e, kty, n'';oct 取 ''k, kty'' - ② 字段名按 **Unicode 码点字典序**排列 - ③ 拼成 **不含空格** 的 JSON 字符串(UTF-8 编码) - ④ 做 **SHA-256** - ⑤ **base64url 编码并去掉 ''='' 填充** —— 得到的字符串就是指纹 <code> // 规范化后的待哈希串(RSA 示例:字段顺序必须长这样) {"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"} </code> 实际项目里用 ''jose'' 一行就够: <code javascript> import { calculateJwkThumbprint } from "jose"; // 公钥 JWK(EC P-256 示例) const jwk = { kty: "EC", crv: "P-256", x: "...", y: "..." }; const kid = await calculateJwkThumbprint(jwk, "sha256"); // 默认也是 sha256 // => "cn-I_WNMClehiVp51i_0VpOENW1upEerA8sEam5hn-s" // 签发时放进 header,验证方据此挑密钥 const header = { alg: "ES256", kid }; </code> 手写一版(只为理解原理,生产环境请用库): <code javascript> import { createHash } from "node:crypto"; const REQUIRED = { // 数组本身已按字典序排好 EC: ["crv", "kty", "x", "y"], RSA: ["e", "kty", "n"], oct: ["k", "kty"], }; function jwkThumbprint(jwk) { const names = REQUIRED[jwk.kty]; if (!names || names.some((n) => jwk[n] === undefined)) { throw new Error("JWK 缺少必需成员"); } const canonical = JSON.stringify( Object.fromEntries(names.map((n) => [n, jwk[n]])), ); return createHash("sha256").update(canonical, "utf8").digest("base64url"); } </code> ===== 5. 指纹在 JWE(JWT 加密)流程里干什么 ===== JWE 的紧凑形式是五段: <code> header.encrypted_key.iv.ciphertext.tag </code> 换算流程: - ① 发送方决定用哪把公钥加密 → 把该公钥的 ''kid''(或其指纹)写进 header - ② 随机生成 CEK(内容加密密钥),用公钥加密 CEK,得到 ''encrypted_key'' - ③ 用 CEK 加密正文(如 AES-GCM),产出 ''iv''、''ciphertext''、''tag'' - ④ 接收方读 header 里的 ''kid'',在本地密钥表(或 JWKS)中**按指纹匹配**出对应私钥 - ⑤ 用私钥解出 CEK,再用 CEK 解密正文,并校验 ''alg''、''enc'' 是否在白名单内 要点: * **指纹只出现在第 ①、④ 步**,本质是「查找键」。加解密运算完全不依赖指纹 * ''kid'' 是**输入参数、不可信**:必须只在服务端白名单键表里查,绝不允许拿 ''kid'' 去拼文件路径、SQL 或 URL(这就是 kid 注入,[[jwt|JWT 页面]]里也提到过) * 指纹**不是令牌合法性的凭据**:公开公钥的指纹谁都能算。真正的信任来自验签、解密成功或 DPoP proof ===== 6. 项目里那个 ''fp'' 变量,可能是这几种 ===== ^ 代码里的写法 ^ 实际含义 ^ 用途 ^ | ''kid = fp(publicKey)'' | 公钥 / 证书指纹 | 生成密钥 ID,支撑轮换与匹配 | | ''fp = sha256(cert)'' | 证书指纹 | TLS、证书 pinning,防止中间人换证书 | | ''fingerprint(jwk)'' → ''jkt'' | JWK Thumbprint(RFC 7638) | DPoP、mTLS,把令牌钉在一把私钥上 | | ''fp = deviceFingerprint(req)'' | 客户端 / 设备指纹(UA、IP、TLS JA3/JA4 等) | 写进 claim 或独立校验,换设备即失效 | | ''fp = sha256(refreshToken)'' | 令牌指纹 | 库里只存哈希,泄库拿不到原文,并可用于检测复用 | | ''FP rate'' | False Positive 误报率 | 与加密无关,属检测 / 风控口径 | ===== 7. 用指纹做「令牌绑定」防盗用 ===== Bearer 令牌有个固有弱点:被偷走后谁拿到谁就能用。指纹提供了一条「钉住」的思路: * **DPoP(RFC 9449)**:客户端自己生成一对密钥,把公钥指纹作为 ''jkt'' claim 放进 access token;每次请求再附一个用私钥签名的 ''DPoP'' proof。服务端校验「proof 所用公钥的指纹 == token 里的 ''jkt''」。令牌被偷,没有私钥也发不出合法 proof * **mTLS 绑定**:把证书指纹与令牌 claim 关联,双向 TLS 通过才放行 * **设备指纹绑定**:把设备指纹哈希放进 claim,请求时重算比对。实现简单,但**误伤率高**:IP 会变(移动网络、双栈切换),浏览器升级会改 UA。风控场景更适合设成「降级为额外验证」,而不是直接拒绝 ===== 8. 实操建议 ===== - 新系统一律用 **SHA-256**;看到 ''x5t''(SHA-1)只做兼容,别主动生成 - 用 **RFC 7638 Thumbprint** 当 ''kid'',让 ''kid'' 能由公钥**独立推导**出来,避免人工命名撞车 - 规范化 JSON 的字段顺序、空格、编码**交给成熟库**(''jose''、''jose4j''、''python-jose'' 等),不要手拼字符串 - 指纹**编码统一**:JWK Thumbprint 用 base64url 无填充,X.509 指纹展示层常用带冒号的 hex,两者归一化之后再比对 - ''kid''、''jku''、''x5u'' 一律先查白名单再用,别让外部输入决定密钥来源 - 记住**指纹不是秘密,也不是身份凭据**:不要把它当密钥、当密码、当访问令牌 ===== 9. 常见坑速查 ===== ^ 现象 ^ 原因 ^ 处理方向 ^ | 用指纹算出的 ''kid'' 对不上 | 字段顺序 / 空格 / 编码不一致 | 统一走 RFC 7638,用库实现 | | ''x5t'' 与 ''x5t#S256'' 混用 | 前者是 SHA-1,后者是 SHA-256 | 新代码只用 SHA-256 版本 | | 换了新密钥,旧令牌全挂 | 旧公钥被直接删掉 | 先并行发布新 ''kid'',等旧令牌自然过期再下线 | | 拿到令牌就能异地使用 | Bearer 令牌本身不绑定客户端 | 用 DPoP / mTLS 做指纹绑定 | | 指纹明明相同却判为不同 | hex、base64url、大小写、冒号书写差异 | 比对前先归一化编码 | | 攻击者指定 ''kid'' 读到任意文件 | ''kid'' 被当成路径 / URL 使用 | ''kid'' 只允许在服务端白名单键表里查 | ===== 10. 指纹在哪看、长什么样 ===== 指纹是算出来的,所以要分两件事看:**取材来源**(对什么算哈希)和**显示形态**(用什么编码写出来)。 ==== 10.1 四种常见形态 ==== ^ 指纹类型 ^ 长度 ^ 长相 ^ 常见位置 ^ | SHA-256 十六进制(X.509 证书) | 64 个 hex 字符 | ''3F:1B:9A:E4:...:02'',冒号分隔大写 | 证书详情、keytool、浏览器 | | SHA-1 十六进制(旧证书) | 40 个 hex 字符 | ''0A:1B:2C:...:9F'',冒号分隔大写 | 老证书、''x5t'' | | base64url 无填充 | 43 个字符 | ''uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s'' | SSH、''jkt''、很多 ''kid'' | | MD5 十六进制(更老) | 32 个 hex 字符 | ''3f:6b:2c:...'',冒号分隔小写 | 早期 SSH 提示 | 换算记一下:**SHA-256 摘要固定 32 字节** → 写成 hex 是 64 个字符、写成 base64url 是 43 个字符;**SHA-1 摘要 20 字节** → hex 是 40 个字符。所以看段数就能猜算法:32 组冒号分隔是 SHA-256,20 组是 SHA-1。 ==== 10.2 SSH 公钥指纹 ==== <code bash> ssh-keygen -lf ~/.ssh/id_ed25519.pub # 256 SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s alice@example.com (ED25519) ssh-keygen -lf ~/.ssh/id_rsa.pub -E md5 # 换回旧的 MD5 格式 </code> 首次连接陌生主机会弹出来让你核对: <code> The authenticity of host 'github.com (140.82.113.4)' can't be established. ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU. </code> GitHub 的 ED25519 / ECDSA / RSA 三条官方指纹公布在其官方文档里,核对时以官方页面为准(本站 [[ssh]] 页面也讲过指纹校验)。 ==== 10.3 X.509 证书指纹(''x5t'' 的来源) ==== <code bash> openssl x509 -in cert.pem -noout -fingerprint -sha256 # SHA256 Fingerprint=3F:1B:9A:E4:... openssl x509 -in cert.pem -noout -fingerprint -sha1 # 对应旧的 x5t </code> Java 密钥库里的指纹: <code bash> keytool -list -v -keystore truststore.jks | grep -A2 Fingerprint </code> 浏览器里的入口:Chrome 打开开发者工具的 **Security** 面板 → View certificate,或在地址栏访问 %%chrome://certificate-manager%%;Firefox 点地址栏的锁图标 → 查看证书 → 详细信息。 ==== 10.4 JWT / JWKS 里的指纹 ==== **① 看 JWKS 端点**(指纹常被直接拿来当 ''kid''): <code bash> curl -s https://example.com/.well-known/jwks.json </code> <code json> { "keys": [ { "kty": "RSA", "use": "sig", "alg": "RS256", "kid": "cn-I_WNMClehiVp51i_0VpOENW1upEerA8sEam5hn-s", "n": "0vx7agoebGcQ...", "e": "AQAB" } ] } </code> 那个 43 个字符的 ''kid'' 就是 JWK Thumbprint 的长相。如果你离线按 RFC 7638 算出来的值与它完全一致,就能确认它是这么生成的。 **② 解 header 看 ''kid''**: <code bash> node -e "console.log(JSON.parse(Buffer.from(process.argv[1].split('.')[0],'base64url')))" "$TOKEN" </code> <code json> { "alg": "RS256", "kid": "cn-I_WNMClehiVp51i_0VpOENW1upEerA8sEam5hn-s" } </code> **③ 令牌里带 ''x5c'' / ''jwk'' 时**,可以现算指纹来核对: <code bash> openssl x509 -in from-x5c.pem -noout -fingerprint -sha256 </code> ==== 10.5 自己算一个 ==== <code bash> # 公钥指纹:SPKI DER 的 SHA-256,再 base64 openssl pkey -in key.pem -pubout -outform DER \ | openssl dgst -sha256 -binary | openssl base64 </code> 注意:JWK Thumbprint **不能**用上面这条命令,它必须按 RFC 7638 的规范 JSON 来算(见第 4 节的 ''jose'' 写法)。 ==== 10.6 必须记住的坑:同一把公钥,三种指纹互不相等 ==== * **SPKI DER 的 SHA-256**:上面那条 openssl 命令算出来的 * **RFC 7638 JWK Thumbprint**:''jkt'' 与相当多 ''kid'' 采用它 * **X.509 证书指纹**:对整张证书算,含签发者、有效期等元数据,''x5t#S256'' 用它 三者针对同一把密钥会给出**完全不同的字符串**。所以比对指纹前先确认三件事:**对什么算(JWK / SPKI / 整张证书)、用什么哈希(SHA-256 / SHA-1)、用什么编码(hex / base64url)**。对不上时先怀疑口径不一致,再怀疑密钥错了。 ===== 11. 指纹的几种作用:只有一种是在「选密钥」 ===== 常见的一个简化理解是:**指纹就是用来告诉后端该用哪把密钥的**。方向没错,但不够准确 —— 指纹的职责是**标识**,「选密钥」只是标识最主流的用法之一。 先拆开两个容易混的东西: ^ 东西 ^ 职责 ^ 是否必须是指纹 ^ | ''kid'' 字段 | 告诉后端用哪把密钥 | 不是,任意字符串都可以,如 ''key-1''、''2011-04-29'' | | 指纹 | 把某把密钥 / 证书 / 令牌压成一个短且可比较的字符串 | 它常被填进 ''kid'',但也可以用在别处 | 也就是说:**真正决定「用哪把密钥」的是 ''kid'' 字段加服务端白名单键表**,指纹只是 ''kid'' 最常见的一种取值方式。人工给密钥起个名字,一样能选密钥。 接下来看指纹的实际用途,只有第一行是在挑密钥: ^ 用法 ^ 实际在干什么 ^ 属于「选密钥」吗 ^ | ''kid'' = 公钥指纹 | 在 JWKS / 本地键表里匹配出对应密钥,再验签或解密 | **是**,这是最主流的用法 | | ''jkt''(DPoP) | 校验「proof 所用公钥」与「token 里记下的公钥」是不是同一把 | 不是,属**绑定一致性校验** | | ''x5t#S256'' | 核对令牌带来的证书是不是预期的那张(pinning) | 不是,属**核对 / 防替换** | | refresh token 的哈希指纹 | 库里只存哈希,比对判断令牌有没有被重复使用 | 不是,属**安全存储 + 重放检测** | | 设备指纹 | 风控维度,换设备就降级或要求二次验证 | 不是,与密钥无关 | | JWKS 里的 ''kid'' | 给公钥一个稳定索引,便于轮换与日志审计 | 算沾边,目的是「区分」而不是「挑选」 | 两点必须记住: * **指纹不证明密钥可信**:公钥指纹谁都能算,攻击者也能把自己公钥的指纹填进 ''kid'' 来「选」密钥。所以 ''kid'' 是**不可信输入**,只能拿去白名单里查,不能拿去拼文件路径、SQL、URL * **指纹不提供保密性**:它不参与任何加解密运算,拿到指纹推不出密钥,也不影响密文安全 更准确的一句话总结是: > 在 JWT 加密里,指纹就是一个**标识符**:把「某把密钥、某张证书、某个令牌」变成一串可比较的短字符串。它**最常**被用来回答「该用哪把密钥」(填进 ''kid''),但这并非唯一用途 —— 做绑定(''jkt'')、做核对(''x5t'')、做安全存储(令牌哈希)时,它并没有在选密钥。 最后一句反过来的推论:**如果只有一把密钥、而且从不轮换,''kid'' 和指纹都可以省掉** —— 指纹存在的全部前提,是「有多个东西需要区分或绑定」。 ===== 12. 一句话总结 ===== > JWT 加密语境里的 ''FP'' 就是**指纹**:它不参与加密运算,只负责**给公钥、证书或令牌内容发一张「身份证」**,让密钥匹配(''kid'')、令牌绑定(''jkt'')和泄露排查变得可自动化。标准里对应的是 RFC 7638 的 JWK Thumbprint,以及 ''x5t#S256'' 这类证书指纹。 ===== 13. 结构总览 ===== 下面这张图把全篇串一遍(可缩放、拖拽、点击折叠): ```mdk height=560 color=#4f46e5 # JWT 加密中的 FP ## 是什么 - FP = fingerprint 指纹 - 定长摘要,单向、可比对 - 公开无妨,不是密钥也不是凭据 - 加解密运算不依赖它 - 另一位含义:False Positive 误报 ## 为什么需要 - 多密钥共存与轮换 - 需要一个密钥标识符 - 指纹可自动生成,不会撞车 - kid 可由公钥独立推导 ## 标准字段 - kid:密钥 ID,常直接放指纹 - x5t:证书 SHA-1 指纹(旧) - x5t#S256:证书 SHA-256 指纹 - jwk / x5c:内嵌公钥与证书链 - jku / x5u:公钥、证书地址 - jkt:DPoP 的 JWK Thumbprint ## RFC 7638 Thumbprint - 只取 kty 的必需成员 - 字段名按字典序排列 - 无空格 JSON,UTF-8 编码 - SHA-256 后 base64url 去填充 - 规范化交给 jose 等库 ## JWE 加密流程 - header.encrypted_key.iv.ciphertext.tag - 发方把 kid 写进 header - 用公钥加密 CEK - 用 CEK 加密正文并产出 tag - 收方按指纹找私钥解 CEK - 指纹只负责选密钥 - kid 不可信,只查白名单表 ## 代码里的 fp - 公钥或证书指纹,用于 kid - 证书 pinning,防中间人换证书 - JWK Thumbprint,用于 jkt - 设备指纹,写进 claim - token 哈希指纹,存库比对 - FP rate 误报率,与加密无关 ## 令牌绑定 - DPoP:jkt + 私钥签名 proof - mTLS:证书指纹与 claim 关联 - 设备指纹:简单但误伤率高 ## 实操与坑 - 一律 SHA-256,别用 x5t - kid 用指纹,可独立推导 - 编码归一化后再比对 - kid / jku / x5u 走白名单 - 旋转密钥先并行发布新 kid - 指纹不是秘密,也不是身份凭据 ``` ---- 返回:[[代码术语]] 登录 Detach Close 该主题尚不存在 您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。 代码术语/fp.txt 最后更改: 2026/10/13 16:45由 张叶安 登录