Allekirjoitus ja vahvistus

badges.ninja julkaisee julkisen kryptografisen identiteetin, jotta kolmannet osapuolet voivat vahvistaa todistuksia, joissa on digitaalinen allekirjoitus. Tämä on perusta Open Badges 3.0:n / W3C Verifiable Credentialsin tuelle.

Nämä päätepisteet ovat julkisia eivätkä vaadi todennusta. Ne ovat suhteessa osoitteeseen https://api.badges.ninja.

Myöntäjän DID

Alustan myöntäjäidentiteetti on did:web-tunniste:

did:web:api.badges.ninja

did:web-sääntöjen mukaan tämä ratkeaa DID-dokumentiksi, joka tarjoillaan alla olevassa tunnetussa polussa.

DID-dokumentti

GET /.well-known/did.json

Palauttaa DID-dokumentin, joka paljastaa myöntäjän julkisen allekirjoitusavaimen (Ed25519 JsonWebKey2020) sen assertionMethod-arvona.

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

Vastauksen sisältötyyppi on application/did+json. Dokumentti on välimuistiin tallennettavissa (se muuttuu vain avaimen kierrätyksessä).

JWKS

Vahvistajille, jotka suosivat JWK Set -löytämistä DID-ratkaisun sijaan:

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 julkisen avaimen RFC 7638 -tiiviste ja vastaa DID-dokumentin verificationMethod-tunnuksen fragmenttia.

Vahvistettava todistus (Open Badges 3.0)

Jokainen myönnetty todistus voidaan hakea Open Badges 3.0:n / W3C Verifiable Credentialin muodossa, allekirjoitettuna yllä olevalla myöntäjän avaimella.

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

Kysely	Tulos
(oletus) tai ?format=jwt	Allekirjoitettu VC-JWT (application/jwt) — tuo OB 3.0 -lompakkoon.
?format=json	Allekirjoittamaton OpenBadgeCredential-JSON (application/vc+ld+json) — tarkastelua varten.

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

Todistus on ["VerifiableCredential", "OpenBadgeCredential"]-tyyppinen VC (kontekstit https://www.w3.org/ns/credentials/v2 ja OB 3.0 -konteksti). Sen issuer.id on did:web:api.badges.ninja, ja saavutus, vastaanottajan identiteetti (tiivistetty sähköposti) sekä myöntämis-/vanhenemispäivät tulevat myönnetystä todistuksesta.

VC-JWT:n vahvistaminen

Token on kompakti JWS, jossa on EdDSA-allekirjoitus. Vahvistaaksesi:

1. Jaa JWT osiin header.payload.signature.
2. Lue kid otsikosta — se osoittaa DID-dokumenttiin / JWKS.
3. Hae julkinen avain ja vahvista Ed25519-allekirjoitus arvon header.payload yli.

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

Vastaanottajat voivat myös hakea todistuksen julkisen todistussivunsa Download-valikosta (Verifiable Credential).

Allekirjoitusalgoritmi

Allekirjoitukset käyttävät Ed25519-algoritmia (EdDSA). Yksityinen avain säilytetään palvelinpuolella eikä sitä koskaan paljasteta; vain yllä oleva julkinen avain julkaistaan.

Isännöity vahvistus (Open Badges 2.0)

Jokainen todistus on myös itsenäisesti vahvistettavissa jo nyt isännöidyn Open Badge 2.0 -assertionsa kautta. Katso Julkinen vahvistus assertion-, badge- ja myöntäjä-JSON-päätepisteitä varten, ja Jakaminen ja vahvistus vastaanottajalle näkyvää vahvistussivua varten.