Mengesahkan Tandatangan Open Badge dalam Node.js, Python dan Go

Tiga contoh kod yang berfungsi (Node, Python, Go) untuk mendapatkan kelayakan Open Badge yang ditandatangani, menyelesaikan kunci awam pengeluar dan mengesahkan tandatangan JWS.

Nacho Coll Oleh Dikemas kini 9 minit bacaan
Tiga contoh kod yang berfungsi (Node, Python, Go) untuk mendapatkan kelayakan Open Badge yang ditandatangani, menyelesaikan kunci awam pengeluar dan mengesahkan tandatangan JWS.

Jika anda mengeluarkan kelayakan, kebanyakan kerja pengesahan berlaku tanpa anda: penerima berkongsi pautan, majikan mengkliknya dan halaman pengesahan menguruskan selebihnya. Tetapi lambat laun ada yang akan bertanya soalan yang lebih tajam. “Bagaimana saya tahu fail ini benar-benar ditandatangani oleh anda, dan tidak diubah selepas itu?” Soalan itu dijawab oleh tandatangan digital, dan menyemaknya hanya memerlukan kira-kira lima belas baris kod dalam mana-mana bahasa arus perdana.

Tutorial ini menunjukkan cara mengesahkan kelayakan Open Badges 3.0 yang ditandatangani dan dikeluarkan melalui https://badges.ninja, langkah demi langkah, dalam Node.js, Python dan Go. Anda tidak perlu menjalankan satu pun daripadanya untuk mengeluarkan kelayakan. Ia untuk mereka yang mahu mengaudit sistem, membina alat pengesahan dalaman, atau sekadar memahami maksud “boleh disahkan” dalam praktiknya.

Apa yang sebenarnya anda sahkan

Terdapat dua lapisan pengesahan dalam Open Badges, dan ada baiknya anda membezakannya.

Pengesahan terhos ialah model Open Badges 2.0. Anugerah mempunyai URL awam, dan sesiapa yang membukanya akan melihat pengeluar, lencana, identiti penerima yang dicincang dan statusnya. Kepercayaan datang daripada hakikat bahawa data disajikan dari domain pengeluar sendiri. Jika anda boleh mencapai halaman itu di https://badges.ninja, kelayakan itu sahih. Ini tidak memerlukan kod dan tidak memerlukan tandatangan.

Pengesahan tandatangan ialah model Open Badges 3.0, dibina di atas W3C Verifiable Credentials. Kelayakan dibungkus sebagai token bertandatangan, jadi ia boleh disemak secara luar talian, bertahun-tahun kemudian, walaupun ia telah disalin ke dalam dompet atau lampiran e-mel. Kepercayaan datang daripada matematik: token itu membawa tandatangan yang hanya boleh dihasilkan oleh pemegang kunci persendirian pengeluar.

Di https://badges.ninja, setiap anugerah tersedia dalam kedua-dua bentuk. Artikel ini mengenai bentuk kedua. Jika anda mahu latar belakang tentang perbezaan kedua-dua versi, baca Open Badges v2 vs v3, dan untuk lawatan ke JSON terhos, lihat panduan Open Badge JSON-LD.

Bahagian-bahagian yang terlibat

Kelayakan bertandatangan ialah VC-JWT: JWS padat, iaitu tiga rentetan base64url yang dipisahkan oleh titik.

header.payload.signature
  • Pengepala (header) menyatakan cara ia ditandatangani. Untuk kelayakan kami, ia mengandungi alg: EdDSA, typ: JWT dan kid (id kunci) yang kelihatan seperti did:web:api.badges.ninja#<thumbprint>.
  • Muatan (payload) memegang tuntutan, termasuk iss (DID pengeluar did:web:api.badges.ninja), jti (id kelayakan), nbf (sah mulai), exp pilihan (tamat tempoh) dan objek vc yang mengandungi OpenBadgeCredential sebenar.
  • Tandatangan ialah tandatangan Ed25519 ke atas bait tepat header.payload.

Kunci awam yang menyemak tandatangan diterbitkan oleh pengeluar di dua tempat, kedua-duanya tanpa pengesahan identiti:

  • https://api.badges.ninja/.well-known/jwks.json memulangkan JWK Set.
  • https://api.badges.ninja/.well-known/did.json memulangkan dokumen DID untuk did:web:api.badges.ninja.

kid JWKS ialah cap jari (thumbprint) RFC 7638 bagi kunci itu. kid dalam pengepala token ialah URL DID, dan serpihannya (bahagian selepas #) ialah cap jari yang sama. Serpihan itulah yang membantu anda memilih kunci yang betul.

Resipi pengesahan

Setiap bahasa mengikuti lima langkah yang sama:

  1. Dapatkan kelayakan bertandatangan daripada titik akhir awam.
  2. Pecahkan token kepada tiga bahagiannya.
  3. Baca pengepala, semak bahawa alg tepat-tepat EdDSA, dan ambil cap jari daripada kid.
  4. Dapatkan JWKS dan cari kunci yang kid-nya sepadan.
  5. Sahkan tandatangan Ed25519 ke atas header.payload dengan kunci tersebut.

Titik akhir kelayakan adalah awam dan menerima id anugerah (GUID yang sama seperti yang anda lihat dalam URL pengesahan seperti https://badges.ninja/awards/<awardId>):

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

Secara lalai ia memulangkan VC-JWT bertandatangan sebagai application/jwt. Tambah ?format=json untuk mendapatkan JSON kelayakan tanpa tandatangan bagi tujuan bacaan. Rujukan pengesahan mendokumenkan kedua-duanya.

Perhatikan bahawa tiada titik akhir “sahkan ini untuk saya” yang berasingan, dan ini disengajakan. Pelayan yang memberitahu anda “ya, sah” meminta anda mempercayai pelayan itu. Tujuan utama tandatangan ialah anda boleh menyemaknya sendiri berdasarkan kunci yang diterbitkan.

Node.js

Modul crypto terbina dalam Node menyokong Ed25519 dan import JWK, jadi anda tidak memerlukan sebarang kebergantungan.

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

Argumen algoritma null adalah betul: dengan Ed25519, jenis kunci menetapkan algoritmanya. Jika anda lebih suka pustaka, jose melakukan tugas yang sama dengan compactVerify dan importJWK, dan mengendalikan semakan pengepala untuk anda.

Python

Pakej cryptography memberi anda Ed25519 secara terus. Pasangnya dengan 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 tidak mempunyai import JWK untuk Ed25519 dalam pustaka ini, jadi kami menyahkod sendiri koordinat x (kunci awam mentah 32 bait). Itulah semua yang terkandung dalam JWK berjenis OKP dengan lengkung Ed25519.

Go

Pustaka standard Go merangkumi segalanya, termasuk 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)
}

Jalankannya dengan go run main.go <awardId>. Pengendalian ralat dipendekkan demi kebolehbacaan; dalam alat sebenar anda akan menyemak setiap penyahkodan.

Ralat lazim dan cara membacanya

Kunci tidak ditemui dalam JWKS. Anda membandingkan kid penuh daripada pengepala token (did:web:api.badges.ninja#abc) dengan kid JWKS (abc). Bandingkan hanya serpihan selepas #. Jika serpihan masih tidak sepadan, pengeluar mungkin telah memutar kunci sejak token dicipta; dapatkan dokumen DID dan lihat entri verificationMethodnya.

Tandatangan tidak sah pada token yang baru anda muat turun. Semak bahawa anda mengesahkan header.payload sebagai teks base64url asal, bukan JSON yang dikodkan semula. Menyerialkan semula JSON mengubah bait dan merosakkan tandatangan. Semak juga sama ada terdapat baris baharu di hujung token yang dimuat turun.

Kekeliruan algoritma. Serangan JWT klasik ialah token yang mendakwa alg: none atau bertukar kepada algoritma simetri supaya pengesah tertipu menerimanya. Contoh kami mengelakkannya dengan menetapkan algoritma yang dijangka, EdDSA, secara tetap dan menolak yang lain. Jangan sekali-kali biarkan token memilih cara ia disahkan.

Ralat pelapik (padding) Base64. JWS menggunakan base64url tanpa pelapik. Python memerlukan pelapik ditambah semula (ditunjukkan di atas), dan Go memerlukan RawURLEncoding, bukan URLEncoding.

Tandatangan sah, tetapi adakah kelayakan itu masih baik? Tandatangan membuktikan ketulenan dan integriti, bukan status semasa. Kelayakan boleh ditandatangani dengan betul namun telah dibatalkan atau tamat tempoh. Semak exp dalam muatan, dan semak status pembatalan yang diterangkan seterusnya.

Jangan lupa pembatalan

Setiap kelayakan Open Badges 3.0 daripada https://badges.ninja membawa entri credentialStatus yang mengikut W3C Bitstring Status List. Ia menuding kepada kelayakan senarai status yang boleh anda dapatkan di /certify-badge/status/<listId>. Apabila pengeluar membatalkan anugerah, satu bit diterbalikkan dalam senarai itu; senarai tersebut disimpan dalam cache selama kira-kira seminit, jadi pembatalan sampai kepada pengesah dengan cepat. Nyahkod senarai dan baca bit pada statusListIndex kelayakan: 1 bermaksud dibatalkan, 0 bermaksud aktif. Rujukan pengesahan menyertakan contoh Node ringkas untuk semakan bit tersebut.

Pengesah yang lengkap melakukan tiga perkara: mengesahkan tandatangan, menyemak tarikh tamat tempoh dan menyemak bit pembatalan. Jika anda mahu melihat rupa pembatalan dari sisi pengeluar, tindakan papan pemuka itu dibincangkan dalam panduan anugerah.

Bila anda tidak memerlukan semua ini

Kebanyakan pemilik program tidak akan menulis kod ini, dan itu tidak mengapa. Untuk semakan harian, buka halaman awam anugerah di https://badges.ninja/awards/<awardId> dan bacanya. Halaman itu tidak memerlukan pendaftaran atau kunci, dan menunjukkan pengeluar, lencana dan status. Penerima juga boleh memuat turun Verifiable Credential daripada menu Download pada halaman kelayakan awam mereka, dan mengimportnya ke mana-mana dompet Open Badges 3.0.

Semakan tandatangan menjadi bernilai apabila:

  • majikan atau universiti mahu mengautomasikan semakan ke atas kelayakan yang mereka terima;
  • anda membina sistem rekod yang menyimpan salinan kelayakan dan perlu membuktikan ia tidak diubah;
  • juruaudit meminta bukti bahawa kelayakan anda boleh disahkan secara bebas, bukan sekadar “percayai laman web kami”.

Persediaan kunci API yang sama seperti untuk pengeluaran tidak diperlukan di sini, kerana semua titik akhir ini adalah awam. Jika anda mahu mengeluarkan kelayakan daripada kod, API quickstart membimbing anda mencipta kunci dan anugerah pertama anda.

API Keys — empty state

Rujukan pantas

ItemNilai
Kelayakan bertandatanganGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
JSON tanpa tandatangan untuk dibacaURL yang sama dengan ?format=json
DID pengeluardid:web:api.badges.ninja
Kunci awam/.well-known/jwks.json dan /.well-known/did.json
AlgoritmaEd25519 (EdDSA)
Padanan kunciserpihan kid pengepala sama dengan kid JWKS
PembatalancredentialStatus yang menuding ke /certify-badge/status/<listId>

Penutup

Mengesahkan tandatangan Open Badge ialah rutin yang ringkas dan mekanikal: dapatkan token, tetapkan algoritma, cari kunci melalui cap jari, dan semak tandatangan Ed25519 ke atas dua segmen pertama. Tambah semakan tamat tempoh dan pembatalan, dan anda mempunyai pengesah yang tidak mempercayai sesiapa kecuali kunci yang diterbitkan oleh pengeluar. Kebebasan itulah yang menjadikan kelayakan digital lebih bernilai daripada PDF.

Bersedia untuk mengeluarkan kelayakan boleh disahkan pertama anda? Mulakan percuma di badges.ninja — pereka visual, halaman pengesahan awam, sijil PDF, output Open Badge v2.0. Tiada kad kredit diperlukan.

Nacho Coll

Tentang penulis

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.

Kembali ke Blog

Artikel Berkaitan