Skip to Content
PortcullisDocs
Integrate (product engineers)

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 isPer-product Ed25519 key pair that signs license filesPer-license secret used for online activation
Your build needsThe public keys in a compiled keyringNothing
Your runtime needsLook up kid in the keyringSend 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:

StateSigns new filesKeep in your keyring
pendingNo (activated later)Yes: ship it ahead of the rotation
activeYesYes
retiredNoYes: older files are still signed with it
revokedNoNo: 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

  1. Digicom generates the next key in pending state.
  2. You ship a product release whose keyring includes the pending key.
  3. Once customers run builds that include it, Digicom activates it. The old key becomes retired.
  4. 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, and
  • licenseFileId: claims.fid of 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.

On this page