Clavem

Machine fingerprinting for software licenses: what to use and what goes wrong

Use one stable operating-system machine id per platform, hash it with a salt that belongs to your app, and send only the hash. Expect it to change on some reinstalls and hardware swaps, and treat a changed fingerprint as a new device, not as fraud.

What a fingerprint is for

A device limit needs a way to tell one computer from another. The app names the device when it activates (instance_name, a label for humans), and it can also send a fingerprint: a stable identifier for the machine. If the fingerprint is the same the next time, the server knows it is the same computer.

In Clavem, activating again with a fingerprint that is already active on the license returns that seat, with its name updated, instead of using another. That removes the most common support case: a buyer reinstalls the app or the operating system and the license counts them twice.

The fingerprint is a convenience that protects honest buyers from using up seats. It is not an anti-piracy mechanism. Anyone who controls the computer controls what the app sends. Design it so that the failure mode is “the buyer has to remove an old device”, not “the buyer is locked out”.

Where the identifiers come from

Platform Identifier Where it lives What the vendor documents
macOS IOPlatformUUID Property of the platform expert device in the IO Registry, read with ioreg or IOKit Apple’s XNU headers define kIOPlatformUUIDKey as "IOPlatformUUID", a property that “describes the machine’s UUID as a string”. I found no Apple documentation that promises when it changes.
Windows MachineGuid Registry value HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid I found no Microsoft documentation that promises it is unique or stable. Microsoft documents that generalizing an image with Sysprep removes computer-specific information.
Linux /etc/machine-id A 128-bit id as 32 hex characters, a file written at install or first boot The systemd documentation describes it fully: generated randomly at installation or first boot, then constant.

The honest summary is that only systemd documents its identifier as a contract. On macOS and Windows you are relying on a value that works, not one that is promised, so treat both as the best available and test them.

How each behaves

This table is reasoned from where each value comes from, plus what developers commonly report. The vendors do not publish these guarantees, so run your own test on the hardware your customers use.

Event macOS IOPlatformUUID Windows MachineGuid Linux machine-id
Reinstall of the operating system Tied to the hardware, so normally the same New value, because Windows Setup writes it at install New value, because it is generated at install or first boot
Replacing the motherboard Normally changes Same Same
Cloning the disk to a second computer Differs, because the value comes from the hardware Same on both, unless the image was generalized with Sysprep Same on both, unless the file was emptied before cloning
Cloning a virtual machine Depends on the hypervisor Same, unless generalized Same, unless the file was emptied
Container Not applicable Depends on the image Depends on how the container is built

Two consequences matter for licensing. On Windows and Linux, a reinstall gives a new fingerprint, so the old activation is stale and the buyer needs to remove it. On Windows and Linux, a cloned disk shares the identifier, so two computers can run on one seat. If that second case bothers you, accept it, because the alternative is mixing in hardware signals that break on honest upgrades.

The pitfalls

Using the MAC address. It changes when a laptop moves to a dock, a VPN installs a virtual adapter, or the operating system randomises the address. It also fails on machines with no adapter. Honest buyers lose their activation for no reason.

Combining many weak signals and requiring all of them. CPU model, disk serial, hostname and screen size sound thorough. Each one can change, and if any change breaks the match, the buyer is a stranger after a memory upgrade. If you combine signals, accept a partial match, and be aware that this adds code and false matches.

Using the hostname. Buyers rename computers, and many computers share default names.

Sending the raw id. The systemd documentation says the machine id should be considered “confidential”, must not be exposed in untrusted environments, “in particular on the network”, and that if you need a stable identifier for an application you should hash it with a keyed hash and a fixed application-specific key. It points at sd_id128_get_machine_app_specific for that. The same logic applies on every platform. A hash with your own salt gives you a stable identifier that reveals nothing if your server or a log leaks.

Treating a changed fingerprint as fraud. The usual cause is a reinstall. Show a message that explains how to free a device and link to the buyer’s device page.

Reading the wrong registry view on Windows. On 64-bit Windows, a 32-bit process can be redirected to a different registry view. Read the 64-bit view so a 32-bit and a 64-bit build of your app produce the same value. The Node example below does this with reg query ... /reg:64.

No fallback. Some machines, sandboxes and containers give you nothing. Fall back to a random id that you generate once and keep in the app’s data folder. It does not survive a reinstall, which is no worse than the Windows and Linux cases above.

Strict or tolerant matching

There are two designs, and the right one depends on what you are protecting.

Design How it works Fails by
Strict One identifier, one hash, exact match Reinstalls and hardware swaps look like new computers, so honest buyers need to free a seat
Tolerant Several signals, a match if enough of them agree More code and more false matches, and a cloned machine can pass as the original

For a software license sold at a normal price, strict matching with a good recovery path is the better trade. It costs a buyer one click on the device page when something changes. Tolerant matching shifts the failure to places you cannot see, because you cannot tell a false match from an honest one.

Note what the server does with the value. Clavem compares fingerprints for equality only. A tolerant matcher would have to live in your app, which makes the decision in code that the attacker can read and change anyway.

A test list for your own fingerprint

Run these on real machines before you rely on the value, and record the results for each platform you ship on:

  1. Read the identifier twice in a row, and after a reboot. It must be identical.
  2. Read it from a 32-bit and a 64-bit build on Windows.
  3. Read it in a virtual machine, then clone the virtual machine and read it again.
  4. Reinstall the operating system on a spare computer and read it again.
  5. Run the app in the sandbox you ship in (a Mac App Store sandbox, a Flatpak, a Windows package container). A sandbox can restrict access to the registry or to files.
  6. Run with no network and with a VPN installed, to confirm nothing in your recipe depends on an adapter.

If any step surprises you, you have found a support ticket before a customer did.

Privacy

A hardware-derived identifier together with an email address in a license record can identify a person. Whether it counts as personal data, and what you must do about it, depends on where you and your customers are. This is general information, not legal advice. In practice: collect the hash and nothing else, say in your privacy policy what you collect and why, and ask a lawyer if your product is aimed at regulated users. Clavem’s API reference says the same thing in one line: send a hash, not a raw hardware id.

Code you can run

The Swift version reads IOPlatformUUID through IOKit and hashes it with an app-specific salt. I compiled and ran it on macOS.

import CryptoKit
import Foundation
import IOKit

func platformUUID() -> String? {
    let service = IOServiceGetMatchingService(kIOMainPortDefault, IOServiceMatching("IOPlatformExpertDevice"))
    guard service != 0 else { return nil }
    defer { IOObjectRelease(service) }
    let value = IORegistryEntryCreateCFProperty(service, kIOPlatformUUIDKey as CFString, kCFAllocatorDefault, 0)
    return value?.takeRetainedValue() as? String
}

func fingerprint(appSalt: String) -> String? {
    guard let uuid = platformUUID() else { return nil }
    let digest = SHA256.hash(data: Data((appSalt + ":" + uuid).utf8))
    let hex = digest.map { String(format: "%02x", $0) }.joined()
    return String(hex.prefix(32))
}

The Node version covers all three platforms. I ran it on macOS only.

import { createHash } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { readFileSync } from 'node:fs';

function rawMachineId() {
  switch (process.platform) {
    case 'darwin': {
      const out = execFileSync('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { encoding: 'utf8' });
      return out.match(/"IOPlatformUUID" = "([0-9A-Fa-f-]{36})"/)?.[1] ?? null;
    }
    case 'win32': {
      const out = execFileSync('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid', '/reg:64'], { encoding: 'utf8' });
      return out.match(/MachineGuid\s+REG_SZ\s+(\S+)/)?.[1] ?? null;
    }
    default: {
      for (const path of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
        try { const v = readFileSync(path, 'utf8').trim(); if (v) return v; } catch {}
      }
      return null;
    }
  }
}

export function fingerprint(appSalt) {
  const id = rawMachineId();
  if (!id) return null;
  return createHash('sha256').update(appSalt + ':' + id).digest('hex').slice(0, 32);
}

On the same Mac, both programs printed the same 32-character value, which is what you want: any language that follows the same recipe produces the same fingerprint. That matters if you ship a Swift app and a command-line tool for one product.

Doing this with Clavem

fingerprint is an optional string of up to 200 characters on POST /v1/licenses/activate. Send a hash. If the same fingerprint is active on the license, the call returns that seat with its name updated, so reinstalls do not consume seats. The token carries it back as the fp claim, which lets your app compare it with what it computes today. Clavem does not compute fingerprints for you and does not match them loosely: two fingerprints are the same or they are not. If a buyer’s fingerprint changes, they use the device page at /licenses/manage to remove the old device, as license transfers between computers explains.

Questions

What is the best machine identifier for license activation?

There is no perfect one. The operating system's own machine id is the usual choice: IOPlatformUUID on macOS, MachineGuid on Windows and /etc/machine-id on Linux. Hash it with an app-specific salt before sending it anywhere.

Should I use the MAC address?

Usually not. MAC addresses change with network adapters, docks, virtual interfaces and address randomisation, so honest customers will lose their activation more often than with an operating-system machine id.

Is a hardware fingerprint personal data under GDPR?

It can be, when it can be linked to a person, which a license record usually allows. This is general information, not legal advice. Hash it, collect no more than you need, say so in your privacy policy and ask a lawyer about your case.

Sources

  1. systemd machine-id documentation (as of November 2026)
  2. Apple XNU source, IOKitKeys.h, kIOPlatformUUIDKey (as of November 2026)
  3. Microsoft Learn, Sysprep generalize a Windows installation (as of November 2026)