Open Badge parašo patikrinimas Node.js, Python ir Go kalbomis

Trys veikiantys kodo pavyzdžiai (Node, Python, Go): kaip gauti pasirašytą Open Badge kredencialą, rasti išdavėjo viešąjį raktą ir patikrinti JWS parašą.

Nacho Coll Autorius Atnaujinta 8 min skaitymo
Trys veikiantys kodo pavyzdžiai (Node, Python, Go): kaip gauti pasirašytą Open Badge kredencialą, rasti išdavėjo viešąjį raktą ir patikrinti JWS parašą.

Jei išduodate kredencialus, didžiąją patikrinimo darbo dalį atlieka kiti: gavėjas pasidalija nuoroda, darbdavys ją atidaro, o patikrinimo puslapis padaro likusį darbą. Bet anksčiau ar vėliau kas nors užduoda aštresnį klausimą: „Iš kur žinoti, kad šį failą tikrai pasirašėte jūs ir kad jo niekas nepakeitė?“ Į tai atsako skaitmeninis parašas, o jį patikrinti galima maždaug penkiolika kodo eilučių bet kuria populiaria kalba.

Šioje pamokoje žingsnis po žingsnio parodome, kaip patikrinti per https://badges.ninja išduotą pasirašytą Open Badges 3.0 kredencialą Node.js, Python ir Go kalbomis. Kredencialams išduoti nieko iš to paleisti nereikia. Tai skirta tiems, kurie nori auditą atlikti sistemai, sukurti vidinį patikrinimo įrankį arba tiesiog suprasti, ką praktiškai reiškia „patikrinamas“.

Ką iš tikrųjų tikrinate

Open Badges yra du patikrinimo lygiai, ir verta juos skirti.

Talpinamas patikrinimas (angl. hosted verification) yra Open Badges 2.0 modelis. Apdovanojimas turi viešą URL, o jį atidaręs kiekvienas mato išdavėją, skaitmeninį ženklelį, užhaširuotą gavėjo tapatybę ir būseną. Pasitikėjimas kyla iš to, kad duomenys pateikiami iš paties išdavėjo domeno. Jei puslapį pasiekiate adresu https://badges.ninja, kredencialas tikras. Tam nereikia nei kodo, nei parašo.

Parašo patikrinimas yra Open Badges 3.0 modelis, paremtas W3C Verifiable Credentials. Kredencialas supakuotas kaip pasirašytas žetonas, todėl jį galima patikrinti neprisijungus, net po daugelio metų, net jei jis buvo nukopijuotas į piniginę ar el. laiško priedą. Pasitikėjimas kyla iš matematikos: žetonas turi parašą, kurį galėjo sukurti tik išdavėjo privačiojo rakto turėtojas.

Per https://badges.ninja kiekvienas apdovanojimas pasiekiamas abiem formomis. Šis straipsnis apie antrąją. Jei norite sužinoti, kuo skiriasi dvi versijos, skaitykite Open Badges v2 vs v3, o talpinamo JSON apžvalgą rasite Open Badge JSON-LD analizėje.

Judančios dalys

Pasirašytas kredencialas yra VC-JWT: kompaktiškas JWS, t. y. trys base64url eilutės, atskirtos taškais.

header.payload.signature
  • Antraštė (angl. header) nurodo, kaip pasirašyta. Mūsų kredencialuose joje yra alg: EdDSA, typ: JWT ir kid (rakto identifikatorius), atrodantis taip: did:web:api.badges.ninja#<thumbprint>.
  • Turinys (angl. payload) talpina teiginius, įskaitant iss (išdavėjo DID did:web:api.badges.ninja), jti (kredencialo id), nbf (galioja nuo), neprivalomą exp (galiojimo pabaiga) ir vc objektą su pačiu OpenBadgeCredential.
  • Parašas yra Ed25519 parašas, apskaičiuotas iš tikslių header.payload baitų.

Viešąjį raktą parašui patikrinti išdavėjas skelbia dviem vietomis, abi be autentifikavimo:

  • https://api.badges.ninja/.well-known/jwks.json grąžina JWK rinkinį.
  • https://api.badges.ninja/.well-known/did.json grąžina did:web:api.badges.ninja DID dokumentą.

JWKS kid yra rakto RFC 7638 atspaudas (angl. thumbprint). Žetono antraštės kid yra DID URL, o jo fragmentas (dalis po #) yra tas pats atspaudas. Būtent pagal šį fragmentą pasirenkamas tinkamas raktas.

Patikrinimo receptas

Kiekviena kalba seka tuos pačius penkis žingsnius:

  1. Gaukite pasirašytą kredencialą iš viešo galinio taško.
  2. Padalykite žetoną į tris dalis.
  3. Perskaitykite antraštę, patikrinkite, ar alg tiksliai lygus EdDSA, ir iš kid paimkite atspaudą.
  4. Gaukite JWKS ir raskite raktą su atitinkančiu kid.
  5. Tuo raktu patikrinkite Ed25519 parašą, apskaičiuotą iš header.payload.

Kredencialo galinis taškas yra viešas ir priima apdovanojimo id (tą patį GUID, kurį matote patikrinimo URL, pavyzdžiui, https://badges.ninja/awards/<awardId>):

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

Pagal numatytuosius nustatymus grąžinamas pasirašytas VC-JWT kaip application/jwt. Pridėkite ?format=json, jei norite gauti nepasirašytą kredencialo JSON skaitymui. Abu variantai aprašyti patikrinimo nuorodoje.

Atkreipkite dėmesį: atskiro „patikrink tai už mane“ galinio taško nėra, ir tai sąmoninga. Serveris, kuris sako „taip, galioja“, prašo pasitikėti serveriu. Visa parašo esmė ta, kad jį galite patikrinti patys pagal viešai paskelbtą raktą.

Node.js

Node integruotas crypto modulis palaiko Ed25519 ir JWK importą, todėl priklausomybių nereikia.

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

Argumentas null vietoje algoritmo yra teisingas: naudojant Ed25519 algoritmą nulemia rakto tipas. Jei mieliau naudojate biblioteką, jose atlieka tą patį darbą su compactVerify ir importJWK ir pati patikrina antraštes.

Python

Paketas cryptography suteikia Ed25519 tiesiogiai. Įdiekite jį komanda 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"])

Šioje bibliotekoje Python neturi Ed25519 JWK importo, todėl x koordinatę (neapdorotą 32 baitų viešąjį raktą) iškoduojame patys. Būtent tiek ir yra OKP tipo JWK su kreive Ed25519.

Go

Go standartinė biblioteka apima viską, įskaitant 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)
}

Paleiskite komanda go run main.go <awardId>. Klaidų apdorojimas sutrumpintas dėl aiškumo; tikrame įrankyje reikėtų tikrinti kiekvieną dekodavimą.

Dažnos klaidos ir kaip jas skaityti

Rakto nėra JWKS. Palyginote visą žetono antraštės kid (did:web:api.badges.ninja#abc) su JWKS kid (abc). Lyginkite tik fragmentą po #. Jei fragmentas vis tiek nesutampa, galbūt išdavėjas pakeitė raktus nuo žetono išrašymo; gaukite DID dokumentą ir peržiūrėkite jo verificationMethod įrašus.

Parašas neteisingas ką tik atsisiųstam žetonui. Patikrinkite, ar tikrinote header.payload kaip pradinį base64url tekstą, o ne iš naujo užkoduotą JSON. Perserializavus JSON pasikeičia baitai ir parašas nebegalioja. Taip pat patikrinkite, ar atsisiųstas žetonas nesibaigia naujos eilutės simboliu.

Algoritmo painiojimas. Klasikinė JWT ataka: žetonas teigia alg: none arba persijungia į simetrinį algoritmą, kad patikrintojas būtų apgautas jį priimti. Mūsų pavyzdžiai to išvengia užkoduodami laukiamą algoritmą EdDSA ir atmesdami visa kita. Niekada neleiskite žetonui pačiam pasirinkti, kaip jis bus tikrinamas.

Base64 užpildymo klaidos. JWS naudoja base64url be užpildymo. Python reikia užpildymą pridėti atgal (parodyta aukščiau), o Go reikia RawURLEncoding, ne URLEncoding.

Parašas galioja, bet ar kredencialas vis dar geras? Parašas įrodo autentiškumą ir vientisumą, bet ne dabartinę būseną. Kredencialas gali būti teisingai pasirašytas ir vis tiek atšauktas ar pasibaigęs. Patikrinkite turinio exp ir toliau aprašytą atšaukimo būseną.

Nepamirškite atšaukimo

Kiekvienas Open Badges 3.0 kredencialas iš https://badges.ninja turi credentialStatus įrašą pagal W3C Bitstring Status List. Jis nurodo būsenos sąrašo kredencialą, kurį galite gauti adresu /certify-badge/status/<listId>. Kai išdavėjas atšaukia apdovanojimą, sąraše pasikeičia bitas; sąrašas talpinamas podėlyje maždaug minutei, todėl atšaukimai patikrintojus pasiekia greitai. Iškoduokite sąrašą ir perskaitykite bitą kredencialo statusListIndex pozicijoje: 1 reiškia atšaukta, 0 reiškia aktyvu. Patikrinimo nuorodoje rasite trumpą Node pavyzdį, kaip tikrinamas šis bitas.

Pilnas patikrintojas atlieka tris dalykus: patikrina parašą, galiojimo pabaigą ir atšaukimo bitą. Jei norite pamatyti, kaip atšaukimas atrodo išdavėjo pusėje, valdymo skydelio veiksmas aprašytas apdovanojimų vadove.

Kada viso to nereikia

Dauguma programų vadovų niekada nerašys šio kodo, ir tai gerai. Kasdieniam patikrinimui atidarykite viešą apdovanojimo puslapį https://badges.ninja/awards/<awardId> ir perskaitykite jį. Puslapiui nereikia nei registracijos, nei rakto, o jame matyti išdavėjas, skaitmeninis ženklelis ir būsena. Gavėjai taip pat gali atsisiųsti Verifiable Credential iš Download meniu savo viešame kredencialo puslapyje ir importuoti jį į bet kurią Open Badges 3.0 piniginę.

Parašo tikrinimas tampa vertingas, kai:

  • darbdavys ar universitetas nori automatizuoti gaunamų kredencialų patikrą;
  • kuriate įrašų sistemą, kuri saugo kredencialų kopijas ir turi įrodyti, kad jos nebuvo pakeistos;
  • auditorius prašo įrodymų, kad jūsų kredencialai nepriklausomai patikrinami, o ne tik „pasitikėkite mūsų svetaine“.

Čia nereikia to paties API rakto, kuris naudojamas išduodant, nes visi šie galiniai taškai yra vieši. Jei kredencialus norite išduoti iš kodo, API greitoji pradžia paaiškina, kaip sukurti raktą ir pirmąjį apdovanojimą.

API Keys — empty state

Trumpa nuoroda

ElementasReikšmė
Pasirašytas kredencialasGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Nepasirašytas JSON skaitymuitas pats URL su ?format=json
Išdavėjo DIDdid:web:api.badges.ninja
Viešieji raktai/.well-known/jwks.json ir /.well-known/did.json
AlgoritmasEd25519 (EdDSA)
Rakto atitikimasantraštės kid fragmentas lygus JWKS kid
AtšaukimascredentialStatus, nurodantis į /certify-badge/status/<listId>

Apibendrinimas

Open Badge parašo patikrinimas yra trumpa, mechaniška rutina: gaukite žetoną, užfiksuokite algoritmą, raskite raktą pagal atspaudą ir patikrinkite Ed25519 parašą pirmiesiems dviem segmentams. Pridėkite galiojimo ir atšaukimo patikras, ir turėsite patikrintoją, kuris nepasitiki niekuo, išskyrus išdavėjo paskelbtą raktą. Būtent ši nepriklausomybė daro skaitmeninį kredencialą vertingesnį už PDF.

Pasiruošę išduoti pirmąjį patikrinamą kredencialą? Pradėkite nemokamai badges.ninja — vizualinis dizaineris, viešas patikrinimo puslapis, PDF sertifikatas, Open Badge v2.0 išvestis. Kreditinės kortelės nereikia.

Nacho Coll

Apie autorių

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.

Grįžti į Tinklaraštį

Susiję straipsniai