Key rotation
Ship signing-key keyrings in your builds, and keep check-ins working after license key rotation.
Two different keys can rotate. They affect your product differently.
Signing key (kid) | License key (OMF-…) | |
|---|---|---|
| What it is | Per-product Ed25519 key pair that signs license files | Per-license secret used for online activation |
| Your build needs | The public keys in a compiled keyring | Nothing |
| Your runtime needs | Look up kid in the keyring | Send licenseFileId with every check-in |
Signing keys and keyrings
Each product has exactly one active signing key. The kid is the lowercase license key
prefix plus the year and month, for example omf-2026-11 (with -n added if rotated twice in a
month).
Key states:
| State | Signs new files | Keep in your keyring |
|---|---|---|
pending | No (activated later) | Yes: ship it ahead of the rotation |
active | Yes | Yes |
retired | No | Yes: older files are still signed with it |
revoked | No | No: remove it in your next release; files signed with it then fail |
Compile the keyring into each release as { kid → publicKey }. Get it from the Portcullis team,
or build it from the public endpoint at build time:
curl -sS "https://<portcullis-api-host>/api/v1/client/keys/omnifleet"{
"status": "success",
"data": {
"keys": [
{ "kid": "omf-2026-11", "algorithm": "Ed25519", "publicKey": "<base64url, 32 bytes>", "status": "active" }
]
}
}The endpoint returns active, pending and retired keys.
Use this endpoint at build time only. Verifying files with keys fetched at runtime would let a fake server sign its own files.
Routine rotation
- Digicom generates the next key in
pendingstate. - You ship a product release whose keyring includes the pending key.
- Once customers run builds that include it, Digicom activates it. The old key becomes
retired. - New files use the new
kid. Existing files keep verifying because the retired key stays in your keyring.
Compromise
If a key is revoked, Digicom activates a new key and you ship an emergency release whose
keyring removes the revoked kid. Online installations receive a file signed with the new
key at their next check-in; offline installations need a new file from Digicom.
License key rotation
Digicom may rotate a customer's license key (for example after a leak). Existing machines are not deactivated, but they only know the old key. That's why every check-in and deactivation sends both:
licenseKey: the key the operator entered, andlicenseFileId:claims.fidof the currently stored file.
The server accepts either the current key or a known file ID belonging to that machine, together with the fingerprint. Activating a new machine always needs the current key.