Верифікація підпису Open Badge у Node.js, Python і Go

Три робочі приклади коду (Node, Python, Go): отримання підписаного посвідчення Open Badge, пошук публічного ключа емітента та перевірка підпису JWS.

Nacho Coll Автор Оновлено 8 хв читання
Три робочі приклади коду (Node, Python, Go): отримання підписаного посвідчення Open Badge, пошук публічного ключа емітента та перевірка підпису JWS.

Якщо ви видаєте посвідчення, більшість роботи з верифікації відбувається без вас: отримувач ділиться посиланням, роботодавець відкриває його, а решту робить сторінка верифікації. Але рано чи пізно хтось поставить гостріше запитання: «Як мені переконатися, що цей файл справді підписали ви і його не змінили згодом?» Відповідь дає цифровий підпис, а перевірка займає близько п’ятнадцяти рядків коду в будь-якій поширеній мові.

Цей туторіал покроково показує, як верифікувати підписане посвідчення Open Badges 3.0, видане через https://badges.ninja, у Node.js, Python і Go. Запускати щось із цього для видачі посвідчень не потрібно. Він для тих, хто хоче провести аудит системи, створити внутрішній інструмент верифікації або просто зрозуміти, що на практиці означає «верифіковане».

Що саме ви верифікуєте

В Open Badges є два рівні верифікації, і їх корисно розрізняти.

Хостингова верифікація — це модель Open Badges 2.0. Нагорода має публічну URL-адресу, і кожен, хто її відкриє, побачить емітента, значок, хешовану ідентичність отримувача та статус. Довіра випливає з того, що дані віддаються з домену самого емітента. Якщо сторінка відкривається на https://badges.ninja, посвідчення справжнє. Для цього не потрібні ні код, ні підпис.

Верифікація підпису — це модель Open Badges 3.0 на основі W3C Verifiable Credentials. Посвідчення пакується як підписаний токен, тож його можна перевірити офлайн, навіть через роки, якщо його скопіювали до гаманця чи вкладення листа. Довіра ґрунтується на математиці: токен містить підпис, який міг створити лише власник приватного ключа емітента.

На https://badges.ninja кожна нагорода доступна в обох формах. Ця стаття про другу. Якщо хочете дізнатися, чим відрізняються версії, прочитайте Open Badges v2 vs v3, а огляд хостингового JSON дивіться в розборі Open Badge JSON-LD.

З чого це складається

Підписане посвідчення — це VC-JWT: компактний JWS, тобто три рядки base64url, розділені крапками.

header.payload.signature
  • Заголовок (header) каже, як створено підпис. У наших посвідченнях він містить alg: EdDSA, typ: JWT та kid (ідентифікатор ключа) на кшталт did:web:api.badges.ninja#<thumbprint>.
  • Корисне навантаження (payload) містить твердження (claims), зокрема iss (DID емітента did:web:api.badges.ninja), jti (ідентифікатор посвідчення), nbf (чинне з), необов’язковий exp (термін дії) та об’єкт vc зі справжнім OpenBadgeCredential.
  • Підпис — це підпис Ed25519 над точними байтами header.payload.

Публічний ключ для перевірки підпису емітент публікує у двох місцях, обидва без автентифікації:

  • https://api.badges.ninja/.well-known/jwks.json повертає набір JWK (JWK Set).
  • https://api.badges.ninja/.well-known/did.json повертає DID-документ для did:web:api.badges.ninja.

kid у JWKS — це відбиток ключа за RFC 7638. kid у заголовку токена — це DID URL, і його фрагмент (частина після #) є тим самим відбитком. Саме за цим фрагментом ви обираєте потрібний ключ.

Рецепт верифікації

В усіх мовах п’ять однакових кроків:

  1. Отримайте підписане посвідчення з публічної кінцевої точки.
  2. Розділіть токен на три частини.
  3. Прочитайте заголовок, переконайтеся, що alg точно EdDSA, і візьміть відбиток із kid.
  4. Отримайте JWKS і знайдіть ключ із відповідним kid.
  5. Перевірте підпис Ed25519 над header.payload цим ключем.

Кінцева точка посвідчення публічна й приймає ідентифікатор нагороди (той самий GUID, що в URL верифікації на кшталт https://badges.ninja/awards/<awardId>):

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

За замовчуванням вона повертає підписаний VC-JWT як application/jwt. Додайте ?format=json, щоб отримати непідписаний JSON посвідчення для читання. Обидва варіанти описано в довіднику з верифікації.

Зверніть увагу: окремої кінцевої точки «перевір це за мене» немає, і це свідомо. Сервер, який каже «так, дійсне», просить вас довіряти серверу. Весь сенс підпису в тому, що ви перевіряєте його самі за опублікованим ключем.

Node.js

Вбудований модуль crypto у Node підтримує Ed25519 та імпорт JWK, тому залежності не потрібні.

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

Аргумент null на місці алгоритму правильний: в Ed25519 тип ключа визначає алгоритм. Якщо віддаєте перевагу бібліотеці, jose робить те саме через compactVerify та importJWK і сама перевіряє заголовки.

Python

Пакет cryptography одразу дає Ed25519. Встановіть його командою 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 не має імпорту JWK для Ed25519, тому координату x (сирий 32-байтовий публічний ключ) ми декодуємо самі. Це все, що містить JWK типу OKP з кривою Ed25519.

Go

Стандартна бібліотека Go покриває все, включно з 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)
}

Запустіть командою go run main.go <awardId>. Обробку помилок скорочено для читабельності; у справжньому інструменті ви перевіряли б кожне декодування.

Типові помилки та як їх читати

Ключа немає в JWKS. Ви порівняли повний kid із заголовка токена (did:web:api.badges.ninja#abc) із kid у JWKS (abc). Порівнюйте лише фрагмент після #. Якщо фрагмент усе одно не збігається, емітент міг змінити ключі після створення токена; отримайте DID-документ і перегляньте записи verificationMethod.

Підпис недійсний на токені, який ви щойно завантажили. Перевірте, що ви верифікували header.payload як вихідний текст base64url, а не заново закодований JSON. Повторна серіалізація JSON змінює байти й ламає підпис. Також перевірте, чи немає кінцевого переведення рядка в завантаженому токені.

Плутанина алгоритмів. Класична атака на JWT — токен, що заявляє alg: none або переходить на симетричний алгоритм, аби верифікатор його прийняв. Наші приклади цього уникають: очікуваний алгоритм EdDSA прописано жорстко, а все інше відхиляється. Ніколи не дозволяйте токену самому обирати, як його верифікувати.

Помилки доповнення base64. JWS використовує base64url без доповнення. Python потребує повернути доповнення (показано вище), а Go — RawURLEncoding, а не URLEncoding.

Підпис дійсний, але чи посвідчення ще чинне? Підпис доводить автентичність і цілісність, а не поточний статус. Посвідчення може бути правильно підписане й водночас відкликане чи прострочене. Перевірте exp у payload та статус відкликання, описаний нижче.

Не забудьте про відкликання

Кожне посвідчення Open Badges 3.0 з https://badges.ninja містить запис credentialStatus за W3C Bitstring Status List. Він вказує на посвідчення зі списком статусів, яке можна отримати за адресою /certify-badge/status/<listId>. Коли емітент відкликає нагороду, у цьому списку перемикається біт; список кешується приблизно на хвилину, тож відкликання швидко доходять до верифікаторів. Декодуйте список і прочитайте біт за statusListIndex посвідчення: 1 означає відкликано, 0 — активне. Довідник з верифікації містить короткий приклад на Node для цієї перевірки біта.

Повний верифікатор робить три речі: перевіряє підпис, перевіряє термін дії та перевіряє біт відкликання. Щоб побачити, як відкликання виглядає з боку емітента, дію на панелі описано в посібнику з нагород.

Коли нічого з цього не потрібно

Більшість власників програм ніколи не писатимуть такий код, і це нормально. Для щоденних перевірок відкрийте публічну сторінку нагороди за адресою https://badges.ninja/awards/<awardId> і прочитайте її. Сторінка не потребує реєстрації чи ключа й показує емітента, значок і статус. Отримувачі також можуть завантажити Verifiable Credential з меню «Завантажити» на своїй публічній сторінці посвідчення та імпортувати його в будь-який гаманець Open Badges 3.0.

Перевірка підпису стає цінною, коли:

  • роботодавець чи університет хоче автоматизувати перевірку отриманих посвідчень;
  • ви створюєте систему обліку, що зберігає копії посвідчень і мусить довести, що їх не змінювали;
  • аудитор просить доказ, що ваші посвідчення можна верифікувати незалежно, а не просто «довіряйте нашому сайту».

Налаштування API-ключа, яке ви використовуєте для видачі, тут не потрібне, бо всі ці кінцеві точки публічні. Якщо ви хочете видавати посвідчення з коду, швидкий старт API проведе вас через створення ключа та першу нагороду.

API Keys — empty state

Коротка довідка

ЕлементЗначення
Підписане посвідченняGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Непідписаний JSON для читаннята сама URL із ?format=json
DID емітентаdid:web:api.badges.ninja
Публічні ключі/.well-known/jwks.json і /.well-known/did.json
АлгоритмEd25519 (EdDSA)
Збіг ключафрагмент kid із заголовка дорівнює kid у JWKS
ВідкликанняcredentialStatus, що вказує на /certify-badge/status/<listId>

Підсумок

Верифікація підпису Open Badge — це коротка механічна процедура: отримайте токен, зафіксуйте алгоритм, знайдіть ключ за відбитком і перевірте підпис Ed25519 над першими двома сегментами. Додайте перевірки терміну дії та відкликання — і матимете верифікатор, що не довіряє нікому, крім опублікованого ключа емітента. Саме ця незалежність робить цифрове посвідчення вартішим за PDF.

Готові видати своє перше верифіковане посвідчення? Почніть безкоштовно на badges.ninja — візуальний дизайнер, публічна сторінка верифікації, PDF-сертифікат, вивід Open Badge v2.0. Кредитна картка не потрібна.

Nacho Coll

Про автора

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.

Назад до Блогу

Схожі статті