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>"
}| Field | Description |
|---|---|
v | Format version. Must be 1. |
alg | Must be "Ed25519". |
kid | Identifies the signing key; look it up in the product's keyring. |
payload | base64url of the claims JSON bytes |
sig | base64url Ed25519 signature |
Signing input
signing input = ASCII bytes of ( "portcullis-license-v1." + payload )- The signature covers the encoded
payloadstring 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" }
}| Claim | Description |
|---|---|
fid | Unique ID of this issued file (UUIDv7). Sent back as licenseFileId at check-in. |
iss | Always "portcullis" |
iat | Issued at (server clock) |
nbf | Not valid before (= license start) |
exp | File validity end: the lease end for online files, normally the license end for offline files |
mode | online or offline |
nonce | Echoed from the request (online) or the request file (offline) |
license.id | License ID |
license.type | perpetual, time_limited or trial |
license.status | active, suspended, revoked or expired |
license.expiresAt | License end, or null for perpetual |
license.maintenanceExpiresAt | Builds released after this date are not covered; null = always covered |
license.graceDays | Grace period after exp or expiresAt |
license.maxMachines | Maximum active machines (0 = unlimited) |
license.checkInIntervalHours | Check-in interval, or null for no check-ins (offline-only) |
product.code | Must equal the product's own code |
customer | Customer ID and display name |
machine.id, machine.fingerprint | The fingerprint must equal the installation's own |
entitlements | Feature 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
| File | exp |
|---|---|
| Online (activation or check-in) | min(now + lease_days, license.expiresAt) |
| Offline | license.expiresAt, or now + 10 years for perpetual licenses. Digicom may set an earlier date. |
| License suspended, revoked or expired | now + 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,activeandretiredkeys in the keyring; removerevokedkeys. - Get the keys from
GET /client/keys/:productCodeat 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.