Open Badge paraksta verifikācija Node.js, Python un Go

Trīs strādājoši koda piemēri (Node, Python, Go), kā iegūt parakstītu Open Badge akreditācijas datu objektu, atrast izdevēja publisko atslēgu un pārbaudīt JWS parakstu.

Nacho Coll Autors Atjaunināts 8 min lasīšanai
Trīs strādājoši koda piemēri (Node, Python, Go), kā iegūt parakstītu Open Badge akreditācijas datu objektu, atrast izdevēja publisko atslēgu un pārbaudīt JWS parakstu.

Ja jūs izsniedzat akreditācijas datus, lielākā daļa verifikācijas notiek bez jums: saņēmējs kopīgo saiti, darba devējs uz tās noklikšķina, un verifikācijas lapa paveic pārējo. Taču agri vai vēlu kāds uzdod asāku jautājumu: „Kā es zinu, ka šo failu patiešām parakstījāt jūs un tas pēc tam nav mainīts?” Uz to atbild digitālais paraksts, un tā pārbaude jebkurā izplatītā valodā aizņem apmēram piecpadsmit koda rindas.

Šī pamācība soli pa solim parāda, kā Node.js, Python un Go verificēt parakstītu Open Badges 3.0 akreditācijas datu objektu, kas izsniegts, izmantojot https://badges.ninja. Lai izsniegtu akreditācijas datus, nekas no tā nav jāpalaiž. Tā paredzēta tiem, kas vēlas auditēt sistēmu, izveidot iekšēju verifikācijas rīku vai vienkārši saprast, ko praksē nozīmē „verificējams”.

Ko jūs patiesībā verificējat

Open Badges ir divi verifikācijas slāņi, un tos ir lietderīgi nošķirt.

Hostētā verifikācija ir Open Badges 2.0 modelis. Apbalvojumam ir publisks URL, un ikviens, kas to atver, redz izdevēju, nozīmīti, saņēmēja jaukto identitāti un statusu. Uzticēšanās izriet no tā, ka dati tiek pasniegti no paša izdevēja domēna. Ja lapu varat atvērt vietnē https://badges.ninja, akreditācijas dati ir īsti. Tam nav vajadzīgs ne kods, ne paraksts.

Paraksta verifikācija ir Open Badges 3.0 modelis, kas balstīts uz W3C Verifiable Credentials. Akreditācijas dati ir iepakoti kā parakstīts tokens, tāpēc tos var pārbaudīt bezsaistē, pēc daudziem gadiem, pat ja tie ir nokopēti makā vai e-pasta pielikumā. Uzticēšanās izriet no matemātikas: tokenam ir paraksts, ko varēja izveidot tikai izdevēja privātās atslēgas īpašnieks.

Platformā https://badges.ninja katrs apbalvojums ir pieejams abās formās. Šis raksts ir par otro. Lai uzzinātu fonu par abu versiju atšķirībām, izlasiet Open Badges v2 vs v3, bet hostētā JSON apskatam skatiet Open Badge JSON-LD pārskatu.

Kustīgās daļas

Parakstītais akreditācijas datu objekts ir VC-JWT: kompakts JWS, kas ir trīs base64url virknes, atdalītas ar punktiem.

header.payload.signature
  • Galvene norāda, kā tika parakstīts. Mūsu akreditācijas datiem tā satur alg: EdDSA, typ: JWT un kid (atslēgas ID), kas izskatās kā did:web:api.badges.ninja#<thumbprint>.
  • Saturs (payload) ietver apgalvojumus, tostarp iss (izdevēja DID did:web:api.badges.ninja), jti (akreditācijas datu ID), nbf (derīgs no), neobligāto exp (beigu termiņš) un objektu vc ar faktisko OpenBadgeCredential.
  • Paraksts ir Ed25519 paraksts virs precīziem header.payload baitiem.

Publisko atslēgu, ar kuru pārbauda parakstu, izdevējs publicē divās vietās, abas bez autentifikācijas:

  • https://api.badges.ninja/.well-known/jwks.json atgriež JWK kopu.
  • https://api.badges.ninja/.well-known/did.json atgriež did:web:api.badges.ninja DID dokumentu.

JWKS kid ir atslēgas RFC 7638 pirkstu nospiedums. kid tokena galvenē ir DID URL, un tā fragments (daļa pēc #) ir tas pats pirkstu nospiedums. Ar šo fragmentu jūs izvēlaties pareizo atslēgu.

Verifikācijas recepte

Visās valodās tiek ievēroti vieni un tie paši pieci soļi:

  1. Iegūstiet parakstītos akreditācijas datus no publiskā gala punkta.
  2. Sadaliet tokenu trīs daļās.
  3. Izlasiet galveni, pārbaudiet, ka alg ir tieši EdDSA, un no kid paņemiet pirkstu nospiedumu.
  4. Iegūstiet JWKS un atrodiet atslēgu, kuras kid sakrīt.
  5. Ar šo atslēgu pārbaudiet Ed25519 parakstu virs header.payload.

Akreditācijas datu gala punkts ir publisks un pieņem apbalvojuma ID (to pašu GUID, ko redzat verifikācijas URL, piemēram, https://badges.ninja/awards/<awardId>):

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

Pēc noklusējuma tas atgriež parakstītu VC-JWT kā application/jwt. Pievienojiet ?format=json, lai lasīšanai iegūtu neparakstīto akreditācijas datu JSON. Abus apraksta verifikācijas atsauce.

Ņemiet vērā, ka atsevišķa gala punkta „pārbaudi to manā vietā” nav, un tas ir apzināti. Serveris, kas jums saka „jā, derīgs”, prasa uzticēties serverim. Paraksta jēga ir tieši tajā, ka jūs paši varat to pārbaudīt ar publicētu atslēgu.

Node.js

Node iebūvētais modulis crypto atbalsta Ed25519 un JWK importu, tāpēc atkarības nav vajadzīgas.

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

Algoritma arguments null ir pareizs: Ed25519 gadījumā algoritmu nosaka atslēgas veids. Ja vēlaties bibliotēku, jose paveic to pašu ar compactVerify un importJWK un galvenes pārbaudes veic jūsu vietā.

Python

Pakotne cryptography nodrošina Ed25519 tieši. Instalējiet to ar 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 šajā bibliotēkā nav JWK importa Ed25519 atslēgām, tāpēc x koordinātu (neapstrādāto 32 baitu publisko atslēgu) mēs atkodējam paši. Tas ir viss, ko satur OKP tipa JWK ar līkni Ed25519.

Go

Go standartbibliotēka aptver visu, tostarp 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)
}

Palaidiet to ar go run main.go <awardId>. Kļūdu apstrāde ir saīsināta lasāmības labad; īstā rīkā jūs pārbaudītu katru atkodēšanu.

Biežākās kļūdas un kā tās lasīt

Atslēga JWKS nav atrasta. Jūs salīdzinājāt pilno kid no tokena galvenes (did:web:api.badges.ninja#abc) ar JWKS kid (abc). Salīdziniet tikai fragmentu pēc #. Ja fragments joprojām nesakrīt, izdevējs, iespējams, ir mainījis atslēgas kopš tokena izveides; iegūstiet DID dokumentu un apskatiet verificationMethod ierakstus.

Paraksts nederīgs tikko lejupielādētam tokenam. Pārbaudiet, vai verificējāt header.payload kā oriģinālo base64url tekstu, nevis no jauna kodētu JSON. JSON atkārtota serializācija maina baitus un salauž parakstu. Pārbaudiet arī, vai lejupielādētā tokena beigās nav jaunas rindas rakstzīmes.

Algoritma sajaukšana. Klasisks JWT uzbrukums ir tokens, kas apgalvo alg: none vai pārslēdzas uz simetrisku algoritmu, lai pievilktu verificētāju to pieņemt. Mūsu piemēri no tā izvairās, cieši fiksējot gaidāmo algoritmu EdDSA un noraidot visu pārējo. Nekad neļaujiet tokenam pašam izvēlēties, kā to verificēt.

Base64 aizpildījuma kļūdas. JWS izmanto base64url bez aizpildījuma. Python nepieciešams aizpildījumu pievienot atpakaļ (parādīts iepriekš), bet Go vajag RawURLEncoding, nevis URLEncoding.

Paraksts derīgs, bet vai akreditācijas dati joprojām ir derīgi? Paraksts apliecina autentiskumu un integritāti, nevis pašreizējo statusu. Akreditācijas dati var būt pareizi parakstīti un tomēr atsaukti vai beigušies. Pārbaudiet exp saturā un tālāk aprakstīto atsaukšanas bitu.

Neaizmirstiet par atsaukšanu

Katrs Open Badges 3.0 akreditācijas datu objekts no https://badges.ninja satur credentialStatus ierakstu, kas atbilst W3C Bitstring Status List. Tas norāda uz statusa saraksta akreditācijas datiem, ko varat iegūt adresē /certify-badge/status/<listId>. Kad izdevējs atsauc apbalvojumu, sarakstā tiek apgriezts bits; saraksts tiek kešots apmēram minūti, tāpēc atsaukumi verificētājus sasniedz ātri. Atkodējiet sarakstu un nolasiet bitu pie akreditācijas datu statusListIndex: 1 nozīmē atsaukts, 0 aktīvs. Verifikācijas atsaucē ir īss Node piemērs šai bita pārbaudei.

Pilnīgs verificētājs dara trīs lietas: pārbauda parakstu, pārbauda derīguma termiņu un pārbauda atsaukšanas bitu. Ja vēlaties redzēt, kā atsaukšana izskatās no izdevēja puses, informācijas paneļa darbība ir aprakstīta apbalvojumu ceļvedī.

Kad jums no tā nekā nav vajadzīgs

Lielākā daļa programmu īpašnieku šo kodu nekad nerakstīs, un tas ir pilnīgi normāli. Ikdienas pārbaudēm atveriet apbalvojuma publisko lapu adresē https://badges.ninja/awards/<awardId> un izlasiet to. Lapai nav vajadzīga reģistrācija vai atslēga, un tā rāda izdevēju, nozīmīti un statusu. Saņēmēji Verifiable Credential var lejupielādēt arī no izvēlnes Download savā publiskajā akreditācijas datu lapā un importēt jebkurā Open Badges 3.0 makā.

Paraksta pārbaude kļūst vērtīga, kad:

  • darba devējs vai universitāte vēlas automatizēt saņemto akreditācijas datu pārbaudi;
  • jūs veidojat ierakstu sistēmu, kas glabā akreditācijas datu kopijas un kurai jāpierāda, ka tās nav mainītas;
  • revidents pieprasa pierādījumu, ka jūsu akreditācijas dati ir neatkarīgi verificējami, nevis tikai „uzticieties mūsu vietnei”.

Tā pati API atslēgas iestatīšana, ko izmanto izsniegšanai, šeit nav vajadzīga, jo visi šie gala punkti ir publiski. Ja vēlaties izsniegt akreditācijas datus no koda, API ātrā sākuma ceļvedis jūs vedīs cauri atslēgas izveidei un pirmajam apbalvojumam.

API Keys — empty state

Ātrā atsauce

VienumsVērtība
Parakstīti akreditācijas datiGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Neparakstīts JSON lasīšanaitas pats URL ar ?format=json
Izdevēja DIDdid:web:api.badges.ninja
Publiskās atslēgas/.well-known/jwks.json un /.well-known/did.json
AlgoritmsEd25519 (EdDSA)
Atslēgas sakritībagalvenes kid fragments vienāds ar JWKS kid
AtsaukšanacredentialStatus, kas norāda uz /certify-badge/status/<listId>

Nobeigumā

Open Badge paraksta verifikācija ir īsa, mehāniska rutīna: iegūstiet tokenu, nofiksējiet algoritmu, atrodiet atslēgu pēc pirkstu nospieduma un pārbaudiet Ed25519 parakstu virs pirmajiem diviem segmentiem. Pievienojiet derīguma termiņa un atsaukšanas pārbaudes, un jums ir verificētājs, kas neuzticas nevienam, izņemot izdevēja publicēto atslēgu. Tieši šī neatkarība padara digitālos akreditācijas datus vērtīgākus par PDF.

Gatavi izsniegt savus pirmos verificējamos akreditācijas datus? Sāciet bez maksas platformā badges.ninja — vizuālais dizainers, publiska verifikācijas lapa, PDF sertifikāts, Open Badge v2.0 izvade. Kredītkarte nav nepieciešama.

Nacho Coll

Par 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.

Atpakaļ uz Blogu

Saistītie raksti