Node-locking activations and surviving fingerprint drift
A node-locked license binds a seat to one machine. The binding is a machine fingerprint — a stable, salted hash derived from hardware and OS signals, never raw hardware identifiers. This deep dive shows how the Keyright SDK computes the fingerprint and sends it on ActivateAsync, how the issuing service counts distinct fingerprints as active devices, and the real operational problem of fingerprint drift: a VM clone, a reimaged disk, a swapped NIC or a RAM upgrade changes the fingerprint, the machine looks new, and seats exhaust. We cover weighted multi-signal fingerprints, tolerance matching, deactivation and lease expiry to reclaim seats, and fail-closed gating.
Node-locking answers one question: is this the machine the license was activated on? It is the oldest and most intuitive licensing model — you buy three seats, you install on three machines, and each install is pinned to the hardware it runs on. The pinning mechanism is a machine fingerprint: a short, stable identifier the SDK derives from the machine and sends to the issuing service at activation. The service remembers it, counts it as one occupied seat, and from then on expects to see the same fingerprint every time that install checks in.
The model is simple until hardware changes. A fingerprint is only as stable as the signals it is built from, and real machines mutate: disks get reimaged, network cards get swapped, VMs get cloned, laptops get more RAM. When the signals move, the fingerprint moves with them, the machine looks brand-new to the issuing service, and a seat that should have stayed put gets spent twice. That failure mode — fingerprint drift — is the real subject of this article. We will build the fingerprint first, wire it through Keyright activation, then spend most of our time making it survive the physical world.
What a machine fingerprint is
A fingerprint is a single hash standing in for a machine. You never ship raw hardware identifiers to the issuing service — that would be both a privacy liability and a reversible dossier of someone’s hardware. Instead you collect a handful of signals that are reasonably stable per machine, combine them, and hash the combination with a per-product salt:
- Machine GUID — the OS-level install identity (
MachineGuidon Windows,/etc/machine-idon Linux, theIOPlatformUUIDon macOS). - Primary MAC address — the hardware address of the main network adapter, with virtual and loopback adapters filtered out.
- System volume serial — the serial of the OS volume.
- CPU identifier — processor model/feature signature.
None of these leaves the machine on its own. They are concatenated and reduced to one SHA-256 digest, salted with a value unique to your product so that the same machine produces different fingerprints for different products and the digest cannot be precomputed against a rainbow table of common hardware.
using System.Security.Cryptography;
using System.Text;
public static class MachineFingerprint
{
// Per-product salt — distinct per Keyright product, kept out of logs.
private const string ProductSalt = "keyright:acme-cad:v1";
public static string Compute()
{
// Each signal is collected best-effort; a missing signal yields "".
var signals = new[]
{
HardwareSignals.MachineGuid(), // OS install identity
HardwareSignals.PrimaryMac(), // main NIC, virtual adapters excluded
HardwareSignals.VolumeSerial(), // OS volume serial
HardwareSignals.CpuId(), // processor signature
};
// Order matters: a fixed order makes the digest reproducible.
var material = ProductSalt + "|" + string.Join("|", signals);
var hash = SHA256.HashData(Encoding.UTF8.GetBytes(material));
return Convert.ToHexString(hash).ToLowerInvariant(); // opaque, one-way
}
}
The output is something like 9f2c…a1, and that is all the issuing service ever sees. There is no path from the digest back to the MAC or the volume serial — the hash is one-way, and the salt means even a known machine’s fingerprint cannot be reproduced without the product’s salt. This is the privacy contract: fingerprints are hashed and salted, never raw PII, and never reversible to hardware identifiers.
Binding a seat at activation
The SDK sends the fingerprint on ActivateAsync. Initialization gives the client the product, the signing public key, and your deployment’s service URL; activation posts the license key plus the computed fingerprint to POST /v1/activate.
KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-cad",
PublicKeyBase64 = "MCowBQYDK2VwAyEA...", // verifies signed responses
ServiceUrl = "https://license.acme.example",
});
var client = KeyrightClient.Current;
// The fingerprint is attached to the activation request automatically,
// but you can inspect or override it for testing.
var result = await client.ActivateAsync(licenseKey);
if (!result.IsValid)
{
// Fail CLOSED: no seat, no licensed functionality.
ShowActivationError(result.Reason); // e.g. SeatsExhausted, InvalidKey
return;
}
On the service side, /v1/activate records the (license key, fingerprint) pair. The seat meter is the count of distinct fingerprints bound to that key: a key sold with three seats accepts three distinct fingerprints and refuses the fourth with a SeatsExhausted result. Reactivating the same fingerprint is idempotent — it re-binds the machine it already knows and does not consume an extra seat. This is why the fingerprint must be stable: the service’s entire notion of “how many machines” is “how many distinct fingerprints have I seen.”
Every subsequent run calls ValidateAsync, which recomputes the fingerprint and presents it. If it matches a live binding, validation succeeds and the SDK exposes the license details and entitlements:
var v = await client.ValidateAsync();
if (!v.IsValid)
{
EnterReadOnlyMode(); // fail closed on any validation failure
return;
}
Console.WriteLine($"Licensed to {v.LicenseInfo.Owner}, seat bound to this machine.");
if (client.HasEntitlement("export.dwg"))
EnableDwgExport();
The drift problem
Here is where the clean model meets hardware reality. Consider the diagram below: a machine’s signals feed the hash, the hash becomes a fingerprint, and the fingerprint occupies one seat on the issuing service. The lower path shows what drift does — one signal changes, the hash changes, and the service sees a new machine competing for a new seat while the old binding still counts.
The causes are mundane and common: a reimaged disk regenerates the OS machine GUID; a swapped or dock-dependent network adapter changes the MAC; cloning a VM template duplicates — or, worse, randomizes — every signal; a firmware update changes a volume serial. Each one flips the digest. A single all-or-nothing signal is brittle; the fix is to stop treating the fingerprint as one fragile value.
Mitigation: weight several signals
Instead of hashing everything into one unforgiving digest, compute a fingerprint from weighted components and accept a match when enough weight agrees. The SDK sends the component set; the issuing service decides whether the presented set is close enough to a known binding to be the same machine.
public sealed record FingerprintComponent(string Name, string Value, int Weight);
public static IReadOnlyList<FingerprintComponent> Components() => new[]
{
new FingerprintComponent("machineGuid", Hash(HardwareSignals.MachineGuid()), 40),
new FingerprintComponent("volumeSerial", Hash(HardwareSignals.VolumeSerial()), 25),
new FingerprintComponent("cpuId", Hash(HardwareSignals.CpuId()), 20),
new FingerprintComponent("primaryMac", Hash(HardwareSignals.PrimaryMac()), 15),
};
static string Hash(string s) =>
Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes("keyright:acme-cad:v1|" + s)))
.ToLowerInvariant();
Each component is individually salted and hashed — the raw signal still never leaves the machine. The service stores the components bound at activation and, on each validation, scores the presented set against them. If matching components carry at least a configured share of total weight, it is the same machine; one changed MAC (15 of 100) does not flip identity, but a wholesale change does.
Tolerance matching on the service
match score = Σ weight(component) where presented.value == bound.value
same machine if match score >= tolerance threshold (e.g. 70 of 100)
re-bind if same machine and some components changed (heal the drift)
new machine if match score < threshold (count a seat)
A tolerance threshold absorbs ordinary drift. When a machine matches above the threshold but some components have changed — the MAC moved, say — the service treats it as the same seat and re-binds to the new component set, healing the drift so the next validation matches cleanly. Only when too much has changed does it count a new machine. Choose the threshold deliberately: too loose and distinct machines collide into one seat; too tight and ordinary upgrades exhaust seats.
Reclaiming seats: deactivation and lease expiry
Tolerance reduces drift but cannot catch everything — a wholesale reimage or a retired laptop genuinely leaves a stale binding holding a seat. Two mechanisms return it.
Explicit deactivation. Before decommissioning or moving a license, the client releases its seat. This posts to POST /v1/deactivate and the seat returns at once.
// Freeing a seat so it can be re-used elsewhere.
var released = await client.DeactivateAsync();
if (released.IsValid)
Console.WriteLine("Seat released; this machine no longer counts.");
Lease expiry. Deactivation only works when the machine is still around to call it — a dead disk never deactivates. So every binding also carries a lease with an expiry that the client renews on each ValidateAsync. A machine that stops validating — retired, reimaged, permanently offline — stops renewing; once its lease lapses, the issuing service reclaims the seat automatically. Deactivation is the clean immediate path; lease expiry is the backstop for machines that vanished. On reactivation (the user reinstalls, or moves the key to replacement hardware) the SDK simply computes the current fingerprint and ActivateAsync binds it to the now-free seat.
Fail closed, always
The non-negotiable rule: when activation is refused, validation fails, or seats are exhausted, the application must fail closed — deny the licensed functionality rather than assume goodwill. Node-locking is only meaningful if the gate holds when the answer is “no”:
var v = await client.ValidateAsync();
bool licensed = v.IsValid
&& v.LicenseInfo is { } info
&& !info.IsExpired;
if (!licensed)
{
// Seat exhausted, fingerprint unknown, lease lapsed, or offline past grace:
// do NOT enable paid features. Degrade, don't default-open.
EnterReadOnlyMode();
return;
}
EnableLicensedFeatures();
Containers and ephemeral identity
Node-locking assumes a durable machine. A container does not have one — every fresh container computes a different fingerprint and would burn a seat on each launch, exhausting the meter almost immediately. For disposable or autoscaled workloads, node-locking is the wrong tool; you want an ephemeral-friendly identity model instead — very short leases that reclaim within minutes, or a concurrency model that counts simultaneous use rather than distinct machines. (We cover that model separately in our writeup on floating, lease-counted seats.) Reserve node-locking for durable workstations and servers, where a stable fingerprint is a feature rather than a fight.
Summary
Node-locking binds a seat to a machine through a salted, one-way fingerprint — stable enough to count, private enough to never expose hardware identifiers. The failure mode that bites in production is drift: ordinary hardware change moves the fingerprint and quietly doubles seat consumption. The cure is not a single brittle hash but a weighted multi-signal fingerprint with a tolerance threshold that re-binds through small changes, backed by explicit deactivation and lease expiry to reclaim seats from machines that are gone. Gate it all fail-closed, and keep ephemeral workloads on an identity model built for them.
Try Nebula.NET
Harden your .NET code in minutes — start with the free edition.