Overenie podpisu Open Badge v Node.js, Pythone a Go

Tri funkčné ukážky kódu (Node, Python, Go) na stiahnutie podpísaného poverenia Open Badge, nájdenie verejného kľúča vydavateľa a overenie podpisu JWS.

Nacho Coll Od Aktualizované 8 min čítania
Tri funkčné ukážky kódu (Node, Python, Go) na stiahnutie podpísaného poverenia Open Badge, nájdenie verejného kľúča vydavateľa a overenie podpisu JWS.

Ak vydávate poverenia, väčšina overovania prebehne bez vás: príjemca zdieľa odkaz, zamestnávateľ naň klikne a overovacia stránka urobí zvyšok. Skôr či neskôr sa však niekto opýta ostrejšie: „Ako viem, že tento súbor naozaj podpísali vy a že ho niekto dodatočne neupravil?“ Odpoveď dáva digitálny podpis a jeho kontrola zaberie približne pätnásť riadkov kódu v ktoromkoľvek bežnom jazyku.

Tento tutoriál krok za krokom ukazuje, ako overiť podpísané poverenie Open Badges 3.0 vydané cez https://badges.ninja v Node.js, Pythone a Go. Nič z toho nemusíte spúšťať, aby ste mohli vydávať poverenia. Je pre tých, ktorí chcú systém auditovať, vytvoriť interný overovací nástroj alebo jednoducho pochopiť, čo „overiteľné“ znamená v praxi.

Čo vlastne overujete

V Open Badges existujú dve vrstvy overovania a je užitočné držať ich oddelene.

Hostované overenie je model Open Badges 2.0. Udelenie má verejnú URL adresu a každý, kto ju otvorí, vidí vydavateľa, digitálny odznak, hashovanú identitu príjemcu a stav. Dôvera vychádza z toho, že dáta sa poskytujú z domény samotného vydavateľa. Ak sa dostanete na stránku na https://badges.ninja, poverenie je skutočné. Nepotrebuje to žiadny kód ani podpis.

Overenie podpisu je model Open Badges 3.0, postavený na W3C Verifiable Credentials. Poverenie je zabalené ako podpísaný token, takže ho možno skontrolovať offline, aj o roky neskôr, dokonca aj keď sa skopírovalo do peňaženky alebo e-mailovej prílohy. Dôvera vychádza z matematiky: token nesie podpis, ktorý mohol vytvoriť len držiteľ súkromného kľúča vydavateľa.

Na https://badges.ninja je každé udelenie dostupné v oboch podobách. Tento článok je o tej druhej. Ak chcete poznať pozadie rozdielov medzi verziami, prečítajte si Open Badges v2 vs v3 a prehliadku hostovaného JSON nájdete v rozbore Open Badge JSON-LD.

Pohyblivé časti

Podpísané poverenie je VC-JWT: kompaktný JWS, teda tri reťazce base64url oddelené bodkami.

header.payload.signature
  • Hlavička (header) hovorí, ako bol token podpísaný. Pri našich povereniach obsahuje alg: EdDSA, typ: JWT a kid (identifikátor kľúča), ktorý vyzerá ako did:web:api.badges.ninja#<thumbprint>.
  • Obsah (payload) nesie tvrdenia vrátane iss (DID vydavateľa did:web:api.badges.ninja), jti (identifikátor poverenia), nbf (platné od), voliteľného exp (expirácia) a objektu vc so samotným OpenBadgeCredential.
  • Podpis je podpis Ed25519 nad presnými bajtmi header.payload.

Verejný kľúč, ktorým sa podpis overuje, vydavateľ zverejňuje na dvoch miestach, oboje bez autentifikácie:

  • https://api.badges.ninja/.well-known/jwks.json vracia JWK Set.
  • https://api.badges.ninja/.well-known/did.json vracia dokument DID pre did:web:api.badges.ninja.

kid v JWKS je thumbprint kľúča podľa RFC 7638. kid v hlavičke tokenu je DID URL a jeho fragment (časť za #) je ten istý thumbprint. Práve podľa tohto fragmentu vyberiete správny kľúč.

Postup overenia

Každý jazyk sleduje rovnakých päť krokov:

  1. Stiahnite podpísané poverenie z verejného koncového bodu.
  2. Rozdeľte token na tri časti.
  3. Prečítajte hlavičku, skontrolujte, že alg je presne EdDSA, a z kid vezmite thumbprint.
  4. Stiahnite JWKS a nájdite kľúč so zhodným kid.
  5. Týmto kľúčom overte podpis Ed25519 nad header.payload.

Koncový bod poverenia je verejný a prijíma identifikátor udelenia (rovnaký GUID, aký vidíte v overovacej URL, napríklad https://badges.ninja/awards/<awardId>):

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

Predvolene vracia podpísaný VC-JWT ako application/jwt. Pridaním ?format=json získate nepodpísané JSON poverenia na čítanie. Referencia overovania dokumentuje obe možnosti.

Všimnite si, že neexistuje samostatný koncový bod „over to za mňa“, a to zámerne. Server, ktorý vám povie „áno, platné“, od vás žiada, aby ste mu verili. Celý zmysel podpisu je v tom, že ho môžete sami skontrolovať voči zverejnenému kľúču.

Node.js

Vstavaný modul crypto v Node podporuje Ed25519 a import JWK, takže nepotrebujete žiadne závislosti.

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 null pre algoritmus je správny: pri Ed25519 algoritmus určuje typ kľúča. Ak uprednostňujete knižnicu, jose robí rovnakú prácu cez compactVerify a importJWK a kontroly hlavičky rieši za vás.

Python

Balík cryptography vám dáva Ed25519 priamo. Nainštalujte ho cez 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 tejto knižnici nemá import JWK pre Ed25519, takže súradnicu x (surový 32-bajtový verejný kľúč) dekódujeme sami. To je všetko, čo JWK typu OKP s krivkou Ed25519 obsahuje.

Go

Štandardná knižnica Go pokrýva všetko vrátane 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)
}

Spustite ho cez go run main.go <awardId>. Spracovanie chýb je kvôli čitateľnosti skrátené; v reálnom nástroji by ste kontrolovali každé dekódovanie.

Časté chyby a ako ich čítať

Kľúč sa v JWKS nenašiel. Porovnali ste celý kid z hlavičky tokenu (did:web:api.badges.ninja#abc) s kid z JWKS (abc). Porovnávajte len fragment za #. Ak sa ani fragment nezhoduje, vydavateľ mohol od vytvorenia tokenu rotovať kľúče; stiahnite dokument DID a pozrite si záznamy verificationMethod.

Neplatný podpis na práve stiahnutom tokene. Skontrolujte, či ste overovali header.payload ako pôvodný text base64url, a nie znovu zakódovaný JSON. Opätovná serializácia JSON zmení bajty a podpis sa pokazí. Skontrolujte aj prípadný znak nového riadka na konci stiahnutého tokenu.

Zámena algoritmu. Klasický útok na JWT je token, ktorý tvrdí alg: none alebo prepne na symetrický algoritmus, aby sa overovač nechal oklamať a prijal ho. Naše ukážky sa mu vyhýbajú pevne zadaným očakávaným algoritmom EdDSA a odmietnutím všetkého ostatného. Nikdy nenechajte token, aby si vyberal, ako sa bude overovať.

Chyby base64 paddingu. JWS používa base64url bez paddingu. Python vyžaduje padding doplniť späť (ukázané vyššie) a Go potrebuje RawURLEncoding, nie URLEncoding.

Podpis platí, ale je poverenie stále dobré? Podpis dokazuje pravosť a integritu, nie aktuálny stav. Poverenie môže byť správne podpísané a pritom odvolané alebo expirované. Skontrolujte exp v payloade a stav odvolania, ktorý popisuje nasledujúca časť.

Nezabudnite na odvolanie

Každé poverenie Open Badges 3.0 z https://badges.ninja obsahuje záznam credentialStatus, ktorý sleduje W3C Bitstring Status List. Ukazuje na poverenie so zoznamom stavov, ktoré môžete stiahnuť na /certify-badge/status/<listId>. Keď vydavateľ odvolá udelenie, v tomto zozname sa prepne jeden bit; zoznam sa kešuje približne minútu, takže odvolania sa k overovačom dostanú rýchlo. Dekódujte zoznam a prečítajte bit na statusListIndex poverenia: 1 znamená odvolané, 0 znamená aktívne. Referencia overovania obsahuje krátku ukážku v Node pre túto kontrolu bitu.

Úplný overovač robí tri veci: overí podpis, skontroluje expiráciu a skontroluje bit odvolania. Ak chcete vidieť, ako odvolanie vyzerá z pohľadu vydavateľa, akcia v dashboarde je popísaná v príručke k udeleniam.

Kedy nič z toho nepotrebujete

Väčšina správcov programov tento kód nikdy nenapíše a je to v poriadku. Na bežné kontroly otvorte verejnú stránku udelenia na https://badges.ninja/awards/<awardId> a prečítajte si ju. Stránka nevyžaduje registráciu ani kľúč a zobrazuje vydavateľa, digitálny odznak a stav. Príjemcovia si môžu Verifiable Credential stiahnuť aj z ponuky Download na verejnej stránke svojho poverenia a importovať ho do ľubovoľnej peňaženky Open Badges 3.0.

Kontrola podpisu sa stáva hodnotnou, keď:

  • zamestnávateľ alebo univerzita chce automatizovať kontrolu prijatých poverení;
  • budujete evidenčný systém, ktorý ukladá kópie poverení a musí dokázať, že sa nezmenili;
  • audítor žiada dôkaz, že vaše poverenia sú nezávisle overiteľné, a nie len „dôverujte našej webstránke“.

Nastavenie API kľúča používané na vydávanie tu nepotrebujete, pretože všetky tieto koncové body sú verejné. Ak chcete poverenia vydávať z kódu, API quickstart vás prevedie vytvorením kľúča a prvým udelením.

API Keys — empty state

Rýchly prehľad

PoložkaHodnota
Podpísané poverenieGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Nepodpísaný JSON na čítanierovnaká URL s ?format=json
DID vydavateľadid:web:api.badges.ninja
Verejné kľúče/.well-known/jwks.json a /.well-known/did.json
AlgoritmusEd25519 (EdDSA)
Zhoda kľúčafragment kid v hlavičke sa rovná kid v JWKS
OdvolaniecredentialStatus ukazujúci na /certify-badge/status/<listId>

Zhrnutie

Overenie podpisu Open Badge je krátka, mechanická rutina: stiahnete token, zafixujete algoritmus, nájdete kľúč podľa thumbprintu a overíte podpis Ed25519 nad prvými dvoma segmentmi. Pridajte kontrolu expirácie a odvolania a máte overovač, ktorý nedôveruje nikomu okrem zverejneného kľúča vydavateľa. Práve táto nezávislosť robí z digitálneho poverenia viac než len PDF.

Ste pripravení vydať svoje prvé overiteľné poverenie? Začnite zadarmo vo badges.ninja — vizuálny dizajnér, verejná overovacia stránka, PDF certifikát, výstup Open Badge v2.0. Bez kreditnej karty.

Nacho Coll

O autorovi

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.

Späť na blog

Súvisiace články