用 Node.js、Python 和 Go 验证 Open Badge 签名

三份可运行的代码示例(Node、Python、Go),教你获取已签名的 Open Badge 凭证、解析颁发者的公钥,并验证 JWS 签名。

Nacho Coll 作者 更新于 14 分钟阅读
三份可运行的代码示例(Node、Python、Go),教你获取已签名的 Open Badge 凭证、解析颁发者的公钥,并验证 JWS 签名。

如果你负责颁发凭证,大部分验证工作其实不需要你插手:接收者分享一个链接,雇主点开,验证页面就会完成剩下的事。但迟早会有人问出更尖锐的问题:“我怎么知道这个文件真的是你们签发的,而且之后没被改过?”回答这个问题靠的是数字签名,而在任何主流语言里,验证一个签名大约只需要十五行代码。

本教程会一步步演示,如何在 Node.js、Python 和 Go 中验证通过 https://badges.ninja 颁发的、已签名的 Open Badges 3.0 凭证。颁发凭证并不需要运行其中任何代码。它是写给想要审计系统、构建内部验证工具,或者只是想弄明白“可验证”在实践中意味着什么的人。

你到底在验证什么

Open Badges 中有两层验证,把它们分清楚会有帮助。

托管验证是 Open Badges 2.0 的模式。每个奖项都有一个公开 URL,任何人打开它都能看到颁发者、徽章、接收者经过哈希处理的身份以及状态。信任来自数据由颁发者自己的域名提供这一事实。只要你能在 https://badges.ninja 上打开该页面,这份凭证就是真实的。这一模式不需要代码,也不需要签名。

签名验证是 Open Badges 3.0 的模式,基于 W3C Verifiable Credentials。凭证被打包成一个已签名的令牌,因此即使它被复制到钱包或邮件附件里,多年之后也可以离线验证。信任来自数学:令牌携带的签名,只有颁发者私钥的持有者才能生成。

在 https://badges.ninja 上,每个奖项都同时提供这两种形式。本文讲的是第二种。如果想了解两个版本的区别,请阅读 Open Badges v2 vs v3;想看托管 JSON 的详细讲解,请见 Open Badge JSON-LD 示例详解。

涉及的组成部分

已签名的凭证是一个 VC-JWT:一种紧凑的 JWS,即由点号分隔的三段 base64url 字符串。

header.payload.signature
  • **头部(header)**说明签名方式。我们的凭证中包含 alg: EdDSA、typ: JWT,以及形如 did:web:api.badges.ninja#<thumbprint> 的 kid(密钥 ID)。
  • **载荷(payload)**包含各项声明,其中有 iss(颁发者 DID did:web:api.badges.ninja)、jti(凭证 ID)、nbf(生效时间)、可选的 exp(过期时间),以及包含实际 OpenBadgeCredential 的 vc 对象。
  • **签名(signature)**是对 header.payload 的精确字节计算出的 Ed25519 签名。

用来校验签名的公钥由颁发者发布在两个位置,均无需身份验证:

  • https://api.badges.ninja/.well-known/jwks.json 返回一个 JWK Set。
  • https://api.badges.ninja/.well-known/did.json 返回 did:web:api.badges.ninja 的 DID 文档。

JWKS 中的 kid 是该密钥的 RFC 7638 指纹(thumbprint)。令牌头部中的 kid 是 DID URL,它的片段(# 之后的部分)正是同一个指纹。靠这个片段,你就能选出正确的密钥。

验证流程

每种语言都遵循同样的五个步骤:

  1. 从公开端点获取已签名的凭证。
  2. 把令牌拆成三部分。
  3. 读取头部,确认 alg 恰好是 EdDSA,并从 kid 中取出指纹。
  4. 获取 JWKS,找到 kid 匹配的密钥。
  5. 用该密钥验证对 header.payload 的 Ed25519 签名。

凭证端点是公开的,参数为奖项 ID(就是验证 URL 中看到的那个 GUID,例如 https://badges.ninja/awards/<awardId>):

curl https://api.badges.ninja/certify-badge/award/<awardId>/vc

默认情况下,它以 application/jwt 返回已签名的 VC-JWT。加上 ?format=json 可以得到未签名、便于阅读的凭证 JSON。验证参考文档对两者都有说明。

请注意,这里没有单独的“替我验证一下”端点,这是有意为之的。一个告诉你“是的,有效”的服务器,是在要求你信任这台服务器。签名的意义恰恰在于,你可以用公开发布的密钥自己去验证。

Node.js

Node 内置的 crypto 模块支持 Ed25519 和 JWK 导入,所以不需要任何依赖。

import crypto from "node:crypto";
const API = "https://api.badges.ninja";
const awardId = process.argv[2];
// —— 1. fetch the signed credential
const jwt = (await (await fetch(`${API}/certify-badge/award/${awardId}/vc`)).text()).trim();
// —— 2. split into parts
const [h, p, s] = jwt.split(".");
const header = JSON.parse(Buffer.from(h, "base64url").toString());
const payload = JSON.parse(Buffer.from(p, "base64url").toString());
// —— 3. refuse anything but EdDSA
if (header.alg !== "EdDSA") throw new Error(`unexpected alg: ${header.alg}`);
const thumbprint = header.kid.split("#")[1];
// —— 4. resolve the public key
const jwks = await (await fetch(`${API}/.well-known/jwks.json`)).json();
const jwk = jwks.keys.find((k) => k.kid === thumbprint);
if (!jwk) throw new Error("no matching key in JWKS");
const publicKey = crypto.createPublicKey({ key: jwk, format: "jwk" });
// —— 5. verify the signature over "header.payload"
const ok = crypto.verify(null, Buffer.from(`${h}.${p}`), publicKey, Buffer.from(s, "base64url"));
console.log(ok ? "signature valid" : "signature INVALID");
console.log("issuer:", payload.iss, "credential:", payload.jti);

算法参数传 null 是正确的:对于 Ed25519,密钥类型就已经确定了算法。如果你更喜欢用库,jose 通过 compactVerify 和 importJWK 也能完成同样的工作,并且会替你处理头部检查。

Python

cryptography 包直接提供 Ed25519。用 pip install cryptography requests 安装。

import base64, json, sys
import requests
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
API = "https://api.badges.ninja"
award_id = sys.argv[1]
def b64url(data: str) -> bytes:
    return base64.urlsafe_b64decode(data + "=" * (-len(data) % 4))
# —— 1. fetch the signed credential
jwt = requests.get(f"{API}/certify-badge/award/{award_id}/vc").text.strip()
# —— 2. split into parts
h, p, s = jwt.split(".")
header = json.loads(b64url(h))
payload = json.loads(b64url(p))
# —— 3. refuse anything but EdDSA
if header["alg"] != "EdDSA":
    raise SystemExit(f"unexpected alg: {header['alg']}")
thumbprint = header["kid"].split("#")[1]
# —— 4. resolve the public key
keys = requests.get(f"{API}/.well-known/jwks.json").json()["keys"]
jwk = next((k for k in keys if k["kid"] == thumbprint), None)
if jwk is None:
    raise SystemExit("no matching key in JWKS")
public_key = Ed25519PublicKey.from_public_bytes(b64url(jwk["x"]))
# —— 5. verify the signature over "header.payload"
try:
    public_key.verify(b64url(s), f"{h}.{p}".encode())
    print("signature valid")
except InvalidSignature:
    print("signature INVALID")
print("issuer:", payload["iss"], "credential:", payload["jti"])

这个库中 Python 没有针对 Ed25519 的 JWK 导入功能,所以我们自己解码 x 坐标(即 32 字节的原始公钥)。类型为 OKP、曲线为 Ed25519 的 JWK 包含的就只有这些。

Go

Go 的标准库就够用了,包括 crypto/ed25519。

package main
import (
	"crypto/ed25519"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
const api = "https://api.badges.ninja"
func get(url string) []byte {
	res, err := http.Get(url)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	b, _ := io.ReadAll(res.Body)
	return b
}
func main() {
	awardID := os.Args[1]
	// —— 1. fetch the signed credential
	jwt := strings.TrimSpace(string(get(api + "/certify-badge/award/" + awardID + "/vc")))
	// —— 2. split into parts
	parts := strings.Split(jwt, ".")
	if len(parts) != 3 {
		panic("not a compact JWS")
	}
	enc := base64.RawURLEncoding
	hb, _ := enc.DecodeString(parts[0])
	var header struct{ Alg, Kid string }
	json.Unmarshal(hb, &header)
	// —— 3. refuse anything but EdDSA
	if header.Alg != "EdDSA" {
		panic("unexpected alg: " + header.Alg)
	}
	thumbprint := strings.Split(header.Kid, "#")[1]
	// —— 4. resolve the public key
	var jwks struct {
		Keys []struct{ Kid, X string } `json:"keys"`
	}
	json.Unmarshal(get(api+"/.well-known/jwks.json"), &jwks)
	var pub ed25519.PublicKey
	for _, k := range jwks.Keys {
		if k.Kid == thumbprint {
			pub, _ = enc.DecodeString(k.X)
		}
	}
	if pub == nil {
		panic("no matching key in JWKS")
	}
	// —— 5. verify the signature over "header.payload"
	sig, _ := enc.DecodeString(parts[2])
	ok := ed25519.Verify(pub, []byte(parts[0]+"."+parts[1]), sig)
	fmt.Println("signature valid:", ok)
}

用 go run main.go <awardId> 运行。为了便于阅读,错误处理做了精简;在真正的工具里,你应该检查每一次解码。

常见错误及其解读

在 JWKS 中找不到密钥。 你拿令牌头部的完整 kid(did:web:api.badges.ninja#abc)去和 JWKS 的 kid(abc)比较了。只比较 # 之后的片段。如果片段仍然不匹配,可能是自令牌签发以来颁发者轮换了密钥;请获取 DID 文档,查看其中的 verificationMethod 条目。

刚下载的令牌签名无效。 检查你验证的是原始 base64url 文本 header.payload,而不是重新编码后的 JSON。重新序列化 JSON 会改变字节,从而破坏签名。同时检查下载的令牌末尾是否带有换行符。

算法混淆。 经典的 JWT 攻击是:令牌声称 alg: none,或切换成对称算法,诱使验证方接受它。我们的示例通过硬编码预期算法 EdDSA 并拒绝其他一切来避开这个问题。永远不要让令牌自己决定如何被验证。

Base64 填充错误。 JWS 使用不带填充的 base64url。Python 需要把填充补回去(如上所示),Go 需要使用 RawURLEncoding,而不是 URLEncoding。

签名有效,但凭证现在还有效吗? 签名证明的是真实性和完整性,而不是当前状态。一份凭证可能签名正确,却已被撤销或已过期。请检查载荷中的 exp,并检查下面介绍的撤销状态。

别忘了撤销状态

https://badges.ninja 上的每份 Open Badges 3.0 凭证都带有一个遵循 W3C Bitstring Status List 的 credentialStatus 条目。它指向一份状态列表凭证,你可以在 /certify-badge/status/<listId> 获取。当颁发者撤销某个奖项时,该列表中的一个比特位会翻转;列表会缓存约一分钟,因此撤销会很快传达给验证方。解码该列表,读取凭证 statusListIndex 处的比特位:1 表示已撤销,0 表示有效。验证参考文档中包含一个检查该比特位的简短 Node 示例。

一个完整的验证程序要做三件事:验证签名、检查有效期、检查撤销位。如果想从颁发者一侧看看撤销是什么样子,仪表板中的操作在奖项指南中有介绍。

什么时候你不需要这些

大多数项目负责人永远不会写这类代码,这完全没问题。日常检查时,打开奖项的公开页面 https://badges.ninja/awards/<awardId> 看一眼就行。该页面无需注册,也无需密钥,会显示颁发者、徽章和状态。接收者还可以在自己的公开凭证页面上通过 Download 菜单下载 Verifiable Credential,并导入任何 Open Badges 3.0 钱包。

在以下情况下,签名检查就变得很有价值:

  • 雇主或大学希望对收到的凭证自动执行检查;
  • 你在构建一个保存凭证副本的记录系统,需要证明这些副本没有被篡改;
  • 审计人员要求提供证据,证明你的凭证可以被独立验证,而不只是“相信我们的网站”。

这里不需要颁发凭证时使用的那套 API 密钥设置,因为这些端点全都是公开的。如果你确实想通过代码颁发凭证,API 快速入门会带你创建密钥并完成第一次颁奖。

API Keys — empty state

速查表

项目值
已签名凭证GET https://api.badges.ninja/certify-badge/award/<awardId>/vc
供阅读的未签名 JSON同一 URL 加上 ?format=json
颁发者 DIDdid:web:api.badges.ninja
公钥/.well-known/jwks.json 和 /.well-known/did.json
算法Ed25519 (EdDSA)
密钥匹配头部 kid 的片段等于 JWKS 的 kid
撤销credentialStatus 指向 /certify-badge/status/<listId>

总结

验证 Open Badge 签名是一套简短、机械的流程:获取令牌、固定算法、按指纹找到密钥,再对前两段检查 Ed25519 签名。加上有效期和撤销检查,你就拥有了一个只信任颁发者所公布密钥的验证程序。正是这种独立性,让数字凭证比一份 PDF 更有价值。

准备好颁发你的第一份可验证凭证了吗? 在 badges.ninja 免费开始 — 可视化设计器、公开验证页面、PDF 证书、Open Badge v2.0 输出。无需信用卡。

Nacho Coll

关于作者

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

返回博客

相关文章