Verificar la signatura d’una Open Badge amb Node.js, Python i Go

Tres exemples de codi funcionals (Node, Python, Go) per obtenir una credencial Open Badge signada, resoldre la clau pública de l’emissor i verificar la signatura JWS.

Nacho Coll Per Actualitzat 10 min de lectura
Tres exemples de codi funcionals (Node, Python, Go) per obtenir una credencial Open Badge signada, resoldre la clau pública de l’emissor i verificar la signatura JWS.

Si emets credencials, la major part de la verificació es fa sense tu: un destinatari comparteix un enllaç, una empresa hi clica i la pàgina de verificació fa la resta. Però tard o d’hora algú et fa una pregunta més punyent. «Com sé que aquest fitxer l’has signat realment tu i que ningú l’ha editat després?» Aquesta pregunta la respon una signatura digital, i comprovar-ne una són unes quinze línies de codi en qualsevol llenguatge habitual.

Aquest tutorial t’ensenya, pas a pas, a verificar una credencial Open Badges 3.0 signada i emesa a través de https://badges.ninja, en Node.js, Python i Go. No cal que executis res d’això per emetre credencials. És per a qui vol auditar el sistema, construir una eina interna de verificació o simplement entendre què vol dir «verificable» a la pràctica.

Què verifiques realment

A Open Badges hi ha dues capes de verificació, i convé tenir-les ben separades.

La verificació allotjada és el model d’Open Badges 2.0. L’atorgament té una URL pública, i qui l’obre veu l’emissor, la insígnia, la identitat del destinatari en forma de hash i l’estat. La confiança ve del fet que les dades les serveix el domini de l’emissor. Si pots arribar a la pàgina a https://badges.ninja, la credencial és real. Això no requereix cap codi ni cap signatura.

La verificació de signatura és el model d’Open Badges 3.0, basat en les W3C Verifiable Credentials. La credencial s’empaqueta com un testimoni signat, de manera que es pot comprovar fora de línia, anys després, fins i tot si s’ha copiat a una cartera digital o a un adjunt de correu. La confiança ve de les matemàtiques: el testimoni porta una signatura que només el propietari de la clau privada de l’emissor podia haver produït.

A https://badges.ninja, cada atorgament està disponible en les dues formes. Aquest article tracta de la segona. Si vols saber en què es diferencien les dues versions, llegeix Open Badges v2 vs v3, i per fer un tomb pel JSON allotjat, mira el recorregut pel JSON-LD d’una Open Badge.

Les peces del trencaclosques

La credencial signada és un VC-JWT: un JWS compacte, és a dir, tres cadenes base64url separades per punts.

header.payload.signature
  • La capçalera diu com s’ha signat. Per a les nostres credencials conté alg: EdDSA, typ: JWT i un kid (identificador de clau) com ara did:web:api.badges.ninja#<thumbprint>.
  • La càrrega útil conté les declaracions, incloent-hi iss (el DID de l’emissor did:web:api.badges.ninja), jti (l’identificador de la credencial), nbf (vàlida des de), un exp opcional (caducitat) i un objecte vc amb l’OpenBadgeCredential pròpiament dita.
  • La signatura és una signatura Ed25519 sobre els bytes exactes de header.payload.

La clau pública que comprova la signatura l’emissor la publica en dos llocs, tots dos sense autenticació:

  • https://api.badges.ninja/.well-known/jwks.json retorna un JWK Set.
  • https://api.badges.ninja/.well-known/did.json retorna el document DID de did:web:api.badges.ninja.

El kid del JWKS és l’empremta RFC 7638 de la clau. El kid de la capçalera del testimoni és la URL DID, i el seu fragment (la part després de #) és aquesta mateixa empremta. Aquest fragment és el que et permet triar la clau correcta.

La recepta de verificació

Tots els llenguatges segueixen els mateixos cinc passos:

  1. Obtén la credencial signada de l’endpoint públic.
  2. Divideix el testimoni en les seves tres parts.
  3. Llegeix la capçalera, comprova que alg sigui exactament EdDSA i agafa l’empremta de kid.
  4. Obtén el JWKS i troba la clau amb el kid coincident.
  5. Verifica la signatura Ed25519 sobre header.payload amb aquesta clau.

L’endpoint de la credencial és públic i accepta l’identificador de l’atorgament (el mateix GUID que veus en una URL de verificació com https://badges.ninja/awards/<awardId>):

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

Per defecte, retorna el VC-JWT signat com a application/jwt. Afegeix ?format=json per obtenir el JSON de la credencial sense signar, per llegir-lo. La referència de verificació documenta totes dues opcions.

Fixa-t’hi que no hi ha cap endpoint apart de «verifica-m’ho», i és deliberat. Un servidor que et diu «sí, és vàlid» et demana que et refiïs del servidor. Tot el sentit d’una signatura és que ho puguis comprovar tu mateix amb una clau publicada.

Node.js

El mòdul crypto integrat a Node admet Ed25519 i la importació de JWK, així que no necessites cap dependència.

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’argument d’algorisme null és correcte: amb Ed25519 el tipus de clau ja fixa l’algorisme. Si prefereixes una biblioteca, jose fa la mateixa feina amb compactVerify i importJWK, i s’encarrega de les comprovacions de la capçalera.

Python

El paquet cryptography t’ofereix Ed25519 directament. Instal·la’l amb 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 no té importació de JWK per a Ed25519 en aquesta biblioteca, així que descodifiquem nosaltres mateixos la coordenada x (els 32 bytes en brut de la clau pública). Això és tot el que conté un JWK de tipus OKP amb corba Ed25519.

Go

La biblioteca estàndard de Go ho cobreix tot, incloent-hi 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)
}

Executa-ho amb go run main.go <awardId>. La gestió d’errors s’ha retallat per llegibilitat; en una eina real hauries de comprovar cada descodificació.

Errors habituals i com interpretar-los

La clau no es troba al JWKS. Has comparat el kid complet de la capçalera del testimoni (did:web:api.badges.ninja#abc) amb el kid del JWKS (abc). Compara només el fragment després de #. Si el fragment tampoc no coincideix, potser l’emissor ha rotat les claus des que es va generar el testimoni; obtén el document DID i mira les entrades de verificationMethod.

Signatura invàlida en un testimoni que acabes de descarregar. Comprova que has verificat header.payload com el text base64url original, no com un JSON recodificat. Tornar a serialitzar el JSON canvia els bytes i trenca la signatura. Comprova també que el testimoni descarregat no acabi amb un salt de línia.

Confusió d’algorisme. L’atac clàssic contra els JWT és un testimoni que declara alg: none o canvia a un algorisme simètric perquè el verificador l’accepti per error. Els nostres exemples ho eviten fixant l’algorisme esperat, EdDSA, i rebutjant la resta. Mai no deixis que el testimoni triï com es verifica.

Errors de farciment base64. JWS usa base64url sense farciment. Python necessita que s’hi torni a afegir (com es veu més amunt), i Go necessita RawURLEncoding, no URLEncoding.

Signatura vàlida, però la credencial continua sent bona? Una signatura prova l’autenticitat i la integritat, no l’estat actual. Una credencial pot estar ben signada i, tot i així, revocada o caducada. Comprova exp a la càrrega útil i comprova l’estat de revocació que descrivim tot seguit.

No t’oblidis de la revocació

Cada credencial Open Badges 3.0 de https://badges.ninja porta una entrada credentialStatus que segueix la W3C Bitstring Status List. Apunta a una credencial de llista d’estat que pots obtenir a /certify-badge/status/<listId>. Quan un emissor revoca un atorgament, canvia un bit d’aquesta llista; la llista es guarda a la memòria cau durant aproximadament un minut, de manera que les revocacions arriben ràpid als verificadors. Descodifica la llista i llegeix el bit a la posició statusListIndex de la credencial: 1 vol dir revocada, 0 vol dir activa. La referència de verificació inclou un breu exemple en Node d’aquesta comprovació del bit.

Un verificador complet fa tres coses: verifica la signatura, comprova la caducitat i comprova el bit de revocació. Si vols veure com es veu la revocació des del costat de l’emissor, l’acció del tauler es descriu a la guia d’atorgaments.

Quan no necessites res d’això

La majoria de responsables de programes mai no escriuran aquest codi, i està bé. Per a les comprovacions del dia a dia, obre la pàgina pública de l’atorgament a https://badges.ninja/awards/<awardId> i llegeix-la. La pàgina no requereix registre ni clau, i mostra l’emissor, la insígnia i l’estat. Els destinataris també poden baixar la Verifiable Credential des del menú Download de la seva pàgina pública de credencial i importar-la a qualsevol cartera Open Badges 3.0.

La comprovació de signatures esdevé valuosa quan:

  • una empresa o una universitat vol automatitzar la comprovació de les credencials que rep;
  • construeixes un sistema de registres que guarda còpies de credencials i necessita demostrar que no s’han alterat;
  • un auditor demana proves que les teves credencials són verificables de manera independent, no només «confieu en el nostre web».

La mateixa configuració de clau d’API que s’usa per emetre no cal aquí, perquè tots aquests endpoints són públics. Si vols emetre credencials des de codi, la guia ràpida de l’API t’explica com crear una clau i el teu primer atorgament.

API Keys — empty state

Referència ràpida

ElementValor
Credencial signadaGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
JSON sense signar per llegirla mateixa URL amb ?format=json
DID de l’emissordid:web:api.badges.ninja
Claus públiques/.well-known/jwks.json i /.well-known/did.json
AlgorismeEd25519 (EdDSA)
Coincidència de clauel fragment del kid de la capçalera és igual al kid del JWKS
RevocaciócredentialStatus que apunta a /certify-badge/status/<listId>

Per acabar

Verificar la signatura d’una Open Badge és una rutina curta i mecànica: obtenir el testimoni, fixar l’algorisme, trobar la clau per l’empremta i comprovar la signatura Ed25519 sobre els dos primers segments. Afegeix-hi les comprovacions de caducitat i revocació i tens un verificador que no es refia de ningú més que de la clau publicada de l’emissor. Aquesta independència és el que fa que una credencial digital valgui més que un PDF.

Vols emetre la teva primera credencial verificable? Comença gratis a badges.ninja — dissenyador visual, pàgina pública de verificació, certificat en PDF, sortida Open Badge v2.0. Sense targeta de crèdit.

Nacho Coll

Sobre l'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.

Tornar al Blog

Articles Relacionats