Como verificar a assinatura de um Open Badge em Node.js, Python e Go

Três exemplos de código funcionais (Node, Python, Go) para buscar uma credencial Open Badge assinada, resolver a chave pública do emissor e verificar a assinatura JWS.

Nacho Coll Por Atualizado 10 min de leitura
Três exemplos de código funcionais (Node, Python, Go) para buscar uma credencial Open Badge assinada, resolver a chave pública do emissor e verificar a assinatura JWS.

Se você emite credenciais, a maior parte do trabalho de verificação acontece sem você: um destinatário compartilha um link, um empregador clica e a página de verificação faz o resto. Mas, mais cedo ou mais tarde, alguém vai fazer uma pergunta mais afiada: “Como sei que este arquivo foi mesmo assinado por você e não foi editado depois?“. Essa pergunta é respondida por uma assinatura digital, e conferir uma leva cerca de quinze linhas de código em qualquer linguagem comum.

Este tutorial mostra, passo a passo, como verificar uma credencial Open Badges 3.0 assinada e emitida pelo https://badges.ninja, em Node.js, Python e Go. Você não precisa executar nada disso para emitir credenciais. Ele é para quem quer auditar o sistema, criar uma ferramenta interna de verificação ou simplesmente entender o que “verificável” significa na prática.

O que você realmente está verificando

Existem duas camadas de verificação no Open Badges, e ajuda mantê-las separadas.

A verificação hospedada é o modelo do Open Badges 2.0. A concessão do emblema tem uma URL pública, e qualquer pessoa que a abra vê o emissor, o emblema, a identidade com hash do destinatário e o status. A confiança vem do fato de os dados serem servidos pelo domínio do próprio emissor. Se você consegue acessar a página em https://badges.ninja, a credencial é real. Não exige código nem assinatura.

A verificação de assinatura é o modelo do Open Badges 3.0, construído sobre as Verifiable Credentials do W3C. A credencial é empacotada como um token assinado, e por isso pode ser conferida offline, anos depois, mesmo que tenha sido copiada para uma carteira digital ou um anexo de e-mail. A confiança vem da matemática: o token carrega uma assinatura que só quem possui a chave privada do emissor poderia ter produzido.

No https://badges.ninja, toda concessão de emblema está disponível nas duas formas. Este artigo trata da segunda. Se quiser entender como as duas versões diferem, leia Open Badges v2 vs v3 e, para um passeio pelo JSON hospedado, veja o passo a passo do JSON-LD do Open Badge.

As peças do sistema

A credencial assinada é um VC-JWT: um JWS compacto, ou seja, três strings base64url separadas por pontos.

header.payload.signature
  • O cabeçalho diz como a assinatura foi feita. Nas nossas credenciais, ele contém alg: EdDSA, typ: JWT e um kid (identificador da chave) parecido com did:web:api.badges.ninja#<thumbprint>.
  • O payload contém as declarações, incluindo iss (o DID do emissor did:web:api.badges.ninja), jti (o id da credencial), nbf (válida a partir de), um exp opcional (expiração) e um objeto vc com a OpenBadgeCredential propriamente dita.
  • A assinatura é uma assinatura Ed25519 sobre os bytes exatos de header.payload.

A chave pública que confere a assinatura é publicada pelo emissor em dois lugares, ambos sem autenticação:

  • https://api.badges.ninja/.well-known/jwks.json retorna um JWK Set.
  • https://api.badges.ninja/.well-known/did.json retorna o documento DID de did:web:api.badges.ninja.

O kid do JWKS é a impressão digital (thumbprint) da chave conforme a RFC 7638. O kid no cabeçalho do token é a URL DID, e o fragmento dela (a parte depois de #) é essa mesma impressão digital. Esse fragmento é o que permite escolher a chave certa.

A receita de verificação

Todas as linguagens seguem os mesmos cinco passos:

  1. Busque a credencial assinada no endpoint público.
  2. Divida o token em suas três partes.
  3. Leia o cabeçalho, confira que alg é exatamente EdDSA e pegue a impressão digital em kid.
  4. Busque o JWKS e encontre a chave cujo kid corresponde.
  5. Verifique a assinatura Ed25519 sobre header.payload com essa chave.

O endpoint da credencial é público e recebe o id da concessão (o mesmo GUID que você vê em uma URL de verificação como https://badges.ninja/awards/<awardId>):

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

Por padrão, ele retorna o VC-JWT assinado como application/jwt. Adicione ?format=json para obter o JSON da credencial sem assinatura, para leitura. A referência de verificação documenta os dois.

Repare que não existe um endpoint separado do tipo “verifique isso para mim”, e isso é proposital. Um servidor que diz “sim, é válida” pede que você confie no servidor. O objetivo de uma assinatura é que você mesmo possa conferi-la com uma chave publicada.

Node.js

O módulo crypto nativo do Node suporta Ed25519 e importação de JWK, então você não precisa de dependências.

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

O argumento de algoritmo null está correto: com Ed25519, o tipo da chave já define o algoritmo. Se preferir uma biblioteca, a jose faz o mesmo trabalho com compactVerify e importJWK, e cuida das verificações do cabeçalho para você.

Python

O pacote cryptography oferece Ed25519 diretamente. Instale com 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"])

O Python não tem importação de JWK para Ed25519 nessa biblioteca, então decodificamos nós mesmos a coordenada x (a chave pública bruta de 32 bytes). É tudo o que um JWK do tipo OKP com curva Ed25519 contém.

Go

A biblioteca padrão do Go cobre tudo, inclusive 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)
}

Execute com go run main.go <awardId>. O tratamento de erros foi reduzido para facilitar a leitura; em uma ferramenta de verdade, você verificaria cada decodificação.

Erros comuns e como interpretá-los

A chave não é encontrada no JWKS. Você comparou o kid completo do cabeçalho do token (did:web:api.badges.ninja#abc) com o kid do JWKS (abc). Compare apenas o fragmento depois de #. Se o fragmento ainda não bater, o emissor pode ter rotacionado as chaves desde que o token foi gerado; busque o documento DID e olhe as entradas de verificationMethod.

Assinatura inválida em um token que você acabou de baixar. Confira se você verificou header.payload como o texto base64url original, e não como JSON recodificado. Serializar o JSON de novo muda os bytes e quebra a assinatura. Verifique também se o token baixado não tem uma quebra de linha no final.

Confusão de algoritmo. O ataque clássico a JWT é um token que declara alg: none ou troca para um algoritmo simétrico para enganar o verificador e fazê-lo aceitar o token. Nossos exemplos evitam isso fixando no código o algoritmo esperado, EdDSA, e recusando todo o resto. Nunca deixe o token escolher como ele será verificado.

Erros de padding do base64. O JWS usa base64url sem padding. O Python precisa que o padding seja adicionado de volta (como mostrado acima), e o Go precisa de RawURLEncoding, não de URLEncoding.

Assinatura válida, mas a credencial ainda é boa? Uma assinatura prova autenticidade e integridade, não o status atual. Uma credencial pode estar corretamente assinada e ainda assim ter sido revogada ou expirado. Confira exp no payload e verifique o status de revogação descrito a seguir.

Não esqueça da revogação

Toda credencial Open Badges 3.0 do https://badges.ninja traz uma entrada credentialStatus que segue a Bitstring Status List do W3C. Ela aponta para uma credencial de lista de status que você pode buscar em /certify-badge/status/<listId>. Quando um emissor revoga uma concessão, um bit é alterado nessa lista; a lista fica em cache por cerca de um minuto, então as revogações chegam rápido aos verificadores. Decodifique a lista e leia o bit no statusListIndex da credencial: 1 significa revogada, 0 significa ativa. A referência de verificação inclui um pequeno exemplo em Node dessa verificação de bit.

Um verificador completo faz três coisas: verifica a assinatura, confere a expiração e confere o bit de revogação. Se quiser ver como a revogação aparece do lado do emissor, a ação no painel está descrita no guia de concessões.

Quando você não precisa de nada disso

A maioria dos responsáveis por programas nunca vai escrever esse código, e tudo bem. Para as conferências do dia a dia, abra a página pública da concessão em https://badges.ninja/awards/<awardId> e leia. A página não exige cadastro nem chave, e mostra o emissor, o emblema e o status. Os destinatários também podem baixar a Verifiable Credential no menu Download da página pública da credencial e importá-la em qualquer carteira compatível com Open Badges 3.0.

A verificação de assinatura passa a ter valor quando:

  • um empregador ou uma universidade quer automatizar a conferência das credenciais que recebe;
  • você está criando um sistema de registros que guarda cópias de credenciais e precisa provar que elas não foram alteradas;
  • um auditor pede evidências de que suas credenciais são verificáveis de forma independente, e não apenas “confie no nosso site”.

A mesma configuração de chave de API usada para emitir não é necessária aqui, porque todos esses endpoints são públicos. Se você quiser emitir credenciais por código, o guia rápido da API mostra como criar uma chave e fazer sua primeira concessão.

API Keys — empty state

Referência rápida

ItemValor
Credencial assinadaGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
JSON sem assinatura para leituraa mesma URL com ?format=json
DID do emissordid:web:api.badges.ninja
Chaves públicas/.well-known/jwks.json e /.well-known/did.json
AlgoritmoEd25519 (EdDSA)
Correspondência da chaveo fragmento do kid do cabeçalho é igual ao kid do JWKS
RevogaçãocredentialStatus apontando para /certify-badge/status/<listId>

Concluindo

Verificar a assinatura de um Open Badge é uma rotina curta e mecânica: busque o token, fixe o algoritmo, encontre a chave pela impressão digital e confira a assinatura Ed25519 sobre os dois primeiros segmentos. Some as verificações de expiração e revogação e você terá um verificador que não confia em ninguém além da chave publicada do emissor. É essa independência que faz uma credencial digital valer mais do que um PDF.

Pronto para emitir sua primeira credencial verificável? Comece grátis no badges.ninja — designer visual, página pública de verificação, certificado em PDF, saída Open Badge v2.0. Sem cartão de crédito.

Nacho Coll

Sobre o 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.

Voltar ao Blog

Artigos Relacionados