Node.js, Python ve Go ile Open Badge İmzasını Doğrulama

İmzalı bir Open Badge kimlik bilgisini almak, veren tarafın açık anahtarını çözmek ve JWS imzasını doğrulamak için üç çalışan kod örneği (Node, Python, Go).

Nacho Coll Yazan Güncellendi 8 dk okuma
İmzalı bir Open Badge kimlik bilgisini almak, veren tarafın açık anahtarını çözmek ve JWS imzasını doğrulamak için üç çalışan kod örneği (Node, Python, Go).

Kimlik bilgileri (credential) düzenliyorsanız, doğrulama işinin büyük kısmı siz hiçbir şey yapmadan gerçekleşir: alıcı bir bağlantı paylaşır, işveren tıklar ve doğrulama sayfası gerisini halleder. Ama er ya da geç biri daha keskin bir soru sorar: «Bu dosyanın gerçekten sizin tarafınızdan imzalandığını ve sonradan değiştirilmediğini nereden bileyim?» Bu sorunun cevabı dijital imzadır ve bir imzayı kontrol etmek, yaygın her dilde yaklaşık on beş satır kod tutar.

Bu eğitim, https://badges.ninja üzerinden düzenlenmiş imzalı bir Open Badges 3.0 credential’ını Node.js, Python ve Go ile adım adım nasıl doğrulayacağınızı gösteriyor. Credential düzenlemek için bunların hiçbirini çalıştırmanız gerekmez. Sistemi denetlemek, kurum içi bir doğrulama aracı geliştirmek veya «doğrulanabilir» ifadesinin pratikte ne anlama geldiğini kavramak isteyenler için hazırlandı.

Tam olarak neyi doğruluyorsunuz

Open Badges’ta iki doğrulama katmanı vardır ve bunları birbirinden ayırmak işe yarar.

Barındırılan doğrulama, Open Badges 2.0 modelidir. Ödülün herkese açık bir URL’si vardır ve onu açan herkes vereni, dijital rozeti, alıcının karma (hash) haline getirilmiş kimliğini ve durumu görür. Güven, verinin verenin kendi alan adından sunulmasından gelir. https://badges.ninja üzerindeki sayfaya ulaşabiliyorsanız credential gerçektir. Bunun için ne kod ne de imza gerekir.

İmza doğrulama, W3C Verifiable Credentials üzerine kurulu Open Badges 3.0 modelidir. Credential imzalı bir token olarak paketlenir; böylece yıllar sonra bile, bir cüzdana veya e-posta ekine kopyalanmış olsa da çevrimdışı kontrol edilebilir. Güven matematikten gelir: token, yalnızca verenin özel anahtarının sahibinin üretebileceği bir imza taşır.

https://badges.ninja üzerinde her ödül her iki biçimde de mevcuttur. Bu makale ikincisiyle ilgili. İki sürümün nasıl farklılaştığını merak ediyorsanız Open Badges v2 vs v3 yazısını okuyun; barındırılan JSON’a göz atmak için Open Badge JSON-LD incelemesine bakın.

Hareketli parçalar

İmzalı credential bir VC-JWT’dir: noktalarla ayrılmış üç base64url dizesinden oluşan kompakt bir JWS.

header.payload.signature
  • Header, imzanın nasıl atıldığını söyler. Bizim credential’larımızda alg: EdDSA, typ: JWT ve did:web:api.badges.ninja#<thumbprint> gibi görünen bir kid (anahtar kimliği) bulunur.
  • Payload, iss (veren DID’i did:web:api.badges.ninja), jti (credential kimliği), nbf (geçerlilik başlangıcı), isteğe bağlı exp (son kullanma) ve asıl OpenBadgeCredential’ı içeren vc nesnesi gibi claim’leri taşır.
  • İmza, header.payload baytları üzerinde atılmış bir Ed25519 imzasıdır.

İmzayı kontrol eden açık anahtarı veren iki yerde yayımlar, ikisi de kimlik doğrulaması olmadan erişilebilir:

  • https://api.badges.ninja/.well-known/jwks.json bir JWK Set döndürür.
  • https://api.badges.ninja/.well-known/did.json, did:web:api.badges.ninja için DID belgesini döndürür.

JWKS kid değeri, anahtarın RFC 7638 thumbprint’idir. Token header’ındaki kid ise DID URL’sidir ve fragment’ı (# sonrasındaki kısım) aynı thumbprint’tir. Doğru anahtarı bu fragment ile seçersiniz.

Doğrulama tarifi

Her dilde aynı beş adım izlenir:

  1. İmzalı credential’ı herkese açık uç noktadan alın.
  2. Token’ı üç parçaya bölün.
  3. Header’ı okuyun, alg değerinin tam olarak EdDSA olduğunu kontrol edin ve kid’den thumbprint’i alın.
  4. JWKS’i alın ve kid değeri eşleşen anahtarı bulun.
  5. O anahtarla header.payload üzerindeki Ed25519 imzasını doğrulayın.

Credential uç noktası herkese açıktır ve ödül kimliğini alır (https://badges.ninja/awards/<awardId> gibi bir doğrulama URL’sinde gördüğünüz GUID ile aynı):

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

Varsayılan olarak imzalı VC-JWT’yi application/jwt olarak döndürür. Okumak için imzasız credential JSON’unu almak istiyorsanız ?format=json ekleyin. Doğrulama referansı ikisini de belgeler.

Ayrı bir «bunu benim için doğrula» uç noktasının olmadığına dikkat edin; bu bilinçli bir tercih. «Evet, geçerli» diyen bir sunucu, sunucuya güvenmenizi ister. İmzanın bütün amacı, onu yayımlanmış bir anahtara karşı kendinizin kontrol edebilmesidir.

Node.js

Node’un yerleşik crypto modülü Ed25519’u ve JWK içe aktarmayı destekler, dolayısıyla hiçbir bağımlılığa ihtiyacınız yok.

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

Algoritma argümanı olarak null doğrudur: Ed25519’da algoritmayı anahtar türü belirler. Kütüphane tercih ederseniz jose, compactVerify ve importJWK ile aynı işi yapar ve header kontrollerini sizin yerinize halleder.

Python

cryptography paketi Ed25519’u doğrudan sunar. pip install cryptography requests ile kurun.

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"])

Bu kütüphanede Ed25519 için JWK içe aktarma yok, bu yüzden x koordinatını (ham 32 baytlık açık anahtar) kendimiz çözüyoruz. OKP türünde, Ed25519 eğrisine sahip bir JWK’nin içeriği bundan ibarettir.

Go

Go’nun standart kütüphanesi crypto/ed25519 dahil her şeyi kapsar.

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> ile çalıştırın. Hata işleme okunabilirlik için kısaltıldı; gerçek bir araçta her çözme işlemini kontrol etmelisiniz.

Sık görülen hatalar ve nasıl okunacakları

Anahtar JWKS’te bulunamıyor. Token header’ındaki tam kid değerini (did:web:api.badges.ninja#abc) JWKS kid değeriyle (abc) karşılaştırdınız. Yalnızca # sonrasındaki fragment’ı karşılaştırın. Fragment yine eşleşmiyorsa, veren token üretildiğinden beri anahtarları döndürmüş olabilir; DID belgesini alın ve verificationMethod girdilerine bakın.

Yeni indirdiğiniz token’da imza geçersiz. header.payload değerini yeniden kodlanmış JSON olarak değil, özgün base64url metni olarak doğruladığınızdan emin olun. JSON’u yeniden serileştirmek baytları değiştirir ve imzayı bozar. İndirilen token’da sondaki satır sonu karakteri olup olmadığını da kontrol edin.

Algoritma karışıklığı. Klasik JWT saldırısı, alg: none iddia eden veya simetrik bir algoritmaya geçen ve böylece doğrulayıcıyı kabul etmeye kandıran bir token’dır. Örneklerimiz beklenen algoritmayı, yani EdDSA’yı sabit kodlayıp gerisini reddederek bundan kaçınır. Token’ın nasıl doğrulanacağını asla token’ın kendisine seçtirmeyin.

Base64 padding hataları. JWS, padding’siz base64url kullanır. Python’da padding’i geri eklemek gerekir (yukarıda gösterildi), Go’da ise URLEncoding değil RawURLEncoding gerekir.

İmza geçerli, ama credential hâlâ iyi durumda mı? İmza özgünlüğü ve bütünlüğü kanıtlar, güncel durumu değil. Bir credential doğru imzalanmış olsa da iptal edilmiş veya süresi dolmuş olabilir. Payload’daki exp değerini ve aşağıda anlatılan iptal durumunu kontrol edin.

İptali unutmayın

https://badges.ninja’dan gelen her Open Badges 3.0 credential’ı, W3C Bitstring Status List’i izleyen bir credentialStatus girdisi taşır. Bu girdi, /certify-badge/status/<listId> adresinden alabileceğiniz bir durum listesi credential’ına işaret eder. Veren bir ödülü iptal ettiğinde bu listede bir bit değişir; liste yaklaşık bir dakika önbelleğe alınır, dolayısıyla iptaller doğrulayıcılara hızla ulaşır. Listeyi çözün ve credential’ın statusListIndex konumundaki biti okuyun: 1 iptal edilmiş, 0 aktif demektir. Doğrulama referansı, bu bit kontrolü için kısa bir Node örneği içerir.

Eksiksiz bir doğrulayıcı üç şey yapar: imzayı doğrular, son kullanma tarihini kontrol eder ve iptal bitini kontrol eder. İptalin veren tarafından nasıl göründüğünü merak ediyorsanız, panodaki işlem ödül kılavuzunda anlatılıyor.

Bunların hiçbirine ihtiyacınız olmadığında

Çoğu program sahibi bu kodu hiç yazmayacak ve bu gayet normal. Günlük kontroller için ödülün herkese açık sayfasını https://badges.ninja/awards/<awardId> adresinde açıp okumanız yeterli. Sayfa kayıt veya anahtar gerektirmez; vereni, rozeti ve durumu gösterir. Alıcılar ayrıca herkese açık credential sayfalarındaki Download menüsünden Verifiable Credential’ı indirip herhangi bir Open Badges 3.0 cüzdanına aktarabilir.

İmza kontrolü şu durumlarda değerli hale gelir:

  • bir işveren veya üniversite, aldığı credential’ların kontrolünü otomatikleştirmek istiyorsa;
  • credential kopyalarını saklayan ve değiştirilmediklerini kanıtlaması gereken bir kayıt sistemi geliştiriyorsanız;
  • bir denetçi, credential’larınızın yalnızca «web sitemize güvenin» değil, bağımsız olarak doğrulanabilir olduğuna dair kanıt istiyorsa.

Düzenleme için kullandığınız API anahtarı kurulumuna burada gerek yok, çünkü bu uç noktaların hepsi herkese açık. Kodla credential düzenlemek isterseniz API hızlı başlangıcı, bir anahtar oluşturmanızı ve ilk ödülünüzü vermenizi adım adım anlatır.

API Keys — empty state

Hızlı başvuru

ÖğeDeğer
İmzalı credentialGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Okumak için imzasız JSONaynı URL, ?format=json ile
Veren DID’idid:web:api.badges.ninja
Açık anahtarlar/.well-known/jwks.json ve /.well-known/did.json
AlgoritmaEd25519 (EdDSA)
Anahtar eşleştirmeheader kid fragment’ı JWKS kid değerine eşit
İptal/certify-badge/status/<listId> adresine işaret eden credentialStatus

Toparlarken

Bir Open Badge imzasını doğrulamak kısa ve mekanik bir rutindir: token’ı alın, algoritmayı sabitleyin, anahtarı thumbprint ile bulun ve ilk iki segment üzerindeki Ed25519 imzasını kontrol edin. Süre sonu ve iptal kontrollerini ekleyin; elinizde verenin yayımladığı anahtardan başka hiç kimseye güvenmeyen bir doğrulayıcı olur. Dijital bir credential’ı PDF’ten değerli kılan şey tam da bu bağımsızlıktır.

İlk doğrulanabilir credential’ınızı düzenlemeye hazır mısınız? badges.ninja’da ücretsiz başlayın — görsel tasarım aracı, herkese açık doğrulama sayfası, PDF sertifika, Open Badge v2.0 çıktısı. Kredi kartı gerekmez.

Nacho Coll

Yazar hakkında

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.

Blog'a Dön

İlgili Yazılar