Skip to main content

Security

:::info Source Sourced from services/certification-service/SECURITY_MODEL.md in the documentation repo. :::

1. Authentication​

  • JWT for internal; public /verify/{token} unauthenticated.
  • S2S mTLS for certificate issuance worker.

2. Authorization​

Roles:

  • certification:issue — worker (internal service account).
  • certification:revoke — compliance_officer, platform_admin, org_admin.
  • certification:template:write — org_admin, provider_admin.
  • certification:read — learner (own), admin.

3. Multi-Tenant Isolation​

  • RLS on all tables (except verification audit + public verify).
  • Public verify narrows to non-PII columns; tenant inferred from certificate.

4. JWS Proof​

  • Per-tenant HSM-backed signing key.
  • Algorithm: EdDSA (Ed25519).
  • kid rotation annual; overlap ≥ 2 days.
  • JWKS published at /api/v1/.well-known/certification-keys.json (CDN-cached 5 min).
  • Verification library validates against JWKS.

5. Verification Token​

  • ULID; HMAC fingerprint (HMAC-SHA256 with tenant secret).
  • Unguessable (256-bit entropy).
  • Exposed via QR code + human-readable (e.g., vt_01H...).
  • Lookup: O(1) via UNIQUE index.

6. Offline Issuance Integrity​

  • localSignature = JWS signed by bundle key (derived from tenant + device).
  • Server verifies by re-deriving bundle key from tenant key + device pubkey.
  • Signature includes attemptId, completedAt, score, localNonce.
  • Replay protection: nonce tracked; duplicate claims rejected.
  • Clock-skew tolerance ±24h on localCompletedAt.

7. Artifact URLs​

  • Signed URLs TTL 10 min on PDF/PNG.
  • OpenBadges 3.0 VC JSON-LD — publicly fetchable via verifier (CDN-cached).
  • Wallet pass files signed with platform wallet-signing key.

8. Audit Logging​

  • Every issuance, revocation, verification logged.
  • Merkle-anchored daily.
  • Tamper-evident: any post-hoc edit to certificates detectable.

9. Threat Model​

ThreatMitigation
Forged certificateJWS proof + tenant signing key; public JWKS
Token guessingULID + HMAC fingerprint; rate limit; 256-bit entropy
Enumeration via /verifyRate limit per IP; 10k/min per tenant
Offline claim forgeryBundle key signature; nonce replay protection
Mass issuance abuseRate limit per tenant; AI anomaly detection (M5)
Template layout XSS (rendered PDF)Headless Chrome sandbox; HTML sanitization before render
Cross-tenant certificate lookupPublic verify only exposes tenant-owned data
GDPR tension (retention vs deletion)Anonymize user PII; keep course + tenant + existence (policy)

10. Compliance​

  • Certificates indefinite retention (except anonymization).
  • OpenBadges 3.0 VC for interop.
  • FERPA for education tenants.
  • Legal hold overrides GDPR for disputed certificates.

11. Secret Management​

  • Signing keys in KMS (HSM-backed).
  • Verification token HMAC secret per tenant, KMS-wrapped.
  • Rotation procedure documented; coordinated with public key cache.