用 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.

返回部落格

相關文章