Provjera potpisa Open Badgea u Node.js-u, Pythonu i Gou

Tri radna primjera koda (Node, Python, Go) za dohvaćanje potpisane Open Badge vjerodajnice, pronalaženje javnog ključa izdavatelja i provjeru JWS potpisa.

Nacho Coll Autor: Ažurirano 9 min čitanja
Tri radna primjera koda (Node, Python, Go) za dohvaćanje potpisane Open Badge vjerodajnice, pronalaženje javnog ključa izdavatelja i provjeru JWS potpisa.

Ako izdajete vjerodajnice, većina posla oko provjere odvija se bez vas: primatelj podijeli poveznicu, poslodavac klikne na nju, a stranica za provjeru napravi ostalo. No prije ili kasnije netko će postaviti oštrije pitanje. „Kako znam da je ovu datoteku doista potpisali vi i da je nitko nije izmijenio nakon toga?” Na to pitanje odgovara digitalni potpis, a njegova provjera traje oko petnaest redaka koda u bilo kojem uobičajenom jeziku.

Ovaj vodič korak po korak pokazuje kako provjeriti potpisanu vjerodajnicu Open Badges 3.0 izdanu putem https://badges.ninja u Node.js-u, Pythonu i Gou. Za izdavanje vjerodajnica ne morate pokretati ništa od ovoga. Namijenjen je onima koji žele provesti reviziju sustava, izgraditi internu alatku za provjeru ili jednostavno razumjeti što „provjerljivo” znači u praksi.

Što zapravo provjeravate

U Open Badgesu postoje dvije razine provjere i korisno ih je držati odvojeno.

Hostirana provjera je model Open Badgesa 2.0. Dodjela ima javni URL, a svatko tko ga otvori vidi izdavatelja, značku, hashirani identitet primatelja i status. Povjerenje proizlazi iz činjenice da se podaci poslužuju s izdavateljeve vlastite domene. Ako možete otvoriti stranicu na https://badges.ninja, vjerodajnica je stvarna. Za to nisu potrebni ni kod ni potpis.

Provjera potpisa je model Open Badgesa 3.0, izgrađen na W3C Verifiable Credentials. Vjerodajnica je pakirana kao potpisani token pa se može provjeriti izvan mreže, godinama kasnije, čak i ako je kopirana u novčanik ili privitak e-pošte. Povjerenje proizlazi iz matematike: token nosi potpis koji je mogao stvoriti samo vlasnik izdavateljeva privatnog ključa.

Na https://badges.ninja svaka je dodjela dostupna u oba oblika. Ovaj članak govori o drugom. Ako želite saznati po čemu se dvije verzije razlikuju, pročitajte Open Badges v2 vs v3, a za razgledavanje hostiranog JSON-a pogledajte prolaz kroz Open Badge JSON-LD.

Dijelovi slagalice

Potpisana vjerodajnica je VC-JWT: kompaktni JWS, odnosno tri base64url niza odvojena točkama.

header.payload.signature
  • Zaglavlje govori kako je potpisano. Za naše vjerodajnice sadrži alg: EdDSA, typ: JWT i kid (ID ključa) oblika did:web:api.badges.ninja#<thumbprint>.
  • Sadržaj (payload) nosi tvrdnje, uključujući iss (DID izdavatelja did:web:api.badges.ninja), jti (ID vjerodajnice), nbf (vrijedi od), neobavezni exp (istek) i objekt vc sa stvarnom OpenBadgeCredential.
  • Potpis je Ed25519 potpis nad točnim bajtovima header.payload.

Javni ključ kojim se provjerava potpis izdavatelj objavljuje na dva mjesta, oba bez autentifikacije:

  • https://api.badges.ninja/.well-known/jwks.json vraća JWK Set.
  • https://api.badges.ninja/.well-known/did.json vraća DID dokument za did:web:api.badges.ninja.

kid u JWKS-u je RFC 7638 otisak (thumbprint) ključa. kid u zaglavlju tokena je DID URL, a njegov fragment (dio nakon #) isti je taj otisak. Taj fragment služi za odabir pravog ključa.

Recept za provjeru

Svaki jezik slijedi istih pet koraka:

  1. Dohvatite potpisanu vjerodajnicu s javne krajnje točke.
  2. Podijelite token na tri dijela.
  3. Pročitajte zaglavlje, provjerite je li alg točno EdDSA i uzmite otisak iz kid.
  4. Dohvatite JWKS i pronađite ključ čiji se kid podudara.
  5. Tim ključem provjerite Ed25519 potpis nad header.payload.

Krajnja točka vjerodajnice je javna i prima ID dodjele (isti GUID koji vidite u URL-u za provjeru, npr. https://badges.ninja/awards/<awardId>):

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

Prema zadanim postavkama vraća potpisani VC-JWT kao application/jwt. Dodajte ?format=json da dobijete nepotpisani JSON vjerodajnice za čitanje. Referenca za provjeru opisuje obje mogućnosti.

Imajte na umu da ne postoji zasebna krajnja točka „provjeri ovo umjesto mene”, i to je namjerno. Poslužitelj koji vam kaže „da, valjano je” traži od vas da vjerujete poslužitelju. Cijela je poanta potpisa da ga možete sami provjeriti prema objavljenom ključu.

Node.js

Ugrađeni modul crypto u Nodeu podržava Ed25519 i uvoz JWK-a, pa vam ne trebaju nikakve ovisnosti.

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 ispravan: kod Ed25519 vrsta ključa određuje algoritam. Ako više volite biblioteku, jose radi isti posao s compactVerify i importJWK te umjesto vas obavlja provjere zaglavlja.

Python

Paket cryptography daje vam Ed25519 izravno. Instalirajte ga naredbom 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 u ovoj biblioteci nema uvoz JWK-a za Ed25519, pa koordinatu x (sirovih 32 bajta javnog ključa) dekodiramo sami. To je sve što JWK tipa OKP s krivuljom Ed25519 sadrži.

Go

Standardna biblioteka Goa pokriva sve, uključujući 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)
}

Pokrenite ga s go run main.go <awardId>. Rukovanje pogreškama skraćeno je radi čitljivosti; u pravoj alatki provjeravali biste svako dekodiranje.

Česte pogreške i kako ih čitati

Ključ nije pronađen u JWKS-u. Usporedili ste cijeli kid iz zaglavlja tokena (did:web:api.badges.ninja#abc) s kid-om iz JWKS-a (abc). Usporedite samo fragment nakon #. Ako se ni fragment ne podudara, izdavatelj je možda rotirao ključeve otkako je token izdan; dohvatite DID dokument i pogledajte njegove unose verificationMethod.

Neispravan potpis na tokenu koji ste upravo preuzeli. Provjerite jeste li header.payload provjeravali kao izvorni base64url tekst, a ne kao ponovno kodiran JSON. Ponovna serijalizacija JSON-a mijenja bajtove i lomi potpis. Provjerite i ima li preuzeti token znak za novi redak na kraju.

Zbunjivanje algoritma. Klasičan napad na JWT je token koji tvrdi alg: none ili prelazi na simetrični algoritam kako bi se verifikator prevario da ga prihvati. Naši primjeri to izbjegavaju tako što čvrsto kodiraju očekivani algoritam, EdDSA, i odbijaju sve drugo. Nikada ne dopustite da token odabere kako će se provjeriti.

Pogreške base64 nadopune. JWS koristi base64url bez nadopune. Python zahtijeva da se nadopuna vrati (prikazano gore), a Go treba RawURLEncoding, a ne URLEncoding.

Potpis je valjan, ali je li vjerodajnica još uvijek dobra? Potpis dokazuje autentičnost i cjelovitost, ne trenutačni status. Vjerodajnica može biti ispravno potpisana, a ipak opozvana ili istekla. Provjerite exp u sadržaju i provjerite status opoziva opisan u nastavku.

Ne zaboravite opoziv

Svaka vjerodajnica Open Badges 3.0 s https://badges.ninja nosi unos credentialStatus koji slijedi W3C Bitstring Status List. Upućuje na vjerodajnicu popisa statusa koju možete dohvatiti na /certify-badge/status/<listId>. Kad izdavatelj opozove dodjelu, u tom se popisu promijeni jedan bit; popis se kešira oko minutu pa opozivi brzo stižu do verifikatora. Dekodirajte popis i pročitajte bit na statusListIndex vjerodajnice: 1 znači opozvana, 0 znači aktivna. Referenca za provjeru uključuje kratak primjer u Nodeu za tu provjeru bita.

Potpun verifikator radi tri stvari: provjerava potpis, provjerava istek i provjerava bit opoziva. Ako želite vidjeti kako opoziv izgleda s izdavateljeve strane, radnja na nadzornoj ploči opisana je u vodiču za dodjele.

Kada vam ništa od ovoga ne treba

Većina voditelja programa nikada neće pisati ovaj kod, i to je u redu. Za svakodnevne provjere otvorite javnu stranicu dodjele na https://badges.ninja/awards/<awardId> i pročitajte je. Stranica ne zahtijeva registraciju ni ključ, a prikazuje izdavatelja, značku i status. Primatelji također mogu preuzeti Verifiable Credential iz izbornika Download na svojoj javnoj stranici vjerodajnice i uvesti je u bilo koji novčanik za Open Badges 3.0.

Provjera potpisa postaje vrijedna kada:

  • poslodavac ili sveučilište želi automatizirati provjeru vjerodajnica koje primaju;
  • gradite sustav evidencije koji pohranjuje kopije vjerodajnica i mora dokazati da nisu mijenjane;
  • revizor traži dokaz da su vaše vjerodajnice neovisno provjerljive, a ne samo „vjerujte našoj web-stranici”.

Isto postavljanje API ključa koje se koristi za izdavanje ovdje nije potrebno jer su sve ove krajnje točke javne. Ako želite izdavati vjerodajnice iz koda, brzi početak s API-jem vodi vas kroz izradu ključa i prve dodjele.

API Keys — empty state

Brza referenca

StavkaVrijednost
Potpisana vjerodajnicaGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Nepotpisani JSON za čitanjeisti URL s ?format=json
DID izdavateljadid:web:api.badges.ninja
Javni ključevi/.well-known/jwks.json i /.well-known/did.json
AlgoritamEd25519 (EdDSA)
Podudaranje ključafragment zaglavlja kid jednak je kid-u iz JWKS-a
OpozivcredentialStatus koji upućuje na /certify-badge/status/<listId>

Zaključak

Provjera potpisa Open Badgea kratka je, mehanička rutina: dohvatite token, fiksirajte algoritam, pronađite ključ po otisku i provjerite Ed25519 potpis nad prva dva segmenta. Dodajte provjere isteka i opoziva i imate verifikator koji ne vjeruje nikome osim objavljenom ključu izdavatelja. Upravo ta neovisnost čini digitalnu vjerodajnicu vrjednijom od PDF-a.

Spremni izdati svoju prvu provjerljivu vjerodajnicu? Započnite besplatno na badges.ninja — vizualni dizajner, javna stranica za provjeru, PDF certifikat, izlaz Open Badge v2.0. Kreditna kartica nije potrebna.

Nacho Coll

O autoru

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.

Natrag na Blog

Povezani članci