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

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

Nacho Coll От Обновено 9 мин четене
Три работещи примера с код (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 срещу v3, а за разходка из хостваното JSON вижте разбора на Open Badge JSON-LD.

Движещите се части

Подписаното удостоверение е VC-JWT: компактен JWS, тоест три низа в base64url, разделени с точки.

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

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

  • https://api.badges.ninja/.well-known/jwks.json връща JWK Set.
  • https://api.badges.ninja/.well-known/did.json връща DID документа за did:web:api.badges.ninja.

kid в JWKS е RFC 7638 thumbprint на ключа. kid в хедъра на токена е DID URL, а фрагментът му (частта след #) е същият thumbprint. Именно по този фрагмент избирате правилния ключ.

Рецептата за верификация

Всеки език следва едни и същи пет стъпки:

  1. Изтеглете подписаното удостоверение от публичната крайна точка.
  2. Разделете токена на трите му части.
  3. Прочетете хедъра, проверете дали alg е точно EdDSA и вземете thumbprint от 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"])

Тази библиотека няма внос на 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 padding. JWS използва base64url без padding. Python изисква padding да се добави обратно (показано по-горе), а 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 от менюто Download на публичната страница на своето удостоверение и да го импортират във всеки портфейл с 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 е кратка, механична рутина: изтегляте токена, фиксирате алгоритъма, намирате ключа по thumbprint и проверявате 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.

Назад към блога

Свързани статии