署名と検証

badges.ninja は公開された暗号学的アイデンティティを公開しており、第三者がデジタル署名を持つクレデンシャルを検証できます。これは Open Badges 3.0 / W3C Verifiable Credentials 対応の基盤です。

これらのエンドポイントは 公開 されており、認証は不要です。https://api.badges.ninja を基準とします。

発行者 DID

プラットフォームの発行者アイデンティティは did:web 識別子です:

did:web:api.badges.ninja

did:web のルールにより、これは下記の well-known パスで提供される DID ドキュメントに解決されます。

DID ドキュメント

GET /.well-known/did.json

発行者の公開署名鍵(Ed25519 の JsonWebKey2020)を assertionMethod として公開する DID ドキュメントを返します。

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

レスポンスのコンテンツタイプは application/did+json です。このドキュメントはキャッシュ可能です(鍵のローテーション時にのみ変更されます)。

JWKS

DID 解決よりも JWK Set ディスカバリを好む検証者向け:

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 は公開鍵の RFC 7638 サムプリントであり、DID ドキュメントの verificationMethod id のフラグメントと一致します。

検証可能なクレデンシャル(Open Badges 3.0)

すべてのアワードは、上記の発行者鍵で署名された Open Badges 3.0 / W3C Verifiable Credential として取得できます。

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

クエリ	結果
(デフォルト) または ?format=jwt	署名済みの VC-JWT(application/jwt)——OB 3.0 ウォレットにインポートします。
?format=json	未署名の OpenBadgeCredential JSON(application/vc+ld+json)——確認用。

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

このクレデンシャルは ["VerifiableCredential", "OpenBadgeCredential"] 型の VC です(コンテキストは https://www.w3.org/ns/credentials/v2 と OB 3.0 コンテキスト)。その issuer.id は did:web:api.badges.ninja であり、アチーブメント、受信者アイデンティティ(ハッシュ化されたメール)、発行/有効期限の日付はアワードから取得されます。

VC-JWT の検証

このトークンは EdDSA 署名を持つコンパクトな JWS です。検証するには:

1. JWT を header.payload.signature に分割します。
2. header から kid を読み取ります——これは DID ドキュメント / JWKS を指します。
3. 公開鍵を取得し、header.payload に対する Ed25519 署名を検証します。

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

受信者は、公開クレデンシャルページの Download メニューからもクレデンシャルを取得できます(Verifiable Credential)。

署名アルゴリズム

署名には Ed25519(EdDSA)を使用します。秘密鍵はサーバー側で保管され、決して公開されません。公開されるのは上記の公開鍵のみです。

ホステッド検証(Open Badges 2.0)

すべてのクレデンシャルは、ホストされた Open Badge 2.0 アサーションを通じて、現在も独立して検証可能です。アサーション、バッジ、発行者の JSON エンドポイントについては 公開検証 を、受信者向けの検証ページについては 共有と検証 を参照してください。