Open Badge aláírás ellenőrzése Node.js-ben, Pythonban és Go-ban

Három működő kódminta (Node, Python, Go) aláírt Open Badge hitelesítő adat lekéréséhez, a kibocsátó nyilvános kulcsának feloldásához és a JWS-aláírás ellenőrzéséhez.

Nacho Coll Szerző: Frissítve 9 perc olvasás
Három működő kódminta (Node, Python, Go) aláírt Open Badge hitelesítő adat lekéréséhez, a kibocsátó nyilvános kulcsának feloldásához és a JWS-aláírás ellenőrzéséhez.

Ha hitelesítő adatokat bocsátasz ki, az ellenőrzés nagy része nélküled zajlik: a címzett megosztja a linket, a munkáltató rákattint, a többit pedig az ellenőrző oldal elintézi. Előbb-utóbb azonban valaki élesebb kérdést tesz fel: „Honnan tudom, hogy ezt a fájlt tényleg te írtad alá, és utólag nem módosították?” Erre a kérdésre a digitális aláírás válaszol, az ellenőrzése pedig bármelyik elterjedt nyelven nagyjából tizenöt sor kód.

Ez a bemutató lépésről lépésre megmutatja, hogyan ellenőrizhetsz egy https://badges.ninja-n kibocsátott, aláírt Open Badges 3.0 hitelesítő adatot Node.js-ben, Pythonban és Go-ban. A kibocsátáshoz nincs szükséged semmire ebből. Azoknak szól, akik auditálni szeretnék a rendszert, belső ellenőrző eszközt építenek, vagy egyszerűen meg akarják érteni, mit jelent a gyakorlatban az „ellenőrizhető”.

Mit ellenőrzöl valójában

Az Open Badgesben két ellenőrzési réteg van, és érdemes szétválasztani őket.

A hosztolt ellenőrzés az Open Badges 2.0 modellje. A kiosztásnak nyilvános URL-je van, és aki megnyitja, látja a kibocsátót, a jelvényt, a címzett hashelt azonosítóját és az állapotot. A bizalom abból fakad, hogy az adatot a kibocsátó saját domainje szolgálja ki. Ha eléred az oldalt a https://badges.ninja-n, a hitelesítő adat valódi. Ehhez nem kell sem kód, sem aláírás.

Az aláírás-ellenőrzés az Open Badges 3.0 modellje, amely a W3C Verifiable Credentials-re épül. A hitelesítő adat aláírt tokenként van becsomagolva, így offline is ellenőrizhető, évekkel később is, még akkor is, ha egy tárcába vagy e-mail-mellékletbe másolták. A bizalom a matematikából ered: a token olyan aláírást hordoz, amelyet csak a kibocsátó privát kulcsának birtokosa állíthatott elő.

A https://badges.ninja-n minden kiosztás mindkét formában elérhető. Ez a cikk a másodikról szól. Ha a két verzió közti különbségek háttere érdekel, olvasd el az Open Badges v2 vs v3 cikket, a hosztolt JSON bemutatásához pedig nézd meg az Open Badge JSON-LD útmutatót.

A mozgó alkatrészek

Az aláírt hitelesítő adat egy VC-JWT: egy kompakt JWS, vagyis három, pontokkal elválasztott base64url karakterlánc.

header.payload.signature
  • A header megmondja, hogyan íródott alá. A mi hitelesítő adatainkban alg: EdDSA, typ: JWT és egy kid (kulcsazonosító) szerepel, amely így néz ki: did:web:api.badges.ninja#<thumbprint>.
  • A payload tartalmazza az állításokat (claims), köztük az iss (a kibocsátó DID-je: did:web:api.badges.ninja), a jti (a hitelesítő adat azonosítója), az nbf (érvényesség kezdete), egy opcionális exp (lejárat), valamint egy vc objektumot a tényleges OpenBadgeCredential-lel.
  • Az aláírás egy Ed25519 aláírás a header.payload pontos bájtjai felett.

Az aláírást ellenőrző nyilvános kulcsot a kibocsátó két helyen teszi közzé, mindkettő hitelesítés nélkül elérhető:

  • A https://api.badges.ninja/.well-known/jwks.json egy JWK Set-et ad vissza.
  • A https://api.badges.ninja/.well-known/did.json a did:web:api.badges.ninja DID-dokumentumát adja vissza.

A JWKS kid a kulcs RFC 7638 szerinti ujjlenyomata (thumbprint). A token headerében lévő kid a DID URL, amelynek töredéke (a # utáni rész) ugyanez az ujjlenyomat. Ez a töredék segít kiválasztani a megfelelő kulcsot.

Az ellenőrzés receptje

Minden nyelven ugyanazt az öt lépést követjük:

  1. Kérd le az aláírt hitelesítő adatot a nyilvános végpontról.
  2. Bontsd a tokent három részre.
  3. Olvasd ki a headert, ellenőrizd, hogy az alg pontosan EdDSA, és vedd ki az ujjlenyomatot a kid-ből.
  4. Kérd le a JWKS-t, és keresd meg azt a kulcsot, amelynek a kid-je egyezik.
  5. Ellenőrizd az Ed25519 aláírást a header.payload felett ezzel a kulccsal.

A hitelesítőadat-végpont nyilvános, és a kiosztás azonosítóját várja (ugyanaz a GUID, amelyet egy ellenőrző URL-ben látsz, például https://badges.ninja/awards/<awardId>):

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

Alapértelmezés szerint az aláírt VC-JWT-t adja vissza application/jwt típusként. Add hozzá a ?format=json paramétert, hogy az aláíratlan hitelesítő adat JSON-ját olvasásra megkapd. Mindkettőt dokumentálja az ellenőrzési referencia.

Vedd észre, hogy nincs külön „ellenőrizd ezt helyettem” végpont, és ez szándékos. Az a szerver, amely azt mondja, „igen, érvényes”, azt kéri, hogy bízz a szerverben. Az aláírás lényege éppen az, hogy magad ellenőrizheted egy közzétett kulccsal szemben.

Node.js

A Node beépített crypto modulja támogatja az Ed25519-et és a JWK-importot, így nincs szükség függőségekre.

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);

A null algoritmus-argumentum helyes: Ed25519 esetén a kulcs típusa rögzíti az algoritmust. Ha inkább könyvtárat használnál, a jose ugyanezt végzi el a compactVerify és az importJWK segítségével, és a header-ellenőrzéseket is elintézi helyetted.

Python

A cryptography csomag közvetlenül biztosít Ed25519-et. Telepítsd így: 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"])

A Python ebben a könyvtárban nem tud Ed25519 JWK-t importálni, ezért az x koordinátát (a nyers, 32 bájtos nyilvános kulcsot) magunk dekódoljuk. Egy OKP típusú, Ed25519 görbéjű JWK ennyit tartalmaz.

Go

A Go standard könyvtára mindent lefed, a crypto/ed25519-et is.

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)
}

Futtasd így: go run main.go <awardId>. A hibakezelést az olvashatóság kedvéért lerövidítettük; egy valódi eszközben minden dekódolást ellenőrizni kell.

Gyakori hibák és értelmezésük

A kulcs nem található a JWKS-ben. A token headerében lévő teljes kid-et (did:web:api.badges.ninja#abc) hasonlítottad össze a JWKS kid-jével (abc). Csak a # utáni töredéket hasonlítsd. Ha a töredék így sem egyezik, lehet, hogy a kibocsátó a token kiállítása óta kulcsot cserélt; kérd le a DID-dokumentumot, és nézd meg a verificationMethod bejegyzéseit.

Érvénytelen aláírás egy frissen letöltött tokenen. Ellenőrizd, hogy a header.payload-ot az eredeti base64url szövegként ellenőrizted-e, nem újrakódolt JSON-ként. A JSON újraszerializálása megváltoztatja a bájtokat, és tönkreteszi az aláírást. Nézd meg azt is, hogy a letöltött token végén nincs-e sortörés.

Algoritmuskeverés. A klasszikus JWT-támadás egy olyan token, amely alg: none-t állít, vagy szimmetrikus algoritmusra vált, hogy az ellenőrzőt rávegye az elfogadására. A mintáink ezt úgy kerülik el, hogy az elvárt algoritmust, az EdDSA-t fixen beégetik, és minden mást elutasítanak. Soha ne hagyd, hogy a token döntse el, hogyan ellenőrzik.

Base64 padding hibák. A JWS padding nélküli base64url-t használ. Pythonban vissza kell tenni a paddinget (lásd fent), Go-ban pedig RawURLEncoding kell, nem URLEncoding.

Érvényes aláírás, de jó még a hitelesítő adat? Az aláírás a hitelességet és az integritást bizonyítja, nem a jelenlegi állapotot. Egy hitelesítő adat lehet helyesen aláírt, és mégis visszavont vagy lejárt. Ellenőrizd a payload exp mezőjét, és a következőkben leírt visszavonási állapotot.

Ne feledkezz meg a visszavonásról

A https://badges.ninja minden Open Badges 3.0 hitelesítő adata tartalmaz egy credentialStatus bejegyzést, amely a W3C Bitstring Status List szabványt követi. Ez egy állapotlista-hitelesítő adatra mutat, amelyet a /certify-badge/status/<listId> címen érhetsz el. Amikor a kibocsátó visszavon egy kiosztást, a listában egy bit átbillen; a lista nagyjából egy percig gyorsítótárazott, így a visszavonások gyorsan eljutnak az ellenőrzőkhöz. Dekódold a listát, és olvasd ki a bitet a hitelesítő adat statusListIndex helyén: az 1 visszavontat, a 0 aktívat jelent. Az ellenőrzési referencia tartalmaz egy rövid Node-példát erre a bitellenőrzésre.

Egy teljes ellenőrző három dolgot csinál: ellenőrzi az aláírást, a lejáratot és a visszavonási bitet. Ha látni szeretnéd, hogyan néz ki a visszavonás a kibocsátó oldaláról, az irányítópulton elérhető műveletet a kiosztási útmutató mutatja be.

Amikor nincs szükséged erre az egészre

A legtöbb programfelelős soha nem ír ilyen kódot, és ez rendben van. A mindennapi ellenőrzésekhez nyisd meg a kiosztás nyilvános oldalát a https://badges.ninja/awards/<awardId> címen, és olvasd el. Az oldalhoz nem kell regisztráció és kulcs sem, és megmutatja a kibocsátót, a jelvényt és az állapotot. A címzettek a nyilvános hitelesítőadat-oldalukon a Download menüből letölthetik a Verifiable Credentialt, és importálhatják bármely Open Badges 3.0 tárcába.

Az aláírás-ellenőrzés akkor lesz értékes, ha:

  • egy munkáltató vagy egyetem automatizálni akarja a kapott hitelesítő adatok ellenőrzését;
  • nyilvántartó rendszert építesz, amely hitelesítő adatok másolatait tárolja, és bizonyítania kell, hogy nem módosultak;
  • egy auditor bizonyítékot kér arra, hogy a hitelesítő adataid egymástól függetlenül ellenőrizhetők, nem csupán „bízzon a weboldalunkban”.

A kibocsátáshoz használt API-kulcs-beállításra itt nincs szükség, mert ezek a végpontok mind nyilvánosak. Ha mégis kódból szeretnél hitelesítő adatokat kibocsátani, az API gyorsindító végigvezet a kulcs létrehozásán és az első kiosztáson.

API Keys — empty state

Gyorsreferencia

ElemÉrték
Aláírt hitelesítő adatGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Aláíratlan JSON olvasásraugyanaz az URL ?format=json-nal
Kibocsátó DIDdid:web:api.badges.ninja
Nyilvános kulcsok/.well-known/jwks.json és /.well-known/did.json
AlgoritmusEd25519 (EdDSA)
Kulcsegyeztetésa header kid töredéke egyenlő a JWKS kid-del
VisszavonáscredentialStatus, amely a /certify-badge/status/<listId> címre mutat

Összegzés

Egy Open Badge aláírásának ellenőrzése rövid, mechanikus rutin: kérd le a tokent, rögzítsd az algoritmust, keresd meg a kulcsot az ujjlenyomat alapján, és ellenőrizd az Ed25519 aláírást az első két szegmens felett. Add hozzá a lejárat- és visszavonás-ellenőrzést, és olyan ellenőrződ lesz, amely senkiben nem bízik a kibocsátó közzétett kulcsán kívül. Éppen ez a függetlenség teszi a digitális hitelesítő adatot többre egy PDF-nél.

Készen állsz az első ellenőrizhető hitelesítő adatod kibocsátására? Kezdd ingyen a badges.ninja-n — vizuális tervező, nyilvános ellenőrző oldal, PDF-tanúsítvány, Open Badge v2.0 kimenet. Bankkártya nem szükséges.

Nacho Coll

A szerzőről

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.

Vissza a Blogra

Kapcsolódó cikkek