Verificarea semnăturii unui Open Badge în Node.js, Python și Go

Trei exemple de cod funcționale (Node, Python, Go) pentru a descărca o credențială Open Badge semnată, a găsi cheia publică a emitentului și a verifica semnătura JWS.

Nacho Coll De Actualizat 9 min de citit
Trei exemple de cod funcționale (Node, Python, Go) pentru a descărca o credențială Open Badge semnată, a găsi cheia publică a emitentului și a verifica semnătura JWS.

Dacă emiți credențiale, cea mai mare parte a verificării se face fără tine: un destinatar distribuie un link, un angajator dă clic pe el, iar pagina de verificare face restul. Dar mai devreme sau mai târziu cineva pune o întrebare mai incisivă: „De unde știu că acest fișier chiar a fost semnat de tine și nu a fost modificat ulterior?” La această întrebare răspunde o semnătură digitală, iar verificarea ei înseamnă cam cincisprezece linii de cod în orice limbaj popular.

Acest tutorial îți arată, pas cu pas, cum să verifici o credențială Open Badges 3.0 semnată, emisă prin https://badges.ninja, în Node.js, Python și Go. Nu ai nevoie de nimic din asta ca să emiți credențiale. E pentru cei care vor să audieze sistemul, să construiască un instrument intern de verificare sau pur și simplu să înțeleagă ce înseamnă „verificabil” în practică.

Ce verifici de fapt

În Open Badges există două niveluri de verificare și e util să le ții separate.

Verificarea găzduită este modelul Open Badges 2.0. Acordarea are o adresă publică, iar oricine o deschide vede emitentul, insigna, identitatea hash-uită a destinatarului și starea. Încrederea vine din faptul că datele sunt servite de pe domeniul emitentului. Dacă poți ajunge la pagina de pe https://badges.ninja, credențiala este reală. Nu cere cod și nici semnătură.

Verificarea semnăturii este modelul Open Badges 3.0, construit pe W3C Verifiable Credentials. Credențiala este împachetată ca un token semnat, deci poate fi verificată offline, chiar și peste ani, chiar dacă a fost copiată într-un portofel digital sau atașată la un e-mail. Încrederea vine din matematică: tokenul poartă o semnătură pe care doar deținătorul cheii private a emitentului a putut-o produce.

Pe https://badges.ninja, fiecare acordare este disponibilă în ambele forme. Acest articol îl privește pe al doilea. Dacă vrei contextul diferențelor dintre cele două versiuni, citește Open Badges v2 vs v3, iar pentru o prezentare a JSON-ului găzduit, vezi ghidul JSON-LD pentru Open Badge.

Piesele componente

Credențiala semnată este un VC-JWT: un JWS compact, adică trei șiruri base64url separate prin puncte.

header.payload.signature
  • Header-ul spune cum a fost semnat. Pentru credențialele noastre conține alg: EdDSA, typ: JWT și un kid (identificatorul cheii) de forma did:web:api.badges.ninja#<thumbprint>.
  • Payload-ul conține revendicările (claims), inclusiv iss (DID-ul emitentului did:web:api.badges.ninja), jti (identificatorul credențialei), nbf (valabilă de la), un exp opțional (expirarea) și un obiect vc cu OpenBadgeCredential propriu-zis.
  • Semnătura este o semnătură Ed25519 peste octeții exacți ai header.payload.

Cheia publică ce verifică semnătura este publicată de emitent în două locuri, ambele fără autentificare:

  • https://api.badges.ninja/.well-known/jwks.json returnează un JWK Set.
  • https://api.badges.ninja/.well-known/did.json returnează documentul DID pentru did:web:api.badges.ninja.

kid-ul din JWKS este amprenta (thumbprint) RFC 7638 a cheii. kid-ul din header-ul tokenului este URL-ul DID, iar fragmentul lui (partea de după #) este aceeași amprentă. Acest fragment te ajută să alegi cheia potrivită.

Rețeta de verificare

Fiecare limbaj urmează aceiași cinci pași:

  1. Descarcă credențiala semnată de la endpoint-ul public.
  2. Împarte tokenul în cele trei părți.
  3. Citește header-ul, verifică dacă alg este exact EdDSA și ia amprenta din kid.
  4. Descarcă JWKS și găsește cheia al cărei kid se potrivește.
  5. Verifică semnătura Ed25519 peste header.payload cu acea cheie.

Endpoint-ul credențialei este public și primește id-ul acordării (același GUID pe care îl vezi într-un URL de verificare precum https://badges.ninja/awards/<awardId>):

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

Implicit, returnează VC-JWT-ul semnat ca application/jwt. Adaugă ?format=json ca să obții JSON-ul nesemnat al credențialei, pentru citit. Referința de verificare le documentează pe ambele.

Reține că nu există un endpoint separat „verifică asta pentru mine”, și asta e intenționat. Un server care îți spune „da, e valid” îți cere să ai încredere în server. Esența unei semnături este că o poți verifica singur, folosind o cheie publicată.

Node.js

Modulul crypto integrat în Node suportă Ed25519 și importul de JWK, deci nu ai nevoie de dependențe.

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

Argumentul null pentru algoritm este corect: la Ed25519, tipul cheii fixează algoritmul. Dacă preferi o bibliotecă, jose face aceeași treabă cu compactVerify și importJWK și se ocupă în locul tău de verificările de header.

Python

Pachetul cryptography îți oferă Ed25519 direct. Instalează-l cu 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 nu are import JWK pentru Ed25519 în această bibliotecă, așa că decodăm noi coordonata x (cheia publică brută de 32 de octeți). Atât conține un JWK de tip OKP cu curba Ed25519.

Go

Biblioteca standard Go acoperă tot, inclusiv 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)
}

Rulează-l cu go run main.go <awardId>. Tratarea erorilor este redusă pentru lizibilitate; într-un instrument real ar trebui să verifici fiecare decodare.

Erori frecvente și cum le citești

Cheia nu se găsește în JWKS. Ai comparat kid-ul complet din header-ul tokenului (did:web:api.badges.ninja#abc) cu kid-ul din JWKS (abc). Compară doar fragmentul de după #. Dacă fragmentul tot nu se potrivește, e posibil ca emitentul să fi rotit cheile după emiterea tokenului; descarcă documentul DID și uită-te la intrările verificationMethod.

Semnătură invalidă la un token tocmai descărcat. Verifică dacă ai verificat header.payload ca text base64url original, nu ca JSON recodat. Re-serializarea JSON-ului schimbă octeții și strică semnătura. Verifică și dacă tokenul descărcat are un newline la final.

Confuzia de algoritm. Atacul clasic asupra JWT este un token care declară alg: none sau trece la un algoritm simetric, păcălind verificatorul să-l accepte. Exemplele noastre îl evită fixând algoritmul așteptat, EdDSA, și refuzând orice altceva. Nu lăsa niciodată tokenul să aleagă cum este verificat.

Erori de padding base64. JWS folosește base64url fără padding. Python are nevoie ca padding-ul să fie adăugat la loc (vezi mai sus), iar Go cere RawURLEncoding, nu URLEncoding.

Semnătură validă, dar credențiala mai e bună? O semnătură dovedește autenticitatea și integritatea, nu starea curentă. O credențială poate fi semnată corect și totuși revocată sau expirată. Verifică exp în payload și verifică starea de revocare descrisă mai jos.

Nu uita de revocare

Fiecare credențială Open Badges 3.0 de pe https://badges.ninja include o intrare credentialStatus conformă cu W3C Bitstring Status List. Aceasta trimite la o credențială de tip listă de stare, pe care o poți descărca de la /certify-badge/status/<listId>. Când un emitent revocă o acordare, un bit se schimbă în acea listă; lista este păstrată în cache circa un minut, așa că revocările ajung rapid la verificatori. Decodează lista și citește bitul de la statusListIndex-ul credențialei: 1 înseamnă revocată, 0 înseamnă activă. Referința de verificare include un scurt exemplu Node pentru verificarea acestui bit.

Un verificator complet face trei lucruri: verifică semnătura, verifică expirarea și verifică bitul de revocare. Dacă vrei să vezi cum arată revocarea din partea emitentului, acțiunea din tabloul de bord este descrisă în ghidul acordărilor.

Când nu ai nevoie de nimic din toate astea

Majoritatea responsabililor de programe nu vor scrie niciodată acest cod, și e în regulă. Pentru verificările de zi cu zi, deschide pagina publică a acordării la https://badges.ninja/awards/<awardId> și citește-o. Pagina nu cere cont și nici cheie și arată emitentul, insigna și starea. Destinatarii pot descărca Verifiable Credential din meniul Download de pe pagina lor publică a credențialei și îl pot importa în orice portofel Open Badges 3.0.

Verificarea semnăturii devine valoroasă când:

  • un angajator sau o universitate vrea să automatizeze verificarea credențialelor primite;
  • construiești un sistem de evidență care stochează copii ale credențialelor și trebuie să demonstreze că nu au fost alterate;
  • un auditor cere dovezi că credențialele tale sunt verificabile independent, nu doar „aveți încredere în site-ul nostru”.

Aici nu ai nevoie de aceeași configurare de cheie API folosită la emitere, deoarece toate aceste endpoint-uri sunt publice. Dacă vrei totuși să emiți credențiale din cod, ghidul rapid API te duce prin crearea unei chei și a primei acordări.

API Keys — empty state

Referință rapidă

ElementValoare
Credențială semnatăGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
JSON nesemnat pentru cititacelași URL cu ?format=json
DID-ul emitentuluidid:web:api.badges.ninja
Chei publice/.well-known/jwks.json și /.well-known/did.json
AlgoritmEd25519 (EdDSA)
Potrivirea cheiifragmentul kid din header este egal cu kid din JWKS
RevocarecredentialStatus care trimite la /certify-badge/status/<listId>

În încheiere

Verificarea semnăturii unui Open Badge este o rutină scurtă și mecanică: descarcă tokenul, fixează algoritmul, găsește cheia după amprentă și verifică semnătura Ed25519 peste primele două segmente. Adaugă verificările de expirare și revocare și obții un verificator care nu se încrede în nimeni în afară de cheia publicată a emitentului. Tocmai această independență face o credențială digitală să valoreze mai mult decât un PDF.

Ești gata să emiți prima ta credențială verificabilă? Începe gratuit pe badges.ninja — designer vizual, pagină publică de verificare, certificat PDF, ieșire Open Badge v2.0. Fără card de credit.

Nacho Coll

Despre autor

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.

Înapoi la Blog

Articole similare