Skip to Content
PortcullisDocs
Integrate (product engineers)

Enforcement guidelines

Evaluate the license state and react to it without ever losing customer data.

Principle: fail open for honest customers, fail closed for forged data. Network trouble never stops a product within lease and grace; invalid signatures always do.

Evaluating the state

Evaluate the stored file on startup, every hour, and after every new file. Check the rows in this order; the first match wins.

StateCondition
not_activatedNo stored file
invalidVerification failed
clock_tamperedSee Clock-tamper check
suspended / revokedclaims.license.status says so
expirednow > exp + graceDays, or the license's expiresAt + graceDays has passed
valid_gracenow > exp, or now > license.expiresAt, but still within grace
validOtherwise, and nbf ≤ now

graceDays and expiresAt come from claims.license. All times are RFC 3339 UTC.

What to do in each state

StateDoDon't
validRun normally
valid_graceShow administrators a persistent banner with the days leftBlock anything
expired, suspended, revoked, invalid, clock_tamperedSwitch to read-only mode. Admin login and the license screen keep working. Show a clear message.Delete or corrupt data. Drop data that is being ingested; buffer it instead.
not_activatedShow the setup / activation screen
Limit reached (limit.*)Block creating moreDisable existing items
Maintenance not coveredRefuse to migrate to the new version and keep the old one runningBrick the install

Also warn administrators when the stored file's exp is less than 7 days away (for example because check-ins have been failing).

Log the reason for invalid (bad signature, unknown kid, wrong product, fingerprint mismatch, malformed) so operators and Digicom support can diagnose it.

Clock-tamper check

Recommended. It stops casual clock rollback from extending a license; it is not meant to stop a determined attacker.

  • Persist lastSeenAt, the maximum wall-clock time observed, in <dataDir>/license.state. Write it at most every 10 minutes, HMAC'd with a key derived from the fingerprint.
  • now < lastSeenAt − 2h → clock_tampered.
  • now < claims.iat − 24h (file issued "in the future") → clock_tampered.
  • A successful online check-in clears the flag. Server time is authoritative, and the new file's iat becomes the new lower bound.

GET /client/time returns the server time for display in diagnostics (for example to show clock skew). It is unsigned; never use it for validation.

On this page