Open Badge -allekirjoituksen varmennus Node.js:llä, Pythonilla ja Gollla

Kolme toimivaa koodiesimerkkiä (Node, Python, Go) allekirjoitetun Open Badge -todistuksen hakemiseen, myöntäjän julkisen avaimen selvittämiseen ja JWS-allekirjoituksen varmentamiseen.

Nacho Coll Kirjoittanut Päivitetty 8 min lukuaika
Kolme toimivaa koodiesimerkkiä (Node, Python, Go) allekirjoitetun Open Badge -todistuksen hakemiseen, myöntäjän julkisen avaimen selvittämiseen ja JWS-allekirjoituksen varmentamiseen.

Jos myönnät todistuksia, suurin osa varmennustyöstä tapahtuu ilman sinua: vastaanottaja jakaa linkin, työnantaja klikkaa sitä, ja varmennussivu hoitaa lopun. Ennemmin tai myöhemmin joku kuitenkin kysyy terävämmän kysymyksen. “Mistä tiedän, että tämän tiedoston on todella allekirjoittanut sinä, eikä sitä ole muokattu jälkikäteen?” Tähän vastaa digitaalinen allekirjoitus, ja sen tarkistaminen vie noin viisitoista riviä koodia millä tahansa yleisellä kielellä.

Tämä opas näyttää, miten varmennat https://badges.ninja:n kautta myönnetyn allekirjoitetun Open Badges 3.0 -todistuksen vaihe vaiheelta Node.js:llä, Pythonilla ja Gollla. Mitään tästä ei tarvitse ajaa todistusten myöntämiseksi. Tämä on tarkoitettu niille, jotka haluavat auditoida järjestelmän, rakentaa sisäisen varmennustyökalun tai vain ymmärtää, mitä “varmennettavissa oleva” käytännössä tarkoittaa.

Mitä oikeastaan varmennat

Open Badgesissa on kaksi varmennuksen tasoa, ja ne kannattaa pitää erillään.

Isännöity varmennus on Open Badges 2.0 -malli. Myöntämisellä on julkinen URL, ja jokainen, joka avaa sen, näkee myöntäjän, merkin, vastaanottajan tiivistetyn identiteetin ja tilan. Luottamus syntyy siitä, että data tarjoillaan myöntäjän omalta verkkotunnukselta. Jos pääset sivulle osoitteessa https://badges.ninja, todistus on aito. Tämä ei vaadi koodia eikä allekirjoitusta.

Allekirjoituksen varmennus on Open Badges 3.0 -malli, joka perustuu W3C Verifiable Credentials -standardiin. Todistus on paketoitu allekirjoitetuksi tokeniksi, joten sen voi tarkistaa offline-tilassa vuosia myöhemmin, vaikka se olisi kopioitu lompakkoon tai sähköpostin liitteeksi. Luottamus syntyy matematiikasta: token sisältää allekirjoituksen, jonka on voinut tuottaa vain myöntäjän yksityisen avaimen haltija.

Palvelussa https://badges.ninja jokainen myöntö on saatavilla molemmissa muodoissa. Tämä artikkeli käsittelee jälkimmäistä. Jos haluat taustaa siitä, miten versiot eroavat, lue Open Badges v2 vs v3, ja isännöidyn JSONin esittelyyn tutustu Open Badge JSON-LD -läpikäyntiin.

Liikkuvat osat

Allekirjoitettu todistus on VC-JWT: kompakti JWS, eli kolme pisteillä erotettua base64url-merkkijonoa.

header.payload.signature
  • Header kertoo, miten allekirjoitus on tehty. Meidän todistuksissamme se sisältää alg: EdDSA, typ: JWT ja kid:n (avaimen tunniste), joka näyttää tältä: did:web:api.badges.ninja#<thumbprint>.
  • Payload sisältää väitteet (claims), mukaan lukien iss (myöntäjän DID did:web:api.badges.ninja), jti (todistuksen tunniste), nbf (voimassa alkaen), valinnaisen exp:n (vanheneminen) ja vc-objektin, jossa on varsinainen OpenBadgeCredential.
  • Allekirjoitus on Ed25519-allekirjoitus header.payload-tavujen tarkan sisällön yli.

Allekirjoituksen tarkistava julkinen avain julkaistaan kahdessa paikassa, kumpikin ilman tunnistautumista:

  • https://api.badges.ninja/.well-known/jwks.json palauttaa JWK Setin.
  • https://api.badges.ninja/.well-known/did.json palauttaa did:web:api.badges.ninja-tunnuksen DID-dokumentin.

JWKS:n kid on avaimen RFC 7638 -thumbprint. Token-headerin kid on DID URL, ja sen fragmentti (#-merkin jälkeinen osa) on sama thumbprint. Tuon fragmentin avulla valitset oikean avaimen.

Varmennusohje

Jokainen kieli noudattaa samoja viittä vaihetta:

  1. Hae allekirjoitettu todistus julkisesta rajapintapisteestä.
  2. Jaa token kolmeen osaan.
  3. Lue header, tarkista että alg on täsmälleen EdDSA, ja ota thumbprint kid:stä.
  4. Hae JWKS ja etsi avain, jonka kid täsmää.
  5. Varmenna Ed25519-allekirjoitus header.payload-sisällön yli kyseisellä avaimella.

Todistuksen rajapintapiste on julkinen ja ottaa vastaan myöntötunnisteen (sama GUID, jonka näet varmennus-URL:ssä, kuten https://badges.ninja/awards/<awardId>):

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

Oletuksena tämä palauttaa allekirjoitetun VC-JWT:n tyyppinä application/jwt. Lisää ?format=json, niin saat allekirjoittamattoman todistus-JSONin luettavaksi. Varmennusviite dokumentoi molemmat.

Huomaa, ettei erillistä “varmenna tämä puolestani” -rajapintapistettä ole, ja se on tarkoituksellista. Palvelin, joka kertoo “kyllä, kelvollinen”, pyytää sinua luottamaan palvelimeen. Allekirjoituksen koko pointti on, että voit tarkistaa sen itse julkaistua avainta vasten.

Node.js

Noden sisäänrakennettu crypto-moduuli tukee Ed25519:ää ja JWK-tuontia, joten riippuvuuksia ei tarvita.

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

Algoritmin null-argumentti on oikein: Ed25519:n kanssa avaintyyppi määrää algoritmin. Jos haluat kirjaston, jose tekee saman compactVerify- ja importJWK-funktioilla ja hoitaa header-tarkistukset puolestasi.

Python

cryptography-paketti tarjoaa Ed25519:n suoraan. Asenna se komennolla 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"])

Pythonissa ei tässä kirjastossa ole JWK-tuontia Ed25519:lle, joten dekoodaamme x-koordinaatin (raaka 32-tavuinen julkinen avain) itse. Se on kaikki, mitä tyypin OKP ja käyrän Ed25519 JWK sisältää.

Go

Gon standardikirjasto kattaa kaiken, myös crypto/ed25519:n.

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

Aja se komennolla go run main.go <awardId>. Virheenkäsittelyä on typistetty luettavuuden vuoksi; oikeassa työkalussa tarkistaisit jokaisen dekoodauksen.

Yleiset virheet ja miten ne luetaan

Avainta ei löydy JWKS:stä. Vertasit token-headerin koko kid:ia (did:web:api.badges.ninja#abc) JWKS:n kid:iin (abc). Vertaa vain #-merkin jälkeistä fragmenttia. Jos fragmentti ei silti täsmää, myöntäjä on voinut kierrättää avaimia tokenin luomisen jälkeen; hae DID-dokumentti ja katso sen verificationMethod-merkinnät.

Allekirjoitus on virheellinen juuri lataamallasi tokenilla. Tarkista, että varmensit header.payload-osan alkuperäisenä base64url-tekstinä, et uudelleenkoodattuna JSONina. JSONin sarjallistaminen uudelleen muuttaa tavut ja rikkoo allekirjoituksen. Tarkista myös, ettei ladatun tokenin perässä ole rivinvaihtoa.

Algoritmisekaannus. Klassinen JWT-hyökkäys on token, joka väittää alg: none tai vaihtaa symmetriseen algoritmiin, jotta varmentaja huijataan hyväksymään se. Esimerkkimme välttävät tämän kovakoodaamalla odotetun algoritmin, EdDSA, ja hylkäämällä kaiken muun. Älä koskaan anna tokenin päättää, miten se varmennetaan.

Base64-täytteen virheet. JWS käyttää base64urlia ilman täytettä. Pythonissa täyte pitää lisätä takaisin (näytetty yllä), ja Gossa tarvitaan RawURLEncoding, ei URLEncoding.

Allekirjoitus on kelvollinen, mutta onko todistus yhä voimassa? Allekirjoitus todistaa aitouden ja eheyden, ei nykyistä tilaa. Todistus voi olla oikein allekirjoitettu ja silti peruutettu tai vanhentunut. Tarkista exp payloadista ja tarkista peruutustila, josta kerrotaan seuraavaksi.

Älä unohda peruutusta

Jokaisella https://badges.ninja:n Open Badges 3.0 -todistuksella on credentialStatus-merkintä, joka noudattaa W3C Bitstring Status List -standardia. Se osoittaa tilalistatodistukseen, jonka voit hakea osoitteesta /certify-badge/status/<listId>. Kun myöntäjä peruuttaa myönnön, listassa käännetään yksi bitti; lista on välimuistissa noin minuutin, joten peruutukset tavoittavat varmentajat nopeasti. Dekoodaa lista ja lue bitti todistuksen statusListIndex-kohdasta: 1 tarkoittaa peruutettua, 0 aktiivista. Varmennusviite sisältää lyhyen Node-esimerkin tuosta bittitarkistuksesta.

Täydellinen varmentaja tekee kolme asiaa: varmentaa allekirjoituksen, tarkistaa vanhenemisen ja tarkistaa peruutusbitin. Jos haluat nähdä, miltä peruutus näyttää myöntäjän puolelta, hallintapaneelin toiminto on kuvattu myöntöoppaassa.

Milloin et tarvitse tätä lainkaan

Useimmat ohjelmien omistajat eivät koskaan kirjoita tätä koodia, ja se on täysin ok. Päivittäisiin tarkistuksiin avaa myönnön julkinen sivu osoitteessa https://badges.ninja/awards/<awardId> ja lue se. Sivu ei vaadi rekisteröitymistä eikä avainta, ja se näyttää myöntäjän, merkin ja tilan. Vastaanottajat voivat myös ladata Verifiable Credentialin julkisen todistussivunsa Lataa-valikosta ja tuoda sen mihin tahansa Open Badges 3.0 -lompakkoon.

Allekirjoituksen tarkistus tulee arvokkaaksi, kun:

  • työnantaja tai yliopisto haluaa automatisoida saamiensa todistusten tarkistuksen;
  • rakennat rekisterijärjestelmää, joka tallentaa todistusten kopioita ja jonka täytyy pystyä osoittamaan, ettei niitä ole muutettu;
  • tarkastaja pyytää todisteita siitä, että todistuksesi ovat riippumattomasti varmennettavissa, eikä vain “luota verkkosivuumme”.

Myöntämiseen käytettyä API-avaimen asennusta ei tarvita tässä, koska kaikki nämä rajapintapisteet ovat julkisia. Jos haluat myöntää todistuksia koodista, API-pikaopas käy läpi avaimen luomisen ja ensimmäisen myönnön.

API Keys — empty state

Pikaviite

KohdeArvo
Allekirjoitettu todistusGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Allekirjoittamaton JSON luettavaksisama URL ja ?format=json
Myöntäjän DIDdid:web:api.badges.ninja
Julkiset avaimet/.well-known/jwks.json ja /.well-known/did.json
AlgoritmiEd25519 (EdDSA)
Avaimen täsmäysheaderin kid:n fragmentti vastaa JWKS:n kid:iä
PeruutuscredentialStatus osoittaa kohteeseen /certify-badge/status/<listId>

Yhteenveto

Open Badge -allekirjoituksen varmennus on lyhyt, mekaaninen rutiini: hae token, lukitse algoritmi, etsi avain thumbprintin avulla ja tarkista Ed25519-allekirjoitus kahden ensimmäisen segmentin yli. Lisää vanhenemisen ja peruutuksen tarkistus, ja sinulla on varmentaja, joka ei luota kehenkään muuhun kuin myöntäjän julkaisemaan avaimeen. Juuri tämä riippumattomuus tekee digitaalisesta todistuksesta arvokkaamman kuin PDF.

Valmis myöntämään ensimmäisen varmennettavan todistuksesi? Aloita ilmaiseksi badges.ninjassa — visuaalinen suunnittelija, julkinen varmennussivu, PDF-sertifikaatti, Open Badge v2.0 -tuloste. Luottokorttia ei tarvita.

Nacho Coll

Kirjoittajasta

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.

Takaisin Blogiin

Aiheeseen liittyvät artikkelit