Parakstīšana un pārbaude

badges.ninja publicē publisku kriptogrāfisko identitāti, lai trešās puses varētu pārbaudīt akreditācijas datus, kas satur digitālu parakstu. Tas ir pamats Open Badges 3.0 / W3C Verifiable Credentials atbalstam.

Šie galapunkti ir publiski un neprasa autentifikāciju. Tie ir relatīvi pret https://api.badges.ninja.

Izsniedzēja DID

Platformas izsniedzēja identitāte ir did:web identifikators:

did:web:api.badges.ninja

Saskaņā ar did:web noteikumiem tas atrisinās uz DID dokumentu, kas tiek apkalpots zemāk norādītajā labi zināmajā ceļā.

DID dokuments

GET /.well-known/did.json

Atgriež DID dokumentu, kas atklāj izsniedzēja publisko parakstīšanas atslēgu (Ed25519 JsonWebKey2020) kā tā 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>"]
}

Atbildes satura tips ir application/did+json. Dokuments ir kešojams (tas mainās tikai atslēgas rotācijas gadījumā).

JWKS

Pārbaudītājiem, kas dod priekšroku JWK Set atklāšanai, nevis DID atrisināšanai:

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 ir publiskās atslēgas RFC 7638 pirkstu nospiedums un atbilst fragmentam DID dokumenta verificationMethod id.

Pārbaudāmi akreditācijas dati (Open Badges 3.0)

Katru apbalvojumu var iegūt kā Open Badges 3.0 / W3C Verifiable Credential, kas parakstīts ar iepriekš norādīto izsniedzēja atslēgu.

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

Vaicājums	Rezultāts
(noklusējums) vai ?format=jwt	Parakstītais VC-JWT (application/jwt) — importējiet OB 3.0 makā.
?format=json	Neparakstītais OpenBadgeCredential JSON (application/vc+ld+json) — apskatei.

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

Akreditācijas dati ir ["VerifiableCredential", "OpenBadgeCredential"] tipa VC (konteksti https://www.w3.org/ns/credentials/v2 un OB 3.0 konteksts). Tā issuer.id ir did:web:api.badges.ninja, un sasniegums, saņēmēja identitāte (hešots e-pasts) un izsniegšanas/derīguma termiņa datumi nāk no apbalvojuma.

VC-JWT pārbaude

Marķieris ir kompakts JWS ar EdDSA parakstu. Lai pārbaudītu:

1. Sadaliet JWT daļās header.payload.signature.
2. Nolasiet kid no galvenes — tas norāda uz DID dokumentu / JWKS.
3. Iegūstiet publisko atslēgu un pārbaudiet Ed25519 parakstu virs 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"));

Saņēmēji var arī iegūt akreditācijas datus no Download izvēlnes savā publiskajā akreditācijas datu lapā (Verifiable Credential).

Paraksta algoritms

Paraksti izmanto Ed25519 (EdDSA). Privātā atslēga tiek glabāta servera pusē un nekad netiek atklāta; tiek publicēta tikai iepriekš norādītā publiskā atslēga.

Mitināta pārbaude (Open Badges 2.0)

Katrs akreditācijas dokuments jau šodien ir arī neatkarīgi pārbaudāms, izmantojot tā mitināto Open Badge 2.0 apliecinājumu. Skatiet Publiskā pārbaude apliecinājuma, nozīmes un izsniedzēja JSON galapunktiem, un Kopīgošana un pārbaude saņēmējam paredzētajai pārbaudes lapai.