Node.js、Python、Go で Open Badge の署名を検証する

署名付き Open Badge クレデンシャルを取得し、発行者の公開鍵を解決して JWS 署名を検証するための、動作するコードサンプル 3 種(Node、Python、Go)。

Nacho Coll 著者: 更新日 16 分で読了
署名付き Open Badge クレデンシャルを取得し、発行者の公開鍵を解決して JWS 署名を検証するための、動作するコードサンプル 3 種(Node、Python、Go)。

クレデンシャルを発行する側であれば、検証作業のほとんどは自動で行われます。受取人がリンクを共有し、雇用主がそれをクリックすれば、あとは検証ページが処理してくれます。ところが遅かれ早かれ、もっと鋭い質問が飛んできます。「このファイルが本当にあなたによって署名され、あとから改ざんされていないとどうやって分かるのですか?」この問いに答えるのがデジタル署名であり、主要な言語ならわずか 15 行ほどのコードで確認できます。

このチュートリアルでは、https://badges.ninja で発行された署名付き Open Badges 3.0 クレデンシャルを、Node.js、Python、Go で順を追って検証する方法を紹介します。クレデンシャルを発行するだけなら、どれも実行する必要はありません。システムを監査したい方、社内向けの検証ツールを作りたい方、あるいは「検証可能」が実際に何を意味するのかを理解したい方のための内容です。

実際に何を検証するのか

Open Badges には 2 つの検証レイヤーがあり、区別しておくと理解しやすくなります。

ホスト型検証は Open Badges 2.0 のモデルです。受賞には公開 URL があり、開けば誰でも発行者、バッジ、受取人のハッシュ化された ID、ステータスを確認できます。信頼の根拠は、データが発行者自身のドメインから配信されていることです。https://badges.ninja 上でそのページに到達できれば、クレデンシャルは本物です。コードも署名も不要です。

署名検証は、W3C Verifiable Credentials をベースにした Open Badges 3.0 のモデルです。クレデンシャルは署名付きトークンとしてパッケージ化されているため、ウォレットやメール添付にコピーされた後でも、何年経ってもオフラインで検証できます。信頼の根拠は数学です。トークンには、発行者の秘密鍵の持ち主にしか作れない署名が含まれています。

https://badges.ninja では、すべての受賞が両方の形式で利用できます。この記事は後者について解説します。2 つのバージョンの違いについては Open Badges v2 vs v3 を、ホスト型 JSON の解説は Open Badge JSON-LD ウォークスルー をご覧ください。

構成要素

署名付きクレデンシャルは VC-JWT です。ドットで区切られた 3 つの base64url 文字列からなる、コンパクトな JWS です。

header.payload.signature
  • ヘッダーは署名方法を示します。当サービスのクレデンシャルでは alg: EdDSA、typ: JWT、そして did:web:api.badges.ninja#<thumbprint> の形をした kid(鍵 ID)が含まれます。
  • ペイロードにはクレームが入っています。iss(発行者 DID did:web:api.badges.ninja)、jti(クレデンシャル ID)、nbf(有効開始)、任意の exp(有効期限)、そして実際の OpenBadgeCredential を持つ vc オブジェクトです。
  • 署名は、header.payload の正確なバイト列に対する Ed25519 署名です。

署名を検証する公開鍵は、発行者が認証なしで次の 2 か所に公開しています。

  • 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 サムプリントです。トークンヘッダーの kid は DID URL で、そのフラグメント(# の後ろの部分)が同じサムプリントになっています。このフラグメントを使って正しい鍵を選びます。

検証の手順

どの言語でも、次の 5 ステップは同じです。

  1. 公開エンドポイントから署名付きクレデンシャルを取得します。
  2. トークンを 3 つの部分に分割します。
  3. ヘッダーを読み、alg がちょうど EdDSA であることを確認し、kid からサムプリントを取り出します。
  4. JWKS を取得し、kid が一致する鍵を探します。
  5. その鍵で header.payload に対する Ed25519 署名を検証します。

クレデンシャルのエンドポイントは公開されており、受賞 ID(https://badges.ninja/awards/<awardId> のような検証 URL に含まれるものと同じ GUID)を受け取ります。

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

デフォルトでは、署名付き VC-JWT が application/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"])

このライブラリには Ed25519 の JWK インポート機能がないため、x 座標(生の 32 バイト公開鍵)を自分でデコードします。曲線が Ed25519 の OKP タイプの 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 のエントリを確認してください。

ダウンロードしたばかりのトークンで署名が無効になる。 header.payload を、再エンコードした JSON ではなく元の base64url テキストのまま検証したか確認してください。JSON を再シリアライズするとバイト列が変わり、署名が壊れます。ダウンロードしたトークンの末尾に改行が付いていないかも確認しましょう。

アルゴリズム混同。 古典的な JWT 攻撃では、トークンが alg: none を名乗ったり、対称アルゴリズムに切り替えたりして、検証側をだまして受け入れさせます。このサンプルは、期待するアルゴリズム EdDSA をハードコードし、それ以外をすべて拒否することで防いでいます。検証方法をトークンに決めさせてはいけません。

Base64 のパディングエラー。 JWS はパディングなしの base64url を使います。Python では(上記のように)パディングを補う必要があり、Go では URLEncoding ではなく RawURLEncoding が必要です。

署名は有効でも、クレデンシャルはまだ有効か? 署名が証明するのは真正性と完全性であり、現在のステータスではありません。正しく署名されていても、失効や期限切れになっていることはあります。ペイロードの exp と、次に説明する失効ステータスを確認してください。

失効の確認を忘れずに

https://badges.ninja が発行するすべての Open Badges 3.0 クレデンシャルには、W3C Bitstring Status List に従った credentialStatus が含まれています。これは /certify-badge/status/<listId> で取得できるステータスリストのクレデンシャルを指します。発行者が受賞を失効させると、そのリストのビットが 1 つ反転します。リストは約 1 分間キャッシュされるので、失効はすぐに検証側へ届きます。リストをデコードし、クレデンシャルの statusListIndex の位置のビットを読んでください。1 は失効、0 は有効を意味します。検証リファレンスには、このビットチェックの短い Node の例が載っています。

完全な検証ツールは 3 つのことを行います。署名の検証、有効期限の確認、失効ビットの確認です。発行者側から見た失効の様子を知りたい場合は、ダッシュボードの操作を受賞ガイドで解説しています。

これらが不要な場合

ほとんどのプログラム運営者は、このコードを書くことはなく、それで問題ありません。日常的な確認なら、受賞の公開ページ 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 と一致
失効/certify-badge/status/<listId> を指す credentialStatus

まとめ

Open Badge の署名検証は、短く機械的な手順です。トークンを取得し、アルゴリズムを固定し、サムプリントで鍵を見つけ、最初の 2 つのセグメントに対する 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.

ブログに戻る

関連記事