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:
- Read the identifier twice in a row, and after a reboot. It must be identical.
- Read it from a 32-bit and a 64-bit build on Windows.
- Read it in a virtual machine, then clone the virtual machine and read it again.
- Reinstall the operating system on a spare computer and read it again.
- 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.
- 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.