Node.js, Python और Go में Open Badge सिग्नेचर का सत्यापन

साइन किए गए Open Badge credential को फ़ेच करने, जारीकर्ता की public key खोजने और JWS सिग्नेचर का सत्यापन करने के लिए तीन काम करने वाले कोड सैंपल (Node, Python, Go)।

Nacho Coll लेखक: अपडेट किया गया 10 मिनट पढ़ें
साइन किए गए Open Badge credential को फ़ेच करने, जारीकर्ता की public key खोजने और JWS सिग्नेचर का सत्यापन करने के लिए तीन काम करने वाले कोड सैंपल (Node, Python, Go)।

अगर आप credentials जारी करते हैं, तो सत्यापन का ज़्यादातर काम आपके बिना ही हो जाता है: प्राप्तकर्ता एक लिंक शेयर करता है, नियोक्ता उस पर क्लिक करता है, और बाकी काम सत्यापन पेज कर देता है। लेकिन देर-सबेर कोई ज़्यादा तीखा सवाल पूछता है: “मुझे कैसे पता चले कि यह फ़ाइल सच में आपने ही साइन की थी, और बाद में इसमें बदलाव नहीं हुआ?” इस सवाल का जवाब डिजिटल सिग्नेचर है, और किसी भी मुख्य भाषा में उसे जाँचने में लगभग पंद्रह लाइन का कोड लगता है।

यह ट्यूटोरियल दिखाता है कि https://badges.ninja से जारी किए गए साइन किए हुए Open Badges 3.0 credential का सत्यापन Node.js, Python और Go में कदम-दर-कदम कैसे किया जाए। credentials जारी करने के लिए आपको इसमें से कुछ भी चलाने की ज़रूरत नहीं है। यह उन लोगों के लिए है जो सिस्टम का ऑडिट करना चाहते हैं, कोई आंतरिक सत्यापन टूल बनाना चाहते हैं, या बस यह समझना चाहते हैं कि व्यवहार में “verifiable” का क्या मतलब है।

आप असल में किसका सत्यापन कर रहे हैं

Open Badges में सत्यापन की दो परतें हैं, और उन्हें अलग-अलग रखना मददगार है।

होस्टेड सत्यापन Open Badges 2.0 का मॉडल है। award का एक सार्वजनिक URL होता है, और उसे खोलने वाला कोई भी व्यक्ति जारीकर्ता, बैज, प्राप्तकर्ता की हैश की गई पहचान और स्टेटस देख सकता है। भरोसा इस बात से आता है कि डेटा जारीकर्ता के अपने डोमेन से परोसा जाता है। अगर आप https://badges.ninja पर वह पेज खोल पाते हैं, तो credential असली है। इसके लिए न कोड चाहिए, न सिग्नेचर।

सिग्नेचर सत्यापन Open Badges 3.0 का मॉडल है, जो W3C Verifiable Credentials पर बना है। credential को एक साइन किए हुए टोकन के रूप में पैक किया जाता है, इसलिए उसे ऑफ़लाइन, सालों बाद भी जाँचा जा सकता है, चाहे उसे किसी वॉलेट या ईमेल अटैचमेंट में कॉपी कर लिया गया हो। भरोसा गणित से आता है: टोकन में ऐसा सिग्नेचर होता है जो केवल जारीकर्ता की private key रखने वाला ही बना सकता था।

https://badges.ninja पर हर award दोनों रूपों में उपलब्ध है। यह लेख दूसरे रूप के बारे में है। अगर आप दोनों संस्करणों के अंतर की पृष्ठभूमि जानना चाहते हैं, तो Open Badges v2 vs v3 पढ़ें, और होस्टेड JSON की झलक के लिए Open Badge JSON-LD वॉकथ्रू देखें।

इसके मुख्य हिस्से

साइन किया हुआ credential एक VC-JWT है: एक कॉम्पैक्ट JWS, यानी डॉट से अलग किए गए तीन base64url स्ट्रिंग।

header.payload.signature
  • हेडर बताता है कि साइन कैसे किया गया। हमारे credentials में इसमें alg: EdDSA, typ: JWT और एक kid (key id) होता है जो did:web:api.badges.ninja#<thumbprint> जैसा दिखता है।
  • पेलोड में claims होते हैं, जिनमें iss (जारीकर्ता का DID did:web:api.badges.ninja), jti (credential id), nbf (कब से मान्य), वैकल्पिक exp (समाप्ति), और असली OpenBadgeCredential वाला vc ऑब्जेक्ट शामिल हैं।
  • सिग्नेचर header.payload के सटीक बाइट्स पर बना Ed25519 सिग्नेचर है।

सिग्नेचर जाँचने वाली public key को जारीकर्ता दो जगह प्रकाशित करता है, दोनों बिना ऑथेंटिकेशन के:

  • https://api.badges.ninja/.well-known/jwks.json एक JWK Set लौटाता है।
  • https://api.badges.ninja/.well-known/did.json did:web:api.badges.ninja का DID डॉक्यूमेंट लौटाता है।

JWKS का kid कुंजी का RFC 7638 थंबप्रिंट है। टोकन हेडर का kid DID URL है, और उसका फ़्रैगमेंट (# के बाद वाला हिस्सा) वही थंबप्रिंट है। सही कुंजी चुनने का तरीका वही फ़्रैगमेंट है।

सत्यापन की विधि

हर भाषा में यही पाँच चरण होते हैं:

  1. सार्वजनिक एंडपॉइंट से साइन किया हुआ credential फ़ेच करें।
  2. टोकन को उसके तीन हिस्सों में बाँटें।
  3. हेडर पढ़ें, जाँचें कि alg ठीक EdDSA है, और kid से थंबप्रिंट निकालें।
  4. JWKS फ़ेच करें और वह कुंजी खोजें जिसका kid मेल खाता हो।
  5. उस कुंजी से header.payload पर Ed25519 सिग्नेचर का सत्यापन करें।

credential एंडपॉइंट सार्वजनिक है और award id लेता है (वही GUID जो आपको https://badges.ninja/awards/<awardId> जैसे सत्यापन URL में दिखता है):

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

डिफ़ॉल्ट रूप से यह साइन किया हुआ VC-JWT application/jwt के रूप में लौटाता है। पढ़ने के लिए बिना साइन किया credential JSON पाने के लिए ?format=json जोड़ें। सत्यापन रेफ़रेंस में दोनों का वर्णन है।

ध्यान दें कि “मेरे लिए इसे verify करो” जैसा कोई अलग एंडपॉइंट नहीं है, और यह जानबूझकर है। जो सर्वर आपको बताता है “हाँ, मान्य है”, वह आपसे सर्वर पर भरोसा करने को कहता है। सिग्नेचर का पूरा मकसद यही है कि आप उसे प्रकाशित कुंजी के विरुद्ध खुद जाँच सकें।

Node.js

Node का बिल्ट-इन crypto मॉड्यूल 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"])

इस लाइब्रेरी में Ed25519 के लिए JWK इम्पोर्ट नहीं है, इसलिए हम x कोऑर्डिनेट (कच्ची 32-बाइट public key) को खुद डिकोड करते हैं। OKP प्रकार और Ed25519 कर्व वाले JWK में बस इतना ही होता है।

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) की तुलना JWKS के kid (abc) से कर दी। केवल # के बाद वाले फ़्रैगमेंट की तुलना करें। अगर फ़्रैगमेंट फिर भी मेल न खाए, तो टोकन बनने के बाद जारीकर्ता ने कुंजियाँ बदली हो सकती हैं; DID डॉक्यूमेंट फ़ेच करें और उसकी verificationMethod एंट्रियाँ देखें।

अभी डाउनलोड किए टोकन पर सिग्नेचर अमान्य। जाँचें कि आपने header.payload को मूल base64url टेक्स्ट के रूप में verify किया है, दोबारा एन्कोड किए गए JSON के रूप में नहीं। JSON को दोबारा सीरियलाइज़ करने से बाइट्स बदल जाते हैं और सिग्नेचर टूट जाता है। साथ ही डाउनलोड किए टोकन के अंत में नई लाइन तो नहीं है, यह भी देखें।

एल्गोरिदम कन्फ़्यूज़न। क्लासिक JWT हमला वह टोकन है जो alg: none का दावा करता है या किसी सिमेट्रिक एल्गोरिदम पर स्विच कर देता है, ताकि verifier धोखे से उसे स्वीकार कर ले। हमारे सैंपल अपेक्षित एल्गोरिदम EdDSA को हार्ड-कोड करके और बाकी सब को ठुकराकर इससे बचते हैं। टोकन को कभी यह तय न करने दें कि उसका सत्यापन कैसे होगा।

Base64 पैडिंग त्रुटियाँ। JWS बिना पैडिंग वाला base64url इस्तेमाल करता है। Python में पैडिंग वापस जोड़नी पड़ती है (ऊपर दिखाया गया), और Go में URLEncoding नहीं, RawURLEncoding चाहिए।

सिग्नेचर मान्य है, पर क्या credential अब भी ठीक है? सिग्नेचर प्रामाणिकता और अखंडता साबित करता है, वर्तमान स्टेटस नहीं। credential सही ढंग से साइन होकर भी रद्द या समाप्त हो सकता है। पेलोड में exp जाँचें, और आगे बताई गई रद्दीकरण स्थिति भी देखें।

रद्दीकरण को न भूलें

https://badges.ninja से आने वाले हर Open Badges 3.0 credential में W3C Bitstring Status List का पालन करने वाली credentialStatus एंट्री होती है। वह एक status list credential की ओर इशारा करती है जिसे आप /certify-badge/status/<listId> पर फ़ेच कर सकते हैं। जब कोई जारीकर्ता किसी award को रद्द करता है, तो उस लिस्ट में एक बिट पलट जाता है; लिस्ट लगभग एक मिनट कैश रहती है, इसलिए रद्दीकरण verifiers तक जल्दी पहुँचते हैं। लिस्ट को डिकोड करें और credential के statusListIndex पर बिट पढ़ें: 1 का मतलब रद्द, 0 का मतलब सक्रिय। सत्यापन रेफ़रेंस में उस बिट जाँच का एक छोटा Node उदाहरण है।

एक पूर्ण verifier तीन काम करता है: सिग्नेचर का सत्यापन, समाप्ति की जाँच, और रद्दीकरण बिट की जाँच। अगर आप देखना चाहते हैं कि जारीकर्ता की ओर से रद्दीकरण कैसा दिखता है, तो डैशबोर्ड की वह कार्रवाई awards गाइड में बताई गई है।

जब आपको इसकी ज़रूरत नहीं होती

ज़्यादातर प्रोग्राम ओनर यह कोड कभी नहीं लिखेंगे, और यह ठीक है। रोज़मर्रा की जाँच के लिए award का सार्वजनिक पेज https://badges.ninja/awards/<awardId> खोलें और उसे पढ़ें। इस पेज के लिए न साइनअप चाहिए, न key, और यह जारीकर्ता, बैज और स्टेटस दिखाता है। प्राप्तकर्ता अपने सार्वजनिक credential पेज के Download मेनू से Verifiable Credential डाउनलोड भी कर सकते हैं और उसे किसी भी Open Badges 3.0 वॉलेट में इम्पोर्ट कर सकते हैं।

सिग्नेचर जाँच तब मूल्यवान बनती है जब:

  • कोई नियोक्ता या विश्वविद्यालय अपने पास आए credentials की जाँच को स्वचालित करना चाहता है;
  • आप ऐसा रिकॉर्ड सिस्टम बना रहे हैं जो credentials की कॉपियाँ रखता है और यह साबित करना चाहता है कि उनमें बदलाव नहीं हुआ;
  • कोई ऑडिटर इस बात का प्रमाण माँगता है कि आपके credentials स्वतंत्र रूप से verifiable हैं, सिर्फ़ “हमारी वेबसाइट पर भरोसा करें” नहीं।

यहाँ वही API key सेटअप नहीं चाहिए जो जारी करने के लिए इस्तेमाल होता है, क्योंकि ये सभी एंडपॉइंट सार्वजनिक हैं। अगर आप कोड से credentials जारी करना चाहते हैं, तो API क्विकस्टार्ट में key बनाने और पहला award देने की पूरी प्रक्रिया है।

API Keys — empty state

त्वरित संदर्भ

आइटममान
साइन किया हुआ credentialGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
पढ़ने के लिए बिना साइन किया JSONवही URL, ?format=json के साथ
जारीकर्ता DIDdid:web:api.badges.ninja
Public keys/.well-known/jwks.json और /.well-known/did.json
एल्गोरिदमEd25519 (EdDSA)
कुंजी मिलानहेडर kid का फ़्रैगमेंट JWKS kid के बराबर
रद्दीकरणcredentialStatus जो /certify-badge/status/<listId> की ओर इशारा करता है

समापन

Open Badge सिग्नेचर का सत्यापन एक छोटी, यांत्रिक प्रक्रिया है: टोकन फ़ेच करें, एल्गोरिदम तय रखें, थंबप्रिंट से कुंजी खोजें, और पहले दो सेगमेंट पर Ed25519 सिग्नेचर जाँचें। समाप्ति और रद्दीकरण की जाँच जोड़ दें, तो आपके पास ऐसा verifier है जो जारीकर्ता की प्रकाशित कुंजी के अलावा किसी पर भरोसा नहीं करता। यही स्वतंत्रता डिजिटल credential को PDF से ज़्यादा मूल्यवान बनाती है।

अपना पहला verifiable credential जारी करने के लिए तैयार हैं? badges.ninja पर मुफ़्त शुरू करें — विज़ुअल डिज़ाइनर, सार्वजनिक सत्यापन पेज, PDF सर्टिफ़िकेट, Open Badge v2.0 आउटपुट। क्रेडिट कार्ड की ज़रूरत नहीं।

ब्लॉग पर वापस

संबंधित लेख