Skip to Content
PortcullisDocs
Reference

License file format

Specification of the signed Portcullis license file (format v1).

A license file is a text file (.lic) containing an Ed25519-signed JSON envelope. Products must reject any version or algorithm they don't know.

Armor

-----BEGIN PORTCULLIS LICENSE-----
eyJ2IjoxLCJhbGciOiJFZDI1NTE5Iiwia2lkIjoib21mLTIwMjYtMTEiLCJwYXlsb2FkIjoi...
-----END PORTCULLIS LICENSE-----

The body is the standard base64 encoding of the envelope JSON, wrapped at 64 columns. Readers strip the armor lines and all whitespace before decoding.

Envelope

{
  "v": 1,
  "alg": "Ed25519",
  "kid": "omf-2026-11",
  "payload": "<base64url of the claims JSON bytes>",
  "sig": "<base64url Ed25519 signature over the ASCII bytes of 'portcullis-license-v1.' + payload>"
}
FieldDescription
vFormat version. Must be 1.
algMust be "Ed25519".
kidIdentifies the signing key; look it up in the product's keyring.
payloadbase64url of the claims JSON bytes
sigbase64url Ed25519 signature

Signing input

signing input = ASCII bytes of ( "portcullis-license-v1." + payload )
  • The signature covers the encoded payload string exactly as it appears in the envelope, not re-serialised JSON. This avoids canonicalisation bugs across languages.
  • The portcullis-license-v1. domain prefix prevents a signature from any other context being replayed as a license.

Claims

{
  "fid": "0193f2c4-...",
  "iss": "portcullis",
  "iat": "2026-11-14T09:00:00Z",
  "nbf": "2026-11-14T00:00:00Z",
  "exp": "2026-12-14T09:00:00Z",
  "mode": "online",
  "nonce": "b64url-16-bytes",

  "license": {
    "id": "0193...", "type": "time_limited", "status": "active",
    "expiresAt": "2027-11-14T00:00:00Z", "maintenanceExpiresAt": "2027-11-14T00:00:00Z",
    "graceDays": 14, "maxMachines": 2, "checkInIntervalHours": 24
  },
  "product": { "code": "omnifleet" },
  "customer": { "id": "0193...", "name": "Acme Logistics PLC" },
  "machine": { "id": "0193...", "fingerprint": "9f2c...(64 hex)" },
  "entitlements": { "module.trips": true, "limit.vehicles": 500, "edition": "enterprise" }
}
ClaimDescription
fidUnique ID of this issued file (UUIDv7). Sent back as licenseFileId at check-in.
issAlways "portcullis"
iatIssued at (server clock)
nbfNot valid before (= license start)
expFile validity end: the lease end for online files, normally the license end for offline files
modeonline or offline
nonceEchoed from the request (online) or the request file (offline)
license.idLicense ID
license.typeperpetual, time_limited or trial
license.statusactive, suspended, revoked or expired
license.expiresAtLicense end, or null for perpetual
license.maintenanceExpiresAtBuilds released after this date are not covered; null = always covered
license.graceDaysGrace period after exp or expiresAt
license.maxMachinesMaximum active machines (0 = unlimited)
license.checkInIntervalHoursCheck-in interval, or null for no check-ins (offline-only)
product.codeMust equal the product's own code
customerCustomer ID and display name
machine.id, machine.fingerprintThe fingerprint must equal the installation's own
entitlementsFeature code โ†’ value. See Entitlements and limits.

All times are RFC 3339 UTC strings. Ignore entitlement codes your build doesn't know.

How exp is set

Fileexp
Online (activation or check-in)min(now + lease_days, license.expiresAt)
Offlinelicense.expiresAt, or now + 10 years for perpetual licenses. Digicom may set an earlier date.
License suspended, revoked or expirednow + 7 days, with license.status set accordingly

Keyrings

Each product has one active Ed25519 signing key at a time, identified by kid (<lowercase key prefix>-<yyyy-mm>, plus -n if rotated twice in a month). Products compile a keyring into each release:

// kid โ†’ raw 32-byte Ed25519 public key, base64url
export const KEYRING: Record<string, string> = {
  // 'omf-2026-11': '<base64url public key>',
};
  • Keep pending, active and retired keys in the keyring; remove revoked keys.
  • Get the keys from GET /client/keys/:productCode at build time, or from the Portcullis team.
  • See Key rotation.

Activation request file (.req)

Produced by offline installations. Standard base64 of this unsigned JSON:

{
  "v": 1, "type": "activation_request", "productCode": "omnifleet",
  "fingerprint": "9f2c...", "nonce": "...", "hostname": "omf-prod-01",
  "platform": "linux-x64", "productVersion": "3.4.0", "createdAt": "2026-11-14T09:00:00Z",
  "licenseKeyHint": "3ZC8D"
}

licenseKeyHint is optional. See Offline activation.

Verification and test vectors

See Verifying license files for the verification steps, the reference Node implementation and the test vectors.

On this page