Home

Awesome

DeviceId

A simple library providing functionality to generate a 'device ID' that can be used to uniquely identify a computer.

Quickstart

What packages are needed?

As of version 6, the packages have been split up so that users can pick-and-choose what they need, without having to pull down unnecessary references that they won't use:

You can pick-and-choose which packages to use based on your use case.

For a standard Windows app, the recommended packages are: DeviceId and DeviceId.Windows. If you want some extra advanced components you can also add DeviceId.Windows.Wmi.

PM> Install-Package DeviceId
PM> Install-Package DeviceId.Windows

Building a device identifier

Use the DeviceIdBuilder class to build up a device ID.

Here's a Windows-specific device ID, using the DeviceId.Windows package to get the built-in Windows Device ID.

string deviceId = new DeviceIdBuilder()
    .OnWindows(windows => windows.AddWindowsDeviceId())
    .ToString();

Here's a simple cross-platform one, using only the DeviceId package, which is valid for both version 5 and version 6 of the library:

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .AddFileToken("example-device-token.txt")
    .ToString();

Here's a more complex device ID, making use of some of the advanced components from the DeviceId.Windows.Wmi (or DeviceId.Windows.Mmi) package:

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .OnWindows(windows => windows
        .AddProcessorId()
        .AddMotherboardSerialNumber()
        .AddSystemDriveSerialNumber())
    .ToString();

Here's a complex cross-platform device ID, using DeviceId.Windows.Wmi, DeviceId.Linux, and DeviceId.Mac:

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .OnWindows(windows => windows
        .AddProcessorId()
        .AddMotherboardSerialNumber()
        .AddSystemDriveSerialNumber())
    .OnLinux(linux => linux
        .AddMotherboardSerialNumber()
        .AddSystemDriveSerialNumber())
    .OnMac(mac => mac
        .AddSystemDriveSerialNumber()
        .AddPlatformSerialNumber())
    .ToString();

You can also generate a unique identifier for a database instance. Currently, only SQL Server is supported, but more may be added if there is demand and/or community support:

using SqlConnection connection = new SqlConnection(connectionString);
connection.Open();
string databaseId = new DeviceIdBuilder()
    .AddSqlServer(connection, sql => sql
        .AddServerName()
        .AddDatabaseName()
        .AddDatabaseId())
    .ToString();

What can you include in a device identifier

The following extension methods are available out of the box to suit some common use cases:

From DeviceId:

From DeviceId.Windows:

From DeviceId.Windows.Wmi / DeviceId.Windows.WmiLight / DeviceId.Windows.Mmi:

From DeviceId.Linux:

From DeviceId.Mac:

From DeviceId.SqlServer:

Dealing with MAC Address randomization and virtual network adapters

Non physical network adapters like VPN connections tend not to have fixed MAC addresses. For wireless (802.11 based) adapters hardware (MAC) address randomization is frequently applied to avoid tracking with many modern operating systems support this out of the box. This makes wireless network adapters bad candidates for device identification.

Using the cross-platform AddMacAddress, you can exclude wireless network adapters like so:

string deviceId = new DeviceIdBuilder()
    .AddMacAddress(excludeWireless: true)
    .ToString();

If you're on Windows, you can also exclude non-physical adapters using the DeviceId.Windows.Wmi or DeviceId.Windows.Mmi packages like so:

string deviceId = new DeviceIdBuilder()
    .AddMacAddress(excludeWireless: true)
    .OnWindows(windows => windows
        .AddMacAddressFromWmi(excludeWireless: true, excludeNonPhysical: true)
    .ToString()

Controlling how the device identifier is formatted

Use the UseFormatter method to set the formatter:

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .UseFormatter(new HashDeviceIdFormatter(() => SHA256.Create(), new Base32ByteArrayEncoder()))
    .ToString();

The "default" formatters are available in DeviceIdFormatters for quick reference. The default formatter changed between version 5 and version 6 of the library. If you're using version 6 but want to revert to the version 5 formatter, you can do so:

string deviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddOsVersion()
    .UseFormatter(DeviceIdFormatters.DefaultV5)
    .ToString();

For more advanced usage scenarios, you can use one of the out-of-the-box implementations of IDeviceIdFormatter in the DeviceId.Formatters namespace, or you can create your own.

There are a number of encoders that can be used customize the formatter. These implement IDeviceIdComponentEncoder and IByteArrayEncoder and are found in the DeviceId.Encoders namespace.

Supporting/validating multiple device ID formats with backwards compatibility

Let's say you shipped an app, and were using DeviceId to perform license checks. You may have done something like:

var currentDeviceId = new DeviceIdBuilder()
    .AddMachineName()
    .AddUserName()
    .AddMacAddress()
    .ToString();

var savedDeviceIdFromLicenseFile = ReadDeviceIdFromLicenseFile();

var isLicenseValid = currentDeviceId == savedDeviceIdFromLicenseFile;

Say you now want to release a new version of your app, and want to change how new device identifiers are generated (maybe just use MAC address and a file token), but you don't want to invalidate every single license file that currently exists. In other words, you want backwards compatible device ID validation.

In the latest version of DeviceId, you can use the DeviceIdManager to do so:


var deviceIdManager = new DeviceIdManager()
    .AddBuilder(1, builder => builder
        .AddMachineName()
        .AddUserName()
        .AddMacAddress())
    .AddBuilder(2, builder => builder
        .AddMacAddress()
        .AddFileToken(TokenFilePath));

var savedDeviceIdFromLicenseFile = ReadDeviceIdFromLicenseFile();

var isLicenseValid = deviceIdManager.Validate(savedDeviceIdFromLicenseFile);

The device ID manager will work out which builder to use, and generate the current device ID in the correct format so that it can be sensibly compared to the device ID being validated.

Note that this functionality all works well but I'm not entirely happy with the naming or the API. I've currently built it so that there are no breaking changes for v6. In the future (v7 for example) I may rename some classes and break the API. In any case though I will keep the functionality, so it's safe to use this stuff.

Migration Guide 5.x -> 6.x

There were a few breaking changes going from v5 to v6.

// V5:
builder.AddOSInstallationID();

// V6:
builder.OnWindows(x => x.AddMachineGuid())
       .OnLinux(x => x.AddMachineId())
       .OnMac(x => x.AddPlatformSerialNumber());

// V5:
builder.AddMotherboardSerialNumber();

// V6:
builder.OnWindows(x => x.AddMotherboardSerialNumber())
       .OnLinux(x => x.AddMotherboardSerialNumber());
       // not available on Mac

// V5:
builder.AddSystemUUID();

// V6:
builder.OnWindows(x => x.AddSystemUuid())
       .OnLinux(x => x.AddProductUuid());
       // not available on Mac

// V5:
builder.AddSystemUUID();

// V6:
builder.OnWindows(x => x.AddProcessorId())
       .OnLinux(x => x.AddCpuInfo());
       // not available on Mac

Strong naming

From version 5 onwards, the assemblies in this package are strong named for the convenience of those users who require strong naming. Please note, however, that the key files are checked in to this repository. This means that anyone can compile their own version and strong name it with the original keys. This is a common practice with open source projects, but it does mean that you shouldn't use the strong name as a guarantee of security or identity.

License and copyright

Copyright Matthew King 2015-2021. Distributed under the MIT License. Refer to license.txt for more information.

Support DeviceId

Community support is greatly appreciated. You can help in the following ways: