Skip to main content
Security Enhancement in v2: Offline verification no longer trusts embedded public keys in .lic files. Applications now maintain a local trust store that maps key IDs to trusted public keys, preventing attackers from crafting malicious licenses with their own keys.

​
What’s Covered in This Guide

Trust Store Architecture

Security model and key management concepts

License Generation

Creating offline licenses in the Dashboard

Client-Side Verification

Implementing secure offline validation

Key Management

Key rotation and migration strategies
  • Quick Start
  • Migration
  1. Set up trust store with your public keys
  2. Generate .lic files from the Dashboard
  3. Implement verification in your application
  4. Handle key rotation for long-term security

​
Trust Store Architecture

The trust store is a client-side security mechanism that maps Key IDs (kid) to trusted public keys, preventing malicious license crafting.
The Key ID (kid) is a stable fingerprint of the public key computed as: kid = base64url(SHA-256(SPKI DER))

​
Computing Key ID

From PEM (Browser/Node.js): 
async function computeKidFromPem(pem) {
  const b64 = pem.replace(/-----BEGIN PUBLIC KEY-----|-----END PUBLIC KEY-----|\s+/g, '');
  const der = Uint8Array.from(atob(b64), c => c.charCodeAt(0));
  const hash = await crypto.subtle.digest('SHA-256', der);
  const b = String.fromCharCode(...new Uint8Array(hash));
  return btoa(b).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
}

​
Trust Store Implementation

import { importSPKI } from 'jose';

// Build trust store during application initialization
const trustStore = new Map();

// Add trusted keys (ship with your application)
const publicKeyPem = `-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAr7Z8s2Z...
-----END PUBLIC KEY-----`;

const kid = 'AbC123XyZ'; // Computed fingerprint
trustStore.set(kid, await importSPKI(publicKeyPem, 'EdDSA'));

​
2. Generate an Offline License (Dashboard)

1

Log in to Keymint and go to Products → [Your Product] → Licenses.
2

Locate the license row you wish to issue offline.
3

In the Activations column, click the Eye icon (👁️) to open the Offline License modal.

​
3. Offline License Modal

The modal has two panels:

​
A. Offline License Generator

  • Machine Code (optional) — A hardware fingerprint (e.g., host-ABC123) locks this file to one device.
  • Custom TTL (seconds) — Required if the license has no built-in expiration. Example: 2592000 for 30 days.
  • Generate Signed License — Signs a fresh JWT and immediately triggers download.

​
B. Device Activations

Below the generator, a table lists all machines that have activated this key. Useful for auditing.

​
4. Enhanced .lic File Format (v2)

When you click Generate, the browser downloads a file named: 
license-<KEY>-<machineCode?>-<YYYY-MM-DD>.lic
Contents (JSON) — No embedded public key: 
{
  "licenseToken": "eyJhbGciOiJFZERTQSIsImtpZCI6IkFiQzEyM1h5WiJ9...",
  "signedKey": "ABCD-EFGH-1234-5678",
  "signedDate": "2025-08-09T14:12:00.000Z",
  "keyId": "AbC123XyZ"
}
Field descriptions:
FieldTypeDescription
licenseTokenstringEd25519-signed JWT (header.alg=EdDSA, header.kid=fingerprint)
signedKeystringLicense key identifier shown to users
signedDatestringISO 8601 timestamp of issuance
keyIdstringSame value as JWT header.kid (fingerprint)

​
5. JWT Structure

Protected header: 
{
  "alg": "EdDSA",
  "kid": "AbC123XyZ"
}
Payload claims:
FieldTypeDescription
sub / keystringLicense key identifier
productIdstringProduct reference
machinestring(Optional) bound hardware fingerprint
typestring”offline”
iatnumberIssued-at timestamp (Unix seconds)
expnumberExpiry timestamp (Unix seconds)
nbfnumberNot-before timestamp (Unix seconds)

​
6. Distribution Methods

  • Web download
  • Email attachment
  • Physical media (USB, DVD, SD card)
  • Embed in installer

​
7. Client-Side Verification with Trust Store

Complete verification implementation: 
import { importSPKI, jwtVerify, decodeProtectedHeader } from "jose";
import fs from "fs";

// Error codes for granular failure handling
type VerificationResult = 
  | { ok: true; code: 'ok'; payload: any }
  | { ok: false; code: 'unknown_kid' | 'token_malformed' | 'signature_invalid' 
                      | 'token_expired' | 'not_yet_valid' | 'machine_mismatch' 
                      | 'product_mismatch' };

// Initialize trust store (ship with your application)
const trustStore = new Map<string, any>();

// Add your trusted public keys
const trustedKeys = [
  {
    kid: 'AbC123XyZ', // Fingerprint from Keymint dashboard
    pem: `-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAr7Z8s2Z...
-----END PUBLIC KEY-----`
  },
  // Add more keys for rotation
];

// Build trust store
for (const { kid, pem } of trustedKeys) {
  trustStore.set(kid, await importSPKI(pem, 'EdDSA'));
}

export async function verifyLicense(
  licenseFilePath: string, 
  options: {
    product?: string;
    machine?: string;
    now?: number;
  } = {}
): Promise<VerificationResult> {
  try {
    // 1. Load the .lic file
    const licenseData = JSON.parse(fs.readFileSync(licenseFilePath, "utf8"));
    const { licenseToken } = licenseData;
    
    if (!licenseToken) {
      return { ok: false, code: 'token_malformed' };
    }

    // 2. Decode JWT header (don't trust payload until signature verified)
    const header = decodeProtectedHeader(licenseToken);
    
    // 3. Resolve verification key
    let verificationKey;
    
    if (header.kid) {
      // Use kid-based lookup
      verificationKey = trustStore.get(header.kid);
      if (!verificationKey) {
        return { ok: false, code: 'unknown_kid' };
      }
      
      try {
        const { payload } = await jwtVerify(licenseToken, verificationKey, { 
          algorithms: ['EdDSA'] 
        });
        return validateClaims(payload, options);
      } catch {
        return { ok: false, code: 'signature_invalid' };
      }
    } else {
      // Legacy fallback: try all trusted keys
      for (const key of trustStore.values()) {
        try {
          const { payload } = await jwtVerify(licenseToken, key, { 
            algorithms: ['EdDSA'] 
          });
          return validateClaims(payload, options);
        } catch {
          // Continue to next key
        }
      }
      return { ok: false, code: 'signature_invalid' };
    }
  } catch {
    return { ok: false, code: 'token_malformed' };
  }
}

function validateClaims(
  payload: any, 
  { now = Math.floor(Date.now() / 1000), product, machine }: any
): VerificationResult {
  // Basic payload structure check
  if (typeof payload !== 'object' || !payload) {
    return { ok: false, code: 'token_malformed' };
  }

  // Check expiration (with small clock skew tolerance)
  const clockSkew = 300; // 5 minutes
  if (payload.exp && now > (payload.exp + clockSkew)) {
    return { ok: false, code: 'token_expired' };
  }

  // Check not-before
  if (payload.nbf && now < (payload.nbf - clockSkew)) {
    return { ok: false, code: 'not_yet_valid' };
  }

  // Check product match
  if (product && payload.productId !== product) {
    return { ok: false, code: 'product_mismatch' };
  }

  // Check machine binding
  if (machine && payload.machine && payload.machine !== machine) {
    return { ok: false, code: 'machine_mismatch' };
  }

  return { ok: true, code: 'ok', payload };
}
Quick implementation: 
import { importSPKI, jwtVerify, decodeProtectedHeader } from 'jose';
import fs from 'fs';

// Trust store helper - ship with your app
async function buildTrustStore() {
  const trustedKeys = [
    // Copy from Keymint "Manage Public Keys"
    { kid: 'AbC123XyZ', pem: `-----BEGIN PUBLIC KEY-----\nMCowBQ...\n-----END PUBLIC KEY-----` },
    { kid: 'DeF456UvW', pem: `-----BEGIN PUBLIC KEY-----\nMCowBQ...\n-----END PUBLIC KEY-----` }, // Next key for rotation
  ];
  
  const store = new Map();
  for (const { kid, pem } of trustedKeys) {
    store.set(kid, await importSPKI(pem, 'EdDSA'));
  }
  return store;
}

// Verify license
async function verifyOfflineLicense(licFilePath: string, options: { productId?: string, machineCode?: string } = {}) {
  const trustStore = await buildTrustStore();
  
  // 1. Read .lic file
  const { licenseToken } = JSON.parse(fs.readFileSync(licFilePath, 'utf8'));
  
  // 2. Decode header, get kid
  const header = decodeProtectedHeader(licenseToken);
  
  // 3. Resolve key from trust store
  let key = header.kid ? trustStore.get(header.kid) : null;
  if (!key) {
    // Fallback: try all trusted keys
    for (const k of trustStore.values()) {
      try {
        await jwtVerify(licenseToken, k, { algorithms: ['EdDSA'] });
        key = k;
        break;
      } catch { /* continue */ }
    }
  }
  
  if (!key) throw new Error('Unknown key ID or invalid signature');
  
  // 4. Verify JWT with Ed25519 only
  const { payload } = await jwtVerify(licenseToken, key, { algorithms: ['EdDSA'] });
  
  // 5. Validate claims
  const now = Math.floor(Date.now() / 1000);
  if (payload.exp && now > payload.exp) throw new Error('License expired');
  if (payload.nbf && now < payload.nbf) throw new Error('License not yet valid');
  if (payload.type && payload.type !== 'offline') throw new Error('Invalid license type');
  if (options.productId && payload.productId !== options.productId) throw new Error('Product mismatch');
  if (options.machineCode && payload.machineCode && payload.machineCode !== options.machineCode) throw new Error('Machine mismatch');
  
  return payload; // License valid!
}

​
8. Best Practices

  • Ship multiple trusted public keys for seamless key rotation.
  • Enforce Ed25519 (EdDSA) only; do not accept other algorithms.
  • Keep clock skew tolerance small (e.g., 5 minutes).
  • Bind to machine code where possible for higher assurance.
  • Provide user-friendly messages for common failure codes.
⌘I