Preverjanje podpisa Open Badge v Node.js, Pythonu in Go

Trije delujoči primeri kode (Node, Python, Go) za pridobitev podpisane poverilnice Open Badge, iskanje javnega ključa izdajatelja in preverjanje podpisa JWS.

Nacho Coll Avtor Posodobljeno 9 min branja
Trije delujoči primeri kode (Node, Python, Go) za pridobitev podpisane poverilnice Open Badge, iskanje javnega ključa izdajatelja in preverjanje podpisa JWS.

Če izdajate poverilnice, se večina preverjanja zgodi brez vas: prejemnik deli povezavo, delodajalec klikne nanjo, preostalo pa opravi stran za preverjanje. Prej ali slej pa nekdo postavi ostrejše vprašanje: »Kako vem, da ste to datoteko res podpisali vi in da je nihče ni naknadno spremenil?« Na to odgovori digitalni podpis, njegovo preverjanje pa v vsakem večjem jeziku zahteva približno petnajst vrstic kode.

Ta vodič korak za korakom pokaže, kako v Node.js, Pythonu in Go preveriti podpisano poverilnico Open Badges 3.0, izdano prek https://badges.ninja. Za izdajanje poverilnic vam ničesar od tega ni treba zagnati. Namenjen je tistim, ki želijo preveriti sistem, zgraditi notranje orodje za preverjanje ali preprosto razumeti, kaj v praksi pomeni »preverljivo«.

Kaj pravzaprav preverjate

V Open Badges obstajata dve ravni preverjanja, zato ju je dobro ločiti.

Gostovano preverjanje je model Open Badges 2.0. Priznanje ima javni URL, vsak, ki ga odpre, pa vidi izdajatelja, značko, zgoščeno identiteto prejemnika in stanje. Zaupanje izhaja iz dejstva, da se podatki servirajo z izdajateljeve domene. Če lahko stran odprete na https://badges.ninja, je poverilnica resnična. Za to ni potrebna nobena koda ali podpis.

Preverjanje podpisa je model Open Badges 3.0, zgrajen na W3C Verifiable Credentials. Poverilnica je zapakirana kot podpisan žeton, zato jo je mogoče preveriti brez povezave, tudi leta pozneje, četudi so jo kopirali v denarnico ali e-poštno prilogo. Zaupanje izhaja iz matematike: žeton nosi podpis, ki ga je lahko ustvaril le imetnik zasebnega ključa izdajatelja.

Na https://badges.ninja je vsako priznanje na voljo v obeh oblikah. Ta članek govori o drugi. Za ozadje razlik med različicama preberite Open Badges v2 vs v3, za oglede gostovanega JSON-a pa si oglejte vodnik po Open Badge JSON-LD.

Sestavni deli

Podpisana poverilnica je VC-JWT: kompakten JWS, torej trije nizi base64url, ločeni s pikami.

header.payload.signature
  • Glava pove, kako je bil žeton podpisan. Pri naših poverilnicah vsebuje alg: EdDSA, typ: JWT in kid (ID ključa), ki izgleda kot did:web:api.badges.ninja#<thumbprint>.
  • Vsebina (payload) nosi trditve, med njimi iss (DID izdajatelja did:web:api.badges.ninja), jti (ID poverilnice), nbf (veljavno od), neobvezni exp (potek) in objekt vc z dejansko poverilnico OpenBadgeCredential.
  • Podpis je podpis Ed25519 nad natančnimi bajti header.payload.

Javni ključ za preverjanje podpisa izdajatelj objavi na dveh mestih, obe brez overjanja:

  • https://api.badges.ninja/.well-known/jwks.json vrne nabor JWK.
  • https://api.badges.ninja/.well-known/did.json vrne dokument DID za did:web:api.badges.ninja.

kid v JWKS je prstni odtis ključa po RFC 7638. kid v glavi žetona je URL DID, njegov fragment (del za #) pa je isti prstni odtis. S tem fragmentom izberete pravi ključ.

Recept za preverjanje

V vseh jezikih sledimo istim petim korakom:

  1. Pridobite podpisano poverilnico z javne končne točke.
  2. Žeton razdelite na tri dele.
  3. Preberite glavo, preverite, da je alg natanko EdDSA, in iz kid vzemite prstni odtis.
  4. Pridobite JWKS in poiščite ključ, katerega kid se ujema.
  5. S tem ključem preverite podpis Ed25519 nad header.payload.

Končna točka poverilnice je javna in sprejme ID priznanja (isti GUID, ki ga vidite v URL-ju za preverjanje, kot je https://badges.ninja/awards/<awardId>):

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

Privzeto vrne podpisan VC-JWT kot application/jwt. Če dodate ?format=json, dobite nepodpisan JSON poverilnice za branje. Oboje opisuje referenca za preverjanje.

Upoštevajte, da ni ločene končne točke »preveri to namesto mene«, in to je namerno. Strežnik, ki vam pove »da, veljavno«, od vas zahteva, da mu zaupate. Smisel podpisa je prav v tem, da ga lahko sami preverite z objavljenim ključem.

Node.js

Vgrajeni modul crypto v Node podpira Ed25519 in uvoz JWK, zato odvisnosti niso potrebne.

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

Argument algoritma null je pravilen: pri Ed25519 algoritem določa že vrsta ključa. Če imate raje knjižnico, jose opravi isto delo s compactVerify in importJWK ter namesto vas preveri glavo.

Python

Paket cryptography vam neposredno ponuja Ed25519. Namestite ga z 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 v tej knjižnici nima uvoza JWK za Ed25519, zato koordinato x (surovi 32-bajtni javni ključ) dekodiramo sami. To je vse, kar vsebuje JWK tipa OKP s krivuljo Ed25519.

Go

Standardna knjižnica Go pokrije vse, vključno s 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)
}

Zaženite ga z go run main.go <awardId>. Obravnava napak je zaradi berljivosti okrnjena; v pravem orodju bi preverili vsako dekodiranje.

Pogoste napake in kako jih razbrati

Ključa ni v JWKS. Primerjali ste celoten kid iz glave žetona (did:web:api.badges.ninja#abc) s kid iz JWKS (abc). Primerjajte samo fragment za #. Če se fragment še vedno ne ujema, je izdajatelj morda od izdaje žetona zamenjal ključe; pridobite dokument DID in si oglejte vnose verificationMethod.

Neveljaven podpis pri žetonu, ki ste ga pravkar prenesli. Preverite, da ste preverjali header.payload kot izvirno besedilo base64url, ne na novo kodiranega JSON-a. Ponovna serializacija JSON-a spremeni bajte in pokvari podpis. Preverite tudi, ali ima prenesen žeton na koncu znak za novo vrstico.

Zamenjava algoritma. Klasičen napad na JWT je žeton, ki trdi alg: none ali preklopi na simetričen algoritem, da preverjevalnik zavede v sprejem. Naši primeri se mu izognejo s trdo kodiranim pričakovanim algoritmom EdDSA in zavrnitvijo vsega drugega. Nikoli ne dovolite, da žeton sam določi, kako se preverja.

Napake pri zapolnitvi base64. JWS uporablja base64url brez zapolnitve. Python zahteva, da zapolnitev dodate nazaj (prikazano zgoraj), Go pa potrebuje RawURLEncoding, ne URLEncoding.

Podpis je veljaven, a je poverilnica še dobra? Podpis dokazuje pristnost in celovitost, ne trenutnega stanja. Poverilnica je lahko pravilno podpisana, a vseeno preklicana ali potekla. Preverite exp v vsebini in bit preklica, opisan v nadaljevanju.

Ne pozabite na preklic

Vsaka poverilnica Open Badges 3.0 z https://badges.ninja vsebuje vnos credentialStatus, ki sledi W3C Bitstring Status List. Kaže na poverilnico s seznamom stanj, ki jo pridobite na /certify-badge/status/<listId>. Ko izdajatelj prekliče priznanje, se na seznamu obrne bit; seznam se predpomni približno eno minuto, zato preklici hitro dosežejo preverjevalce. Dekodirajte seznam in preberite bit pri statusListIndex poverilnice: 1 pomeni preklicano, 0 aktivno. Referenca za preverjanje vključuje kratek primer v Node za preverjanje tega bita.

Popoln preverjevalnik naredi tri stvari: preveri podpis, preveri potek in preveri bit preklica. Če želite videti, kako preklic izgleda z izdajateljeve strani, je dejanje na nadzorni plošči opisano v vodniku po priznanjih.

Kdaj vam vsega tega ni treba

Večina vodij programov te kode nikoli ne bo napisala, in to je povsem v redu. Za vsakodnevna preverjanja odprite javno stran priznanja na https://badges.ninja/awards/<awardId> in jo preberite. Stran ne zahteva registracije ali ključa ter prikazuje izdajatelja, značko in stanje. Prejemniki lahko Verifiable Credential prenesejo tudi iz menija Download na svoji javni strani poverilnice in ga uvozijo v katero koli denarnico Open Badges 3.0.

Preverjanje podpisa postane dragoceno, ko:

  • želi delodajalec ali univerza avtomatizirati preverjanje prejetih poverilnic;
  • gradite sistem evidenc, ki hrani kopije poverilnic in mora dokazati, da niso bile spremenjene;
  • revizor zahteva dokaz, da so vaše poverilnice neodvisno preverljive, ne le »zaupajte našemu spletnemu mestu«.

Iste nastavitve ključa API, kot se uporabljajo za izdajanje, tukaj niso potrebne, ker so vse te končne točke javne. Če želite poverilnice izdajati iz kode, vas hitri začetek z API-jem vodi skozi ustvarjanje ključa in vaše prvo priznanje.

API Keys — empty state

Hitra referenca

ElementVrednost
Podpisana poverilnicaGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Nepodpisan JSON za branjeisti URL z ?format=json
DID izdajateljadid:web:api.badges.ninja
Javni ključi/.well-known/jwks.json in /.well-known/did.json
AlgoritemEd25519 (EdDSA)
Ujemanje ključafragment kid v glavi je enak kid v JWKS
PrekliccredentialStatus, ki kaže na /certify-badge/status/<listId>

Za konec

Preverjanje podpisa Open Badge je kratka, mehanična rutina: pridobite žeton, določite algoritem, poiščite ključ po prstnem odtisu in preverite podpis Ed25519 nad prvima dvema segmentoma. Dodajte preverjanje poteka in preklica in imate preverjevalnik, ki ne zaupa nikomur razen objavljenemu ključu izdajatelja. Ta neodvisnost naredi digitalno poverilnico vredno več kot PDF.

Ste pripravljeni izdati svojo prvo preverljivo poverilnico? Začnite brezplačno na badges.ninja — vizualni oblikovalnik, javna stran za preverjanje, PDF-certifikat, izhod Open Badge v2.0. Kreditna kartica ni potrebna.

Nacho Coll

O avtorju

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.

Nazaj na Blog

Povezani članki