Podpisovanje in preverjanje

badges.ninja objavlja javno kriptografsko identiteto, da lahko tretje strani preverijo poverilnice, ki nosijo digitalni podpis. To je temelj za podporo Open Badges 3.0 / W3C Verifiable Credentials.

Te končne točke so javne in ne zahtevajo avtentikacije. Relativne so glede na https://api.badges.ninja.

Izdajateljev DID

Identiteta izdajatelja platforme je identifikator did:web:

did:web:api.badges.ninja

Po pravilih did:web se to razreši v dokument DID, postrežen na spodnji dobro znani (well-known) poti.

Dokument DID

GET /.well-known/did.json

Vrne dokument DID, ki izpostavlja izdajateljev javni podpisni ključ (Ed25519 JsonWebKey2020) kot svoj assertionMethod.

curl https://api.badges.ninja/.well-known/did.json

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:api.badges.ninja",
  "verificationMethod": [
    {
      "id": "did:web:api.badges.ninja#<kid>",
      "type": "JsonWebKey2020",
      "controller": "did:web:api.badges.ninja",
      "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "<base64url>" }
    }
  ],
  "assertionMethod": ["did:web:api.badges.ninja#<kid>"],
  "authentication": ["did:web:api.badges.ninja#<kid>"]
}

Tip vsebine odziva je application/did+json. Dokument je predpomnljiv (spremeni se le ob rotaciji ključa).

JWKS

Za preverjevalce, ki imajo raje odkrivanje prek JWK Set kot razrešitev DID:

GET /.well-known/jwks.json

curl https://api.badges.ninja/.well-known/jwks.json

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "<base64url>",
      "kid": "<thumbprint>",
      "alg": "EdDSA",
      "use": "sig"
    }
  ]
}

kid je odtis (thumbprint) po RFC 7638 javnega ključa in se ujema s fragmentom na id-ju verificationMethod v dokumentu DID.

Verifiable Credential (Open Badges 3.0)

Vsako priznanje je mogoče pridobiti kot Open Badges 3.0 / W3C Verifiable Credential, podpisano z zgornjim izdajateljevim ključem.

GET /certify-badge/award/{guid}/vc

Poizvedba	Rezultat
(privzeto) ali ?format=jwt	Podpisan VC-JWT (application/jwt) — uvozite v denarnico OB 3.0.
?format=json	Nepodpisan JSON OpenBadgeCredential (application/vc+ld+json) — za pregled.

# Signed credential (VC-JWT)
curl https://api.badges.ninja/certify-badge/award/<guid>/vc

# Human-readable credential JSON
curl "https://api.badges.ninja/certify-badge/award/<guid>/vc?format=json"

Poverilnica je VC tipa ["VerifiableCredential", "OpenBadgeCredential"] (konteksta https://www.w3.org/ns/credentials/v2 in kontekst OB 3.0). Njen issuer.id je did:web:api.badges.ninja, dosežek, identiteta prejemnika (zgoščena e-pošta) ter datuma izdaje/poteka pa izvirajo iz priznanja.

Preverjanje VC-JWT

Žeton je kompaktni JWS s podpisom EdDSA. Za preverjanje:

1. Razdelite JWT na header.payload.signature.
2. Preberite kid iz glave — ta kaže v dokument DID / JWKS.
3. Pridobite javni ključ in preverite podpis Ed25519 nad header.payload.

import crypto from "node:crypto";

const [h, p, s] = jwt.split(".");
const jwks = await (await fetch("https://api.badges.ninja/.well-known/jwks.json")).json();
const jwk = jwks.keys[0];
const pub = crypto.createPublicKey({ key: jwk, format: "jwk" });
const ok = crypto.verify(null, Buffer.from(`${h}.${p}`), pub, Buffer.from(s, "base64url"));

Prejemniki lahko poverilnico prevzamejo tudi iz menija Download na svoji javni strani poverilnice (Verifiable Credential).

Algoritem podpisa

Podpisi uporabljajo Ed25519 (EdDSA). Zasebni ključ je hranjen na strežniku in ni nikoli izpostavljen; objavljen je le zgornji javni ključ.

Gostovano preverjanje (Open Badges 2.0)

Vsaka poverilnica je danes tudi neodvisno preverljiva prek svoje gostovane trditve Open Badge 2.0. Za končne točke JSON trditve, značke in izdajatelja glejte Javno preverjanje, za prejemniku namenjeno stran preverjanja pa Deljenje in preverjanje.