Aláírás és ellenőrzés

A badges.ninja nyilvános kriptográfiai identitást tesz közzé, hogy harmadik felek ellenőrizhessék a digitális aláírással ellátott hitelesítő adatokat. Ez az alapja az Open Badges 3.0 / W3C Verifiable Credentials támogatásnak.

Ezek a végpontok nyilvánosak, és nem igényelnek hitelesítést. A https://api.badges.ninja címhez viszonyítottak.

Kibocsátó DID

A platform kibocsátói identitása a did:web azonosító:

did:web:api.badges.ninja

A did:web szabályai szerint ez az alábbi well-known útvonalon kiszolgált DID-dokumentumra oldódik fel.

DID-dokumentum

GET /.well-known/did.json

Visszaadja a DID-dokumentumot, amely a kibocsátó nyilvános aláíró kulcsát (egy Ed25519 JsonWebKey2020) az assertionMethod értékeként teszi közzé.

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

A válasz tartalomtípusa application/did+json. A dokumentum gyorsítótárazható (csak kulcsrotációkor változik).

JWKS

Azoknak az ellenőrzőknek, akik a JWK Set felfedezést részesítik előnyben a DID-feloldással szemben:

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

A kid a nyilvános kulcs RFC 7638 szerinti ujjlenyomata, és megegyezik a DID-dokumentum verificationMethod azonosítóján lévő fragmentummal.

Ellenőrizhető hitelesítő adat (Open Badges 3.0)

Minden díj lekérhető Open Badges 3.0 / W3C Verifiable Credential formában, a fenti kibocsátói kulccsal aláírva.

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

Lekérdezés	Eredmény
(alapértelmezett) vagy ?format=jwt	Az aláírt VC-JWT (application/jwt) — importáld egy OB 3.0 tárcába.
?format=json	Az aláíratlan OpenBadgeCredential JSON (application/vc+ld+json) — vizsgálathoz.

# 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"

A hitelesítő adat egy ["VerifiableCredential", "OpenBadgeCredential"] típusú VC (a https://www.w3.org/ns/credentials/v2 és az OB 3.0 kontextusok). Az issuer.id értéke did:web:api.badges.ninja, a teljesítmény, a címzett identitása (hashelt e-mail) és a kiállítási/lejárati dátumok pedig a díjból származnak.

Egy VC-JWT ellenőrzése

A token egy kompakt JWS EdDSA aláírással. Az ellenőrzéshez:

1. Oszd fel a JWT-t header.payload.signature részekre.
2. Olvasd ki a kid értéket a fejlécből — ez a DID-dokumentumra / JWKS mutat.
3. Kérd le a nyilvános kulcsot, és ellenőrizd az Ed25519 aláírást a header.payload felett.

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

A címzettek a hitelesítő adatot a nyilvános hitelesítőoldaluk Download menüjéből is megszerezhetik (Verifiable Credential).

Aláírási algoritmus

Az aláírások Ed25519 (EdDSA) algoritmust használnak. A privát kulcsot a szerver oldalon őrizzük, és soha nem tesszük közzé; csak a fenti nyilvános kulcs kerül közzétételre.

Tárolt ellenőrzés (Open Badges 2.0)

Minden hitelesítő adat ma is önállóan ellenőrizhető a tárolt Open Badge 2.0 tanúsítványán keresztül. Lásd a Nyilvános ellenőrzés oldalt a tanúsítvány, jelvény és kibocsátó JSON-végpontjaihoz, valamint a Megosztás és ellenőrzés oldalt a címzetteknek szóló ellenőrzőoldalhoz.