Verificare la firma di un Open Badge in Node.js, Python e Go

Tre esempi di codice funzionanti (Node, Python, Go) per recuperare una credenziale Open Badge firmata, risolvere la chiave pubblica dell'emittente e verificare la firma JWS.

Nacho Coll Di Aggiornato 10 min di lettura
Tre esempi di codice funzionanti (Node, Python, Go) per recuperare una credenziale Open Badge firmata, risolvere la chiave pubblica dell'emittente e verificare la firma JWS.

Se emetti credenziali, la maggior parte del lavoro di verifica avviene senza di te: un destinatario condivide un link, un datore di lavoro ci clicca e la pagina di verifica fa il resto. Prima o poi, però, qualcuno farà una domanda più incisiva. «Come faccio a sapere che questo file è stato davvero firmato da te e non modificato in seguito?» A rispondere è una firma digitale, e controllarne una richiede circa quindici righe di codice in qualsiasi linguaggio diffuso.

Questo tutorial mostra, passo dopo passo, come verificare una credenziale Open Badges 3.0 firmata ed emessa tramite https://badges.ninja, in Node.js, Python e Go. Non serve eseguire nulla di tutto ciò per emettere credenziali. È per chi vuole fare un audit del sistema, costruire uno strumento di verifica interno o semplicemente capire cosa significhi «verificabile» in pratica.

Cosa stai davvero verificando

In Open Badges esistono due livelli di verifica ed è utile tenerli separati.

La verifica ospitata è il modello di Open Badges 2.0. L’assegnazione ha un URL pubblico e chiunque lo apra vede l’emittente, il badge, l’identità con hash del destinatario e lo stato. La fiducia deriva dal fatto che i dati vengono serviti dal dominio dell’emittente stesso. Se riesci a raggiungere la pagina su https://badges.ninja, la credenziale è autentica. Non servono codice né firma.

La verifica della firma è il modello di Open Badges 3.0, basato sulle Verifiable Credentials del W3C. La credenziale è impacchettata come token firmato, quindi può essere controllata offline, anni dopo, anche se è stata copiata in un wallet o in un allegato email. La fiducia deriva dalla matematica: il token contiene una firma che solo chi possiede la chiave privata dell’emittente poteva produrre.

Su https://badges.ninja ogni assegnazione è disponibile in entrambe le forme. Questo articolo parla della seconda. Per capire le differenze tra le due versioni leggi Open Badges v2 vs v3; per una panoramica del JSON ospitato, vedi la guida al JSON-LD di Open Badge.

Gli ingranaggi

La credenziale firmata è un VC-JWT: un JWS compatto, ovvero tre stringhe base64url separate da punti.

header.payload.signature
  • L’header indica come è stato firmato. Per le nostre credenziali contiene alg: EdDSA, typ: JWT e un kid (key id) simile a did:web:api.badges.ninja#<thumbprint>.
  • Il payload contiene le dichiarazioni (claim), tra cui iss (il DID dell’emittente did:web:api.badges.ninja), jti (l’id della credenziale), nbf (valida da), un exp facoltativo (scadenza) e un oggetto vc con l’OpenBadgeCredential vera e propria.
  • La firma è una firma Ed25519 calcolata sui byte esatti di header.payload.

La chiave pubblica che controlla la firma è pubblicata dall’emittente in due punti, entrambi senza autenticazione:

  • https://api.badges.ninja/.well-known/jwks.json restituisce un JWK Set.
  • https://api.badges.ninja/.well-known/did.json restituisce il documento DID per did:web:api.badges.ninja.

Il kid del JWKS è il thumbprint RFC 7638 della chiave. Il kid nell’header del token è l’URL DID e il suo frammento (la parte dopo #) è lo stesso thumbprint. Quel frammento è ciò che ti permette di scegliere la chiave giusta.

La ricetta di verifica

Ogni linguaggio segue gli stessi cinque passaggi:

  1. Recupera la credenziale firmata dall’endpoint pubblico.
  2. Dividi il token nelle sue tre parti.
  3. Leggi l’header, controlla che alg sia esattamente EdDSA e prendi il thumbprint da kid.
  4. Recupera il JWKS e trova la chiave il cui kid corrisponde.
  5. Verifica la firma Ed25519 su header.payload con quella chiave.

L’endpoint della credenziale è pubblico e accetta l’id dell’assegnazione (lo stesso GUID che vedi in un URL di verifica come https://badges.ninja/awards/<awardId>):

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

Per impostazione predefinita restituisce il VC-JWT firmato come application/jwt. Aggiungi ?format=json per ottenere il JSON non firmato della credenziale, da leggere. Il riferimento sulla verifica documenta entrambi.

Nota che non esiste un endpoint separato «verificalo per me», ed è voluto. Un server che ti dice «sì, valido» ti chiede di fidarti del server. Il senso di una firma è proprio poterla controllare da solo con una chiave pubblicata.

Node.js

Il modulo integrato crypto di Node supporta Ed25519 e l’importazione JWK, quindi non servono dipendenze.

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

L’argomento null per l’algoritmo è corretto: con Ed25519 è il tipo di chiave a fissare l’algoritmo. Se preferisci una libreria, jose fa lo stesso lavoro con compactVerify e importJWK e gestisce per te i controlli sull’header.

Python

Il pacchetto cryptography ti dà Ed25519 direttamente. Installalo con 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"])

In questa libreria Python non ha un’importazione JWK per Ed25519, quindi decodifichiamo noi la coordinata x (la chiave pubblica grezza di 32 byte). È tutto ciò che contiene un JWK di tipo OKP con curva Ed25519.

Go

La libreria standard di Go copre tutto, incluso 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)
}

Eseguilo con go run main.go <awardId>. La gestione degli errori è ridotta per leggibilità; in uno strumento reale controlleresti ogni decodifica.

Errori comuni e come interpretarli

La chiave non si trova nel JWKS. Hai confrontato il kid completo dell’header del token (did:web:api.badges.ninja#abc) con il kid del JWKS (abc). Confronta solo il frammento dopo #. Se il frammento continua a non corrispondere, l’emittente potrebbe aver ruotato le chiavi dopo la creazione del token: recupera il documento DID e guarda le voci di verificationMethod.

Firma non valida su un token appena scaricato. Controlla di aver verificato header.payload come testo base64url originale, non come JSON ricodificato. Riserializzare il JSON cambia i byte e rompe la firma. Controlla anche che non ci sia un a capo finale nel token scaricato.

Confusione sull’algoritmo. Il classico attacco JWT è un token che dichiara alg: none o passa a un algoritmo simmetrico per ingannare un verificatore e fargli accettare il token. I nostri esempi lo evitano fissando nel codice l’algoritmo atteso, EdDSA, e rifiutando tutto il resto. Non lasciare mai che sia il token a scegliere come viene verificato.

Errori di padding base64. Il JWS usa base64url senza padding. Python richiede di riaggiungere il padding (mostrato sopra), e Go richiede RawURLEncoding, non URLEncoding.

Firma valida, ma la credenziale è ancora buona? Una firma prova autenticità e integrità, non lo stato attuale. Una credenziale può essere firmata correttamente ed essere comunque revocata o scaduta. Controlla exp nel payload e controlla lo stato di revoca descritto di seguito.

Non dimenticare la revoca

Ogni credenziale Open Badges 3.0 di https://badges.ninja include una voce credentialStatus conforme alla W3C Bitstring Status List. Punta a una credenziale di lista di stato che puoi recuperare da /certify-badge/status/<listId>. Quando un emittente revoca un’assegnazione, in quella lista si inverte un bit; la lista resta in cache per circa un minuto, quindi le revoche raggiungono rapidamente i verificatori. Decodifica la lista e leggi il bit in corrispondenza di statusListIndex della credenziale: 1 significa revocata, 0 significa attiva. Il riferimento sulla verifica include un breve esempio in Node di questo controllo del bit.

Un verificatore completo fa tre cose: verifica la firma, controlla la scadenza e controlla il bit di revoca. Se vuoi vedere come appare la revoca dal lato dell’emittente, l’azione nella dashboard è descritta nella guida alle assegnazioni.

Quando non ti serve nulla di tutto questo

La maggior parte dei responsabili di programma non scriverà mai questo codice, e va bene così. Per i controlli quotidiani, apri la pagina pubblica dell’assegnazione su https://badges.ninja/awards/<awardId> e leggila. La pagina non richiede registrazione né chiave e mostra emittente, badge e stato. I destinatari possono anche scaricare la Verifiable Credential dal menu Download della loro pagina pubblica della credenziale e importarla in qualsiasi wallet Open Badges 3.0.

La verifica della firma diventa preziosa quando:

  • un datore di lavoro o un’università vuole automatizzare i controlli sulle credenziali che riceve;
  • stai costruendo un sistema di registrazione che conserva copie delle credenziali e deve dimostrare che non sono state alterate;
  • un auditor chiede la prova che le tue credenziali siano verificabili in modo indipendente, non solo «fidatevi del nostro sito».

Qui non serve la stessa configurazione della chiave API usata per l’emissione, perché tutti questi endpoint sono pubblici. Se invece vuoi emettere credenziali da codice, la guida rapida all’API ti accompagna nella creazione di una chiave e della tua prima assegnazione.

API Keys — empty state

Riferimento rapido

ElementoValore
Credenziale firmataGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
JSON non firmato da leggerestesso URL con ?format=json
DID dell’emittentedid:web:api.badges.ninja
Chiavi pubbliche/.well-known/jwks.json e /.well-known/did.json
AlgoritmoEd25519 (EdDSA)
Corrispondenza della chiaveil frammento del kid dell’header è uguale al kid del JWKS
RevocacredentialStatus che punta a /certify-badge/status/<listId>

Per concludere

Verificare la firma di un Open Badge è una routine breve e meccanica: recupera il token, fissa l’algoritmo, trova la chiave tramite thumbprint e controlla la firma Ed25519 sui primi due segmenti. Aggiungi i controlli di scadenza e revoca e avrai un verificatore che non si fida di nessuno tranne che della chiave pubblicata dall’emittente. È proprio questa indipendenza a rendere una credenziale digitale più preziosa di un PDF.

Pronto a emettere la tua prima credenziale verificabile? Inizia gratis su badges.ninja — designer visuale, pagina di verifica pubblica, certificato PDF, output Open Badge v2.0. Nessuna carta di credito richiesta.

Nacho Coll

Informazioni sull'autore

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.

Torna al Blog

Articoli correlati