DocumentationLicense model

License model

License model

Ed25519 JWS license format, offline verification by agent and server, grace and offline days, revocation. Never any network dependency to check an entitlement.

A MaelGard license is a token signed by the vendor, verified locally by the agent and the server, with no network. The vendor license service only issues and revokes. Its unavailability never blocks startup or protection.

Token format

  • Envelope: compact JWS (RFC 7515).
  • Algorithm: EdDSA on Ed25519.
  • Header: kid identifies the signing key for rotation; cty = maelgard-license.
  • Size: a few hundred bytes to a few kilobytes.
  • Transport: .lic text file, database text column, HTTP header.

Payload fields

JSON payload of a MaelGard license (spec section 3.1).
FieldTypeDescription
license_idUUIDUnique identifier, used for revocation.
schema_versionintegerLicense format version.
tenant_idstringTarget tenant, must match the server tenant.
customer_namestringLegal name, for display.
editionenumstandard or advanced. Baseline features.
seatsintegerAllowed number of endpoints.
seat_overageintegerOverage tolerance before any effect.
modelsarrayPaid models: id and max major version.
channelsarrayAllowed channels, when the offering restricts them.
featuresarrayEnabled options (SIEM export, public API, etc.).
not_beforedateStart of validity (ISO 8601).
not_afterdateEnd of validity.
grace_daysintegerGrace days after not_after (default 30).
offline_daysintegerDays without refresh before a warning.
hard_stopbooleanAllows a blocking effect. false by default: alerts only.
issued_atdateIssuance, for anti-replay: newest wins.
issuerstringIdentifier of the signing key used.

Example payload

{
  "license_id": "a3f1b2c4-5d6e-4f78-9a0b-1c2d3e4f5a6b",
  "schema_version": 1,
  "tenant_id": "example-bank",
  "customer_name": "Example Bank Ltd.",
  "edition": "advanced",
  "seats": 1000,
  "seat_overage": 100,
  "models": [
    { "id": "pii", "max_major_version": 1 },
    { "id": "health", "max_major_version": 0 },
    { "id": "finance", "max_major_version": 2 }
  ],
  "channels": ["web", "desktop", "api", "code_assistant"],
  "features": ["siem_export", "public_api"],
  "not_before": "2026-10-01",
  "not_after":  "2027-09-30",
  "grace_days": 30,
  "offline_days": 60,
  "hard_stop": false,
  "issued_at": "2026-09-15T10:00:00Z",
  "issuer": "mgl-2026"
}

Verification on the agent

The agent and the server use the same shared crate maelgard-license to avoid any divergence. Verification runs in six steps.

  1. Verify the JWS signature with the embedded public key matching the kid.
  2. Check that tenant_id matches the local tenant configuration.
  3. Check not_before ≤ now ≤ not_after + grace_days, with clock protection.
  4. Check that the license is not in the cached revocation list.
  5. Pick, among several present licenses, the one with the most recent issued_at.
  6. Derive effective rights (seats, models, channels, options).
License states after verification.
StateMeaning
validLicense effective, entitlements active.
expiredBeyond not_after + grace_days.
revokedListed in the revocation set.
wrong_tenantTenant mismatch.
bad_signatureInvalid signature or unknown key.
unknown_versionUnsupported major version.
absentNo license imported, evaluation mode.

Clock protection

Offline verification depends on the local clock, which a user can roll back. Verification protects itself without ever needing the network.

  • Monotonic marker: the product stores the most recent timestamp observed from a trusted source (integrity anchor, server heartbeat).
  • Maximum: the time used for verification is the maximum of system clock and marker.
  • Detection: a rollback beyond a threshold is flagged as tampering, without blocking protection.
  • Fast forward is pointless: moving the clock forward brings no advantage. Expiry only removes features when hard_stop is true.

Grace and offline days

Two distinct windows.
ParameterRoleEffect
grace_daysDays after not_after where the license stays fully effective.Visible warning, no feature removed. Default 30.
offline_daysDays without refresh before an admin warning.Admin warning only, no impact on protection.

Revocation

  • The vendor publishes a signed revocation list (JWS, cty = maelgard-license-revocations), timestamped and incremental.
  • The list is distributed to clients by the aggregation server, and by file for isolated sites.
  • An offline client that has never received a revocation keeps honouring its latest valid license, until the list arrives.
  • Revocation handles fraud or termination, not routine business. The regular lever is still the expiry date.

Administrator CLI

On the agent and server, routine operations go through dlpia-admin on the endpoint and through the server console. On the vendor side, maelgard-license issues, verifies and revokes.

# License status on an endpoint
dlpia-admin license status

# Local import (file pushed by GPO or Intune)
dlpia-admin license import C:\ProgramData\DLPIA\licenses\bank.lic

# Purge the license cache (back to evaluation or absent)
dlpia-admin license purge

# Local file verification
maelgard-license verify bank.lic --public-key keys/mgl-2026.pub
Exit codes of dlpia-admin license import.
CodeMeaning
0License imported successfully.
1Unreadable file or invalid syntax.
2Invalid signature or unknown public key.
3Incorrect tenant for this endpoint.
4License expired beyond grace.
5License revoked.
6Unsupported schema version.
7License older than one already in cache.

Issuance on the vendor side

Issuance signs the token with the license private key held in an HSM (OpenBao Transit). The key never leaves the HSM.

maelgard-license issue \
  --tenant example-bank \
  --edition advanced \
  --seats 1000 \
  --seat-overage 100 \
  --models pii@1,health@0,finance@2 \
  --channels web,desktop,api,code_assistant \
  --features siem_export,public_api \
  --not-before 2026-10-01 \
  --not-after  2027-09-30 \
  --grace-days 30 \
  --offline-days 60 \
  --out bank-2026.lic
  • Every issued license is logged (id, customer, scope, dates) in a registry for monitoring and audit.
  • The service validates every order against the offering catalog before issuing.
  • The signing key is separate from Authenticode, catalog and endpoint CA keys. A compromise only affects it.

Public key rotation

The agent and server embed the current and previous keys. Both are accepted during the transition. The token header carries the kid of the key in use.

# Rotate on the vendor side (OpenBao)
bao write -f transit/keys/maelgard-license/rotate

# Then publish the new public key to the agent and server teams
maelgard-license-service signer current-public-key \
  --token-file deploy/prod/secrets/keyadmin.token

Troubleshooting

Common error messages on import.
MessageLikely causeAction
"License not authentic"Embedded public key does not match the kid in the token.Upgrade the agent or server with the new public key.
"Invalid tenant"The token tenant_id does not match the endpoint configuration.Check the MSI property TENANT_ID or the server tenant.
"License expired"Date past not_after + grace_days.Request a new license from the vendor.
"License revoked"The license_id is in the cached revocation list.Contact vendor support.
"Unsupported schema version"The token uses a newer schema_version than the binary.Upgrade the agent or server.
"License older"The issued_at is older than the cached license.Import the most recent license.
"Clock ahead"The monotonic marker is greater than the system clock.Resynchronise the clock and wait for the next verification.

Evaluation mode

Before any import, the product runs in evaluation: baseline edition, 10 endpoints, free models, 30 days, clearly displayed. End of evaluation follows the same rule as expiry: never exposure, only paid features removed and alerts raised.