Pasirašymas ir tikrinimas

badges.ninja skelbia viešą kriptografinę tapatybę, kad trečiosios šalys galėtų patikrinti kredencialus, turinčius skaitmeninį parašą. Tai yra Open Badges 3.0 / W3C Verifiable Credentials palaikymo pagrindas.

Šie galiniai taškai yra vieši ir nereikalauja autentikavimo. Jie yra santykiniai https://api.badges.ninja atžvilgiu.

Išdavėjo DID

Platformos išdavėjo tapatybė yra did:web identifikatorius:

did:web:api.badges.ninja

Pagal did:web taisykles, tai išsprendžiama į DID dokumentą, aptarnaujamą žemiau esančiame gerai žinomame kelyje.

DID dokumentas

GET /.well-known/did.json

Grąžina DID dokumentą, atskleidžiantį išdavėjo viešąjį pasirašymo raktą (Ed25519 JsonWebKey2020) kaip jo 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>"]
}

Atsakymo turinio tipas yra application/did+json. Dokumentas yra talpinamas talpykloje (jis keičiasi tik pakeitus raktą).

JWKS

Tikrintojams, kurie renkasi JWK Set aptikimą, o ne DID sprendimą:

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 yra RFC 7638 viešojo rakto atspaudas (thumbprint) ir atitinka fragmentą DID dokumento verificationMethod id.

Tikrinamas kredencialas (Open Badges 3.0)

Kiekvieną apdovanojimą galima gauti kaip Open Badges 3.0 / W3C Verifiable Credential, pasirašytą aukščiau esančiu išdavėjo raktu.

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

Užklausa	Rezultatas
(numatytasis) arba ?format=jwt	Pasirašytas VC-JWT (application/jwt) — importuokite į OB 3.0 piniginę.
?format=json	Nepasirašytas OpenBadgeCredential JSON (application/vc+ld+json) — apžiūrai.

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

Kredencialas yra ["VerifiableCredential", "OpenBadgeCredential"] tipo VC (kontekstai https://www.w3.org/ns/credentials/v2 ir OB 3.0 kontekstas). Jo issuer.id yra did:web:api.badges.ninja, o pasiekimas, gavėjo tapatybė (maišos būdu užšifruotas el. paštas) ir išdavimo/galiojimo datos gaunami iš apdovanojimo.

VC-JWT tikrinimas

Žetonas yra kompaktiškas JWS su EdDSA parašu. Norėdami patikrinti:

1. Padalinkite JWT į header.payload.signature.
2. Nuskaitykite kid iš antraštės — jis nurodo į DID dokumentą / JWKS.
3. Gaukite viešąjį raktą ir patikrinkite Ed25519 parašą virš 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"));

Gavėjai kredencialą taip pat gali gauti iš Download meniu savo viešame kredencialo puslapyje (Verifiable Credential).

Parašo algoritmas

Parašai naudoja Ed25519 (EdDSA). Privatus raktas saugomas serverio pusėje ir niekada neatskleidžiamas; skelbiamas tik aukščiau esantis viešasis raktas.

Aptarnaujamas tikrinimas (Open Badges 2.0)

Kiekvienas kredencialas šiandien taip pat nepriklausomai patikrinamas per jo aptarnaujamą Open Badge 2.0 teiginį (assertion). Žr. Viešas tikrinimas dėl teiginio, ženklelio ir išdavėjo JSON galinių taškų, bei Bendrinimas ir tikrinimas dėl gavėjui skirto tikrinimo puslapio.