Allkirjastamine ja kontrollimine

badges.ninja avaldab avaliku krüptograafilise identiteedi, et kolmandad osapooled saaksid kontrollida digitaalallkirja kandvaid tunnistusi. See on aluseks Open Badges 3.0 / W3C Verifiable Credentials toele.

Need otspunktid on avalikud ega nõua autentimist. Need on suhtelised aadressiga https://api.badges.ninja.

Väljastaja DID

Platvormi väljastaja identiteet on did:web identifikaator:

did:web:api.badges.ninja

did:web reeglite kohaselt laheneb see DID-dokumendiks, mida serveeritakse allpool asuval üldtuntud (well-known) teel.

DID-dokument

GET /.well-known/did.json

Tagastab DID-dokumendi, mis avaldab väljastaja avaliku allkirjastamisvõtme (Ed25519 JsonWebKey2020) oma assertionMethod-ina.

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

Vastuse sisutüüp on application/did+json. Dokument on vahemällu salvestatav (see muutub ainult võtme rotatsioonil).

JWKS

Kontrollijatele, kes eelistavad DID-lahenduse asemel JWK Set avastamist:

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 on avaliku võtme RFC 7638 sõrmejälg ja vastab DID-dokumendi verificationMethod id-l olevale fragmendile.

Kontrollitav tunnistus (Open Badges 3.0)

Iga autasu saab hankida Open Badges 3.0 / W3C Verifiable Credential-ina, mis on allkirjastatud ülaltoodud väljastaja võtmega.

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

Päring	Tulemus
(vaikimisi) või ?format=jwt	Allkirjastatud VC-JWT (application/jwt) — impordi OB 3.0 rahakotti.
?format=json	Allkirjastamata OpenBadgeCredential JSON (application/vc+ld+json) — kontrollimiseks.

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

Tunnistus on ["VerifiableCredential", "OpenBadgeCredential"] tüüpi VC (kontekstid https://www.w3.org/ns/credentials/v2 ja OB 3.0 kontekst). Selle issuer.id on did:web:api.badges.ninja ning saavutus, saaja identiteet (räsitud e-post) ja väljastamis-/aegumiskuupäevad pärinevad autasust.

VC-JWT kontrollimine

Token on kompaktne JWS EdDSA allkirjaga. Kontrollimiseks:

1. Jaga JWT osadeks header.payload.signature.
2. Loe päisest kid — see osutab DID-dokumenti / JWKS-i.
3. Hangi avalik võti ja kontrolli Ed25519 allkirja header.payload üle.

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

Saajad saavad tunnistuse hankida ka oma avaliku tunnistuse lehel asuvast menüüst Download (Verifiable Credential).

Allkirja algoritm

Allkirjad kasutavad Ed25519 (EdDSA). Privaatvõtit hoitakse serveripoolel ega paljastata kunagi; avaldatakse ainult ülaltoodud avalik võti.

Hostitud kontrollimine (Open Badges 2.0)

Iga tunnistus on ka juba täna sõltumatult kontrollitav oma hostitud Open Badge 2.0 kinnituse (assertion) kaudu. Vt Avalik kontrollimine kinnituse, märgi ja väljastaja JSON-otspunktide kohta ning Jagamine ja kontrollimine saajale suunatud kontrollimislehe kohta.