Skip to content

License Security

Trust model

  • The private signing key lives only on the licensing server.
  • The panel and agents hold only the pinned Ed25519 public key(s), identified by kid. Key rotation adds a new kid; unknown kids are rejected.
  • TLS certificate verification is always on. There is no option to disable it and no way to point the verifier at an unpinned key.

What is verified

Every signed lease is checked in this order (all mandatory):

  1. Signature envelope decodes (base64url, 64 bytes).
  2. Certificate decodes to JSON.
  3. kid is a pinned trusted key.
  4. Ed25519 signature over the exact certificate bytes.
  5. schema_version supported.
  6. Product matches.
  7. installation_id / fingerprint binding matches this installation.
  8. not_before not in the future.
  9. Status is known.
  10. Entitlements and lease_generation parse.

Any failure is a verification exception; the caller fails closed. A newer signed SUSPENDED/REVOKED state always overrides an older ACTIVE state.

Release manifest (integrity)

The integrity service verifies a signed release manifest before trusting any file hash. The manifest pins the license protocol version, trusted key ids and SHA-256 hashes of security-critical files. A modified critical file or manifest yields TAMPER_SUSPECTED and locks the protected functionality. A missing manifest is reported as MISSING (not silently PASS).

Security events

Recorded with no key material and no signature bytes:

LICENSE_SIGNATURE_INVALID, LICENSE_CACHE_TAMPER, LICENSE_INSTALLATION_MISMATCH, LICENSE_INTEGRITY_FAILURE, LICENSE_CLOCK_ANOMALY, LICENSE_STATE_TRANSITION (audit).

Honest limitations

This is tamper resistance, not an impossible guarantee:

  • A user with root on the host can patch both the application code and the verifier, and can rewrite the manifest. No client-side scheme can prevent that. The signed lease, server-authoritative suspend/revoke and the installation binding make tampering detectable and inconvenient, and they stop casual copying, but they are not cryptographic proof against a root adversary.
  • Nothing here is claimed to be "uncrackable".
  • Licensing never destroys customer data as a DRM measure, so an attacker who patches the client does not put customer workloads at risk — they only obtain an unlicensed control plane.

Operational hardening

  • Pin the public key via environment (KRAPPLE_PUBLIC_KEY, KRAPPLE_KID).
  • Keep the license key in a 0600 file or a secrets manager, never in git.
  • Ship the signed release manifest and verify it on boot and in CI.
  • Alert on the security events above.