Hardware Binding

Hardware binding ensures that licenses can only be used on authorized machines by creating a unique fingerprint of the customer's hardware. This prevents casual license sharing while allowing legitimate use across machine upgrades.

How It Works

When a customer activates a license, Licenz collects various hardware identifiers and combines them into a unique fingerprint. This fingerprint is then associated with the license and verified on each subsequent use.

Binding Factors

Licenz can use multiple hardware characteristics to create a fingerprint. You can configure which factors to include based on your security needs and tolerance for false positives.

Factor	Description	Stability	Uniqueness
MAC Address	Network interface hardware addresses	Medium	High
Disk Serial	Primary storage device serial number	High	High
Hostname	Machine's network name	Low	Medium
CPU ID	Processor identification string	Very High	Medium
OS ID	Operating system identifier	Medium	Low
Machine GUID	OS-level unique machine identifier	High	High

Factor Selection Guide

• High Security: Use all factors - best protection but more sensitive to hardware changes
• Balanced: MAC + Disk Serial + CPU ID - good protection, tolerates minor changes
• Flexible: Disk Serial + Machine GUID only - allows network and component upgrades

Fingerprint Structure

The collected fingerprint is structured as JSON and hashed for comparison:

{
  "hash": "sha256:a1b2c3d4e5f67890...",
  "algorithm": "sha256",
  "components": {
    "mac_addresses": ["aa:bb:cc:dd:ee:ff", "11:22:33:44:55:66"],
    "disk_serial": "WD-XXXXX123456",
    "hostname": "workstation-01",
    "cpu_id": "GenuineIntel-0x506E3",
    "os_id": "linux-5.15"
  },
  "collected_at": "2024-01-15T10:30:00Z"
}

Collecting a Fingerprint

Use the Licenz client library to collect fingerprints in your application:

use licenz::HardwareFingerprint;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Collect hardware fingerprint with default factors
    let fingerprint = HardwareFingerprint::collect()?;

    println!("Fingerprint: {}", fingerprint.hash());
    println!("Components: {:?}", fingerprint.components());

    // Customize which factors to include
    let custom_fingerprint = HardwareFingerprint::builder()
        .include_mac_address(true)
        .include_disk_serial(true)
        .include_hostname(false)  // Exclude hostname
        .include_cpu_id(true)
        .build()?;

    Ok(())
}

Verification Process

When verifying a license with hardware binding, the current machine's fingerprint is compared against the registered fingerprint:

use licenz::{License, Verifier, HardwareFingerprint};

fn validate_license(key: &str) -> Result<bool, Box<dyn std::error::Error>> {
    let license = License::from_key(key)?;
    let fingerprint = HardwareFingerprint::collect()?;
    let verifier = Verifier::new(public_key);

    match verifier.verify_with_hardware(&license, &fingerprint) {
        Ok(result) => {
            if !result.is_active() {
                println!("License expired");
                return Ok(false);
            }

            if !result.hardware_matches() {
                println!("Hardware mismatch! Expected: {}", result.expected_fingerprint());
                println!("Got: {}", fingerprint.hash());
                return Ok(false);
            }

            println!("License valid and hardware verified!");
            Ok(true)
        }
        Err(e) => {
            println!("Validation error: {}", e);
            Ok(false)
        }
    }
}

Activation Flow

The typical hardware-bound activation flow using the CLI:

# First activation - registers the hardware fingerprint
licenz activate LIC-XXXX-XXXX-XXXX-XXXX

# Output:
# Collecting hardware fingerprint...
# Fingerprint: a1b2c3d4e5f6...
# License activated successfully!
# Activations used: 1 of 3

# Subsequent runs on the same machine
licenz verify LIC-XXXX-XXXX-XXXX-XXXX

# Output:
# License valid
# Hardware: verified
# Expires: 2025-12-31

Handling Hardware Changes

When customers upgrade or replace hardware, their fingerprint changes. Licenz provides several options for handling this:

Automatic Tolerance

Configure tolerance at the product level to allow minor fingerprint differences:

# Set tolerance to 75% - 3 of 4 factors must match
licenz product update prod_abc123 --hardware-tolerance 75

Manual Reactivation

Customers can request reactivation through the customer portal or by contacting support. This consumes one of their activation slots if available.

# Reset activations for a license (admin)
licenz license reset-hardware LIC-XXXX-XXXX-XXXX-XXXX

# Or deactivate a specific machine
licenz deactivate --fingerprint a1b2c3d4...

Grace Period

Configure a grace period during which hardware mismatches are logged but not enforced, giving customers time to request reactivation:

# Allow 7-day grace period on hardware mismatch
licenz product update prod_abc123 --hardware-grace-days 7

Privacy Considerations

Hardware fingerprints are one-way hashed before transmission, meaning Licenz stores only the hash, not raw hardware identifiers. This provides:

• Privacy - Raw hardware serials are never transmitted or stored
• Security - Hashes cannot be reversed to obtain identifiers
• Compliance - Helps meet data minimization requirements (GDPR)

Next Steps

• Set up offline activation for air-gapped environments
• Learn about the security model
• Activations API reference
• CLI activation commands