Hardware ID generation

A hardware ID is a unique device identifier used to bind a license to that device, which helps to avoid transferring licenses to other devices.

This tutorial will help you learn more about hardware ID algorithms provided by LicenseSpring SDKs and choose the optimal hardware ID algorithm for your application.

Prerequisites

1

Initialize LicenseManager

Initialized LicenseManager (or LicenseHandler) with your configuration using the appropriate settings.

2

Activate a license

Activated a license of any type.

3

Implement checks

Implemented routine local and online checks within the application.

SDK-independent hardware ID generator library

We provide a SDK-independent hardware ID generator library as a dynamically-loadable shared library. This is a part of our on-going process to standardize licensing across all our SDKs. The library is integrated into:

• C++ SDK since v7.42.0,

• C# SDK since v7.34.0,

• Java SDK since v2.25.1,

• Go SDK since the v2 rewrite,

• Python SDK since v2.0.0,

• JavaScript SDK since initial release.

Swift and Android SDK use custom hardware ID generation algorithms as they are mostly tied to platforms with straightforward hardware ID generation.

Each SDK packages the shared library to be easily deployable either manually or through popular repositories and package managers. The library is released for multiple operating systems and architectures:

• For Windows, we provide binaries built for x64, x86 and ARM64 architectures, built with a VS2022 MSVC toolchain. We also provide a version built GCC 8.1 from Qt's distribution of MinGW.

• For macOS, we provide binaries built for the x86_64 architecture (min. required version 10.12) and arm64 architecture (min. required version 11.0).

• For Linux, we provide binaries built for i686, x86_64, armv7l (i.e. armhf), ppc64le, s390x and riscv architectures, linked against either glibc 2.27 or musl libc.

• For iOS, we provide an XCFramework, which includes slices for iphoneos (arm64) and iphonesimulator (arm64 & x86_64). The slices are shipped as static libraries, which means the framework must be statically linked into the consumer library or application.

Algorithms list

The library exports an enum of available algorithms. Algorithm names in each SDK that FFIs into the library can easily be mapped to an algorithm in the following list:

enum class HardwareIdAlgorithm {
    /**
     * @brief Default hardware ID calculation algorithm.
     *
     * @details Computes a default hardware identifier.
     * On Windows, computes HardwareIdAlgorithm::WindowsComputerSystemProductId.
     * On macOS, the algorithm uses `gethostuuid` to compute a unique machine
     * identifier.
     * On Linux, computes HardwareIdAlgorithm::LinuxMachineId.
     */
    Default,

    /**
     * @brief Alternative hardware ID algorithm for Windows.
     *
     * @details Computes a hardware fingerprint based on CPU, disk, and
     * motherboard.
     */
    WindowsHardwareFingerprintId,

    /**
     * @brief Default hardware ID algorithm for Windows.
     *
     * @details Gets the UUID of the Windows machine using the Computer System
     * Product UUID. See [Microsoft
     * Docs](https://learn.microsoft.com/en-us/windows/win32/cimwin32prov/win32-computersystemproduct).
     */
    WindowsComputerSystemProductId,

    /**
     * @brief Alternative hardware ID algorithm for Windows.
     *
     * @details Retrieves `SOFTWARE\Microsoft\Cryptography\MachineGUID` from
     * the Windows registry.
     */
    WindowsCryptographyId,

    /**
     * @brief Default hardware ID algorithm for Linux.
     *
     * @details Reads `/etc/machine-id` and `/var/lib/dbus/machine-id` in that
     * order. If these files don't exist, a new UUID is written to the
     * filesystem.
     */
    LinuxMachineId,

    /**
     * @brief Cloud platforms instance hardware ID algorithm.
     *
     * @details Retrieves the instance ID for cloud platforms, including Azure,
     * AWS, and GCP.
     */
    CloudPlatformsId
};

The full package can be downloaded on the hardware ID generator download page.

Configuration

When you have chosen the algorithm, set it to the ExtendedOptions.

C++

LicenseSpring::ExtendedOptions options;

// DeviceIDAlgorithm::HardwareIdGeneratorDefault is the default 
// value for the new hardware ID generator library
options.setDeviceIdAlgorithm(HardwareIdGeneratorDefault);

C#

Swift

Java

Python

SDKs also allow overriding the hardware ID. For instance, you can use the MAC address as the hardware ID:

C++

LicenseSpring::ExtendedOptions options;
options.setHardwareID( options.getNetworkInfo().mac() );

C#

Go

Java

Python

Relink License

The license relinking method can be useful when the hardware ID algorithm has been changed. Despite the license belonging to the current device, the local check will throw DeviceNotLicensedException since different algorithms produce different hardware IDs. In this case you can relink the license to the new hardware ID.

C++

try
{
  license->localCheck();
}
catch(const DeviceNotLicensedException& ex)
{
  std::cout << "Trying to upgrade to newer hardware ID algorithm..." << std::endl;
  license = m_licenseManager->relinkLicense(HardwareIdGeneratorWindowsComputerSystemProductId);
  std::cout << "License successfully linked to new hardware ID." << std::endl;
  return;
}

// the C++ SDK also provides unlinkFromDevice and isLicenseBelongsToThisDevice methods
// unlinkFromDevice check if the license is tied to the current device, and deactivates it
// isLicenseBelongsToThisDevice checks if the license belongs to hardware ID computed by
// the passed DeviceIDAlgorithm

C#

This method checks if the old hardware ID of the license matches any of the IDs generated by different algorithms. When it finds the correct algorithm, it deactivates the license with the old ID and activates it again using the new algorithm. This method throws the same exceptions as a regular license activation.

Recovering WMI

WMI repository issues can occur on Windows 10 and Windows 11. It's useful to know how to fix them since most of the hardware ID algorithms use WMI. Here are some recovery methods:

• To check if the WMI repository is consistent, open Command Prompt with administrator privileges and run winmgmt /verifyrepository. If you don't get a message stating WMI repository is consistent, proceed with the next steps.

• In the same Command Prompt window, run the three following commands:

  • cd C:\Windows\system32\wbem

  • mofcomp.exe CIMWin32.mof

  • regsvr32 cimwin32.dll

• You can also try to recover WMI by running the following command from Command Prompt with admin privileges: winmgmt /resetrepository. For more information, see https://stackoverflow.com/a/71535626

Be aware of risks of running the command above, see https://techcommunity.microsoft.com/t5/ask-the-performance-team/wmi-repository-corruption-or-not/ba-p/375484