Верификација потписа 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 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) носи тврдње, укључујући 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"])

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 допуне (padding). 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 из менија Download на јавној страници своје акредитиве и увезу га у било који новчаник за Open Badges 3.0.

Провера потписа постаје вредна када:

  • послодавац или универзитет желе да аутоматизују провере акредитива које примају;
  • правите систем евиденције који чува копије акредитива и мора да докаже да нису измењене;
  • ревизор тражи доказ да су ваше акредитиве независно верификабилне, а не само „верујте нашем сајту“.

Подешавање API кључа које се користи за издавање овде није потребно, јер су све ове крајње тачке јавне. Ако ипак желите да издајете акредитиве из кода, API quickstart води вас кроз прављење кључа и прве доделе.

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.

Назад на блог

Повезани чланци