簽署與驗證

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

回傳 DID 文件,將頒發者的公開簽署金鑰(一個 Ed25519 JsonWebKey2020)作為其 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>"]
}

回應內容類型為 application/did+json。該文件可快取(它僅在金鑰輪換時變更)。

JWKS

對於較傾向使用 JWK Set 探索而非 DID 解析的驗證者:

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 端點,請參見 公開驗證;關於面向接收者的驗證頁面,請參見 分享與驗證。