Verifiera en Open Badge-signatur i Node.js, Python och Go

Tre fungerande kodexempel (Node, Python, Go) för att hämta en signerad Open Badge-meritbevis, slå upp utfärdarens publika nyckel och verifiera JWS-signaturen.

Nacho Coll Av Uppdaterad 9 min läsning
Tre fungerande kodexempel (Node, Python, Go) för att hämta en signerad Open Badge-meritbevis, slå upp utfärdarens publika nyckel och verifiera JWS-signaturen.

Om du utfärdar meritbevis sköts det mesta av verifieringen utan dig: en mottagare delar en länk, en arbetsgivare klickar på den och verifieringssidan gör resten. Men förr eller senare ställer någon en vassare fråga: ”Hur vet jag att den här filen verkligen signerades av dig och inte ändrades i efterhand?” Den frågan besvaras av en digital signatur, och att kontrollera en tar ungefär femton rader kod i vilket vanligt språk som helst.

Den här handledningen visar steg för steg hur du verifierar ett signerat Open Badges 3.0-meritbevis som utfärdats via https://badges.ninja, i Node.js, Python och Go. Du behöver inget av detta för att utfärda meritbevis. Det är till för dig som vill granska systemet, bygga ett internt verifieringsverktyg eller helt enkelt förstå vad ”verifierbart” betyder i praktiken.

Vad du egentligen verifierar

Det finns två lager av verifiering i Open Badges, och det hjälper att hålla isär dem.

Hostad verifiering är Open Badges 2.0-modellen. Utmärkelsen har en publik URL, och den som öppnar den ser utfärdaren, märket, mottagarens hashade identitet och status. Förtroendet kommer av att datan serveras från utfärdarens egen domän. Kan du nå sidan på https://badges.ninja är meritbeviset äkta. Det kräver varken kod eller signatur.

Signaturverifiering är Open Badges 3.0-modellen, byggd på W3C Verifiable Credentials. Meritbeviset paketeras som en signerad token och kan därför kontrolleras offline, år senare, även om det kopierats till en plånbok eller en e-postbilaga. Förtroendet kommer från matematiken: token bär en signatur som bara innehavaren av utfärdarens privata nyckel kan ha skapat.

På https://badges.ninja finns varje utmärkelse i båda formerna. Den här artikeln handlar om den andra. Vill du ha bakgrunden till hur de två versionerna skiljer sig, läs Open Badges v2 vs v3, och för en genomgång av den hostade JSON-filen, se genomgången av Open Badge JSON-LD.

De rörliga delarna

Det signerade meritbeviset är ett VC-JWT: en kompakt JWS, alltså tre base64url-strängar åtskilda av punkter.

header.payload.signature
  • Headern berättar hur det signerades. För våra meritbevis innehåller den alg: EdDSA, typ: JWT och en kid (nyckel-id) som ser ut så här: did:web:api.badges.ninja#<thumbprint>.
  • Payloaden innehåller påståendena (claims), bland annat iss (utfärdarens DID did:web:api.badges.ninja), jti (meritbevisets id), nbf (giltigt från), ett valfritt exp (utgång) och ett vc-objekt med själva OpenBadgeCredential.
  • Signaturen är en Ed25519-signatur över de exakta byten i header.payload.

Den publika nyckel som kontrollerar signaturen publiceras av utfärdaren på två ställen, båda utan autentisering:

  • https://api.badges.ninja/.well-known/jwks.json returnerar ett JWK Set.
  • https://api.badges.ninja/.well-known/did.json returnerar DID-dokumentet för did:web:api.badges.ninja.

JWKS-kid är nyckelns RFC 7638-tumavtryck (thumbprint). kid i tokenens header är DID-URL:en, och dess fragment (delen efter #) är samma tumavtryck. Det fragmentet är det som låter dig välja rätt nyckel.

Verifieringsreceptet

Alla språk följer samma fem steg:

  1. Hämta det signerade meritbeviset från den publika endpointen.
  2. Dela upp token i dess tre delar.
  3. Läs headern, kontrollera att alg är exakt EdDSA och ta tumavtrycket från kid.
  4. Hämta JWKS och hitta nyckeln vars kid matchar.
  5. Verifiera Ed25519-signaturen över header.payload med den nyckeln.

Endpointen för meritbeviset är publik och tar utmärkelsens id (samma GUID som du ser i en verifierings-URL som https://badges.ninja/awards/<awardId>):

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

Som standard returneras det signerade VC-JWT som application/jwt. Lägg till ?format=json för att få det osignerade meritbevisets JSON att läsa. Verifieringsreferensen dokumenterar båda.

Lägg märke till att det inte finns någon separat endpoint för ”verifiera det här åt mig”, och det är avsiktligt. En server som säger ”ja, giltigt” ber dig lita på servern. Hela poängen med en signatur är att du kan kontrollera den själv mot en publicerad nyckel.

Node.js

Nodes inbyggda crypto-modul stöder Ed25519 och JWK-import, så du behöver inga beroenden.

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

Algoritmargumentet null är korrekt: med Ed25519 fastställer nyckeltypen algoritmen. Föredrar du ett bibliotek gör jose samma jobb med compactVerify och importJWK, och sköter header-kontrollerna åt dig.

Python

Paketet cryptography ger dig Ed25519 direkt. Installera det med 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 saknar JWK-import för Ed25519 i det här biblioteket, så vi avkodar x-koordinaten (den råa publika nyckeln på 32 byte) själva. Det är allt en JWK av typen OKP med kurvan Ed25519 innehåller.

Go

Gos standardbibliotek täcker allt, inklusive 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)
}

Kör det med go run main.go <awardId>. Felhanteringen är förenklad för läsbarhetens skull; i ett riktigt verktyg bör du kontrollera varje avkodning.

Vanliga fel och hur du tolkar dem

Nyckeln hittas inte i JWKS. Du jämförde hela kid från tokenens header (did:web:api.badges.ninja#abc) med JWKS-kid (abc). Jämför bara fragmentet efter #. Matchar fragmentet fortfarande inte kan utfärdaren ha roterat nycklar sedan token skapades; hämta DID-dokumentet och titta på dess verificationMethod-poster.

Ogiltig signatur på en token du just laddat ner. Kontrollera att du verifierade header.payload som den ursprungliga base64url-texten, inte omkodad JSON. Om JSON serialiseras om ändras byten och signaturen går sönder. Kontrollera också om den nedladdade token har ett avslutande radbrytningstecken.

Algoritmförväxling. Den klassiska JWT-attacken är en token som hävdar alg: none eller byter till en symmetrisk algoritm så att en verifierare luras att acceptera den. Våra exempel undviker det genom att hårdkoda den förväntade algoritmen, EdDSA, och avvisa allt annat. Låt aldrig token bestämma hur den ska verifieras.

Base64-paddingfel. JWS använder base64url utan padding. Python behöver få paddingen tillbaka (se ovan), och Go kräver RawURLEncoding, inte URLEncoding.

Giltig signatur, men är meritbeviset fortfarande gott? En signatur bevisar äkthet och integritet, inte aktuell status. Ett meritbevis kan vara korrekt signerat och ändå återkallat eller utgånget. Kontrollera exp i payloaden och återkallelsestatusen som beskrivs härnäst.

Glöm inte återkallelse

Varje Open Badges 3.0-meritbevis från https://badges.ninja har en credentialStatus-post som följer W3C Bitstring Status List. Den pekar på ett statuslistebevis som du kan hämta på /certify-badge/status/<listId>. När en utfärdare återkallar en utmärkelse växlar en bit i den listan; listan cachas i ungefär en minut, så återkallelser når verifierare snabbt. Avkoda listan och läs biten vid meritbevisets statusListIndex: 1 betyder återkallad, 0 betyder aktiv. Verifieringsreferensen innehåller ett kort Node-exempel på den bitkontrollen.

En komplett verifierare gör tre saker: verifierar signaturen, kontrollerar utgångsdatumet och kontrollerar återkallelsebiten. Vill du se hur återkallelse ser ut från utfärdarens sida beskrivs åtgärden i instrumentpanelen i guiden om utmärkelser.

När du inte behöver något av detta

De flesta programansvariga kommer aldrig att skriva den här koden, och det är helt okej. För vardagliga kontroller öppnar du utmärkelsens publika sida på https://badges.ninja/awards/<awardId> och läser den. Sidan kräver varken registrering eller nyckel och visar utfärdare, märke och status. Mottagare kan också ladda ner Verifiable Credential från Download-menyn på sin publika meritbevissida och importera det i valfri Open Badges 3.0-plånbok.

Signaturkontroll blir värdefull när:

  • en arbetsgivare eller ett universitet vill automatisera kontroller av meritbevis de tar emot;
  • du bygger ett registersystem som lagrar kopior av meritbevis och behöver bevisa att de inte har ändrats;
  • en revisor ber om belägg för att dina meritbevis är oberoende verifierbara, inte bara ”lita på vår webbplats”.

Samma API-nyckelinställning som används för att utfärda behövs inte här, eftersom alla dessa endpoints är publika. Vill du utfärda meritbevis från kod går API-snabbstarten igenom hur du skapar en nyckel och din första utmärkelse.

API Keys — empty state

Snabbreferens

PostVärde
Signerat meritbevisGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Osignerad JSON att läsasamma URL med ?format=json
Utfärdarens DIDdid:web:api.badges.ninja
Publika nycklar/.well-known/jwks.json och /.well-known/did.json
AlgoritmEd25519 (EdDSA)
Nyckelmatchningfragmentet av header-kid är lika med JWKS-kid
ÅterkallelsecredentialStatus som pekar på /certify-badge/status/<listId>

Sammanfattning

Att verifiera en Open Badge-signatur är en kort, mekanisk rutin: hämta token, lås algoritmen, hitta nyckeln via tumavtrycket och kontrollera Ed25519-signaturen över de två första segmenten. Lägg till kontroller av utgång och återkallelse så har du en verifierare som inte litar på någon annan än utfärdarens publicerade nyckel. Det oberoendet är precis vad som gör ett digitalt meritbevis värt mer än en PDF.

Redo att utfärda ditt första verifierbara meritbevis? Börja gratis på badges.ninja — visuell designer, publik verifieringssida, PDF-certifikat, Open Badge v2.0-utdata. Inget kreditkort krävs.

Nacho Coll

Om författaren

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.

Tillbaka till Bloggen

Relaterade artiklar