/machineid

Get the unique machine id of any host (without admin privileges)

Primary LanguageCrystalMIT LicenseMIT

machineid

Inspired from Go's machineid. machineid provides support for reading the unique machine id of most host OS's (without admin privileges)

Main Features

  • Cross-Platform (tested on Win7+, Debian 8+, Ubuntu 14.04+, OS X 10.6+, FreeBSD 11+)
  • No admin privileges required
  • Hardware independent (no usage of MAC, BIOS or CPU — those are too unreliable, especially in a VM environment)
  • IDs are unique1 to the installed OS

Installation

  1. Add the dependency to your shard.yml:

    dependencies:
  machineid:
    github: razorinc/machineid

  2. Run shards install

Usage

require "machineid"

Function: ID() (string)

Returns original machine id as a string.

Function: ProtectedID(appID string)

Returns hashed version of the machine ID as a string. The hash is generated in a cryptographically secure way, using a fixed, application-specific key (calculates HMAC-SHA256 of the app ID, keyed by the machine ID).

What you get

This package returns the OS native machine UUID/GUID, which the OS uses for internal needs.

All machine IDs are usually generated during system installation and stay constant for all subsequent boots.

The following sources are used:

  • BSD uses /etc/hostid and smbios.system.uuid as a fallback
  • Linux uses /var/lib/dbus/machine-id (man)
  • OS X uses IOPlatformUUID
  • Windows uses the MachineGuid from HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography

Unique Key Reliability

Do note, that machine-id and MachineGuid can be changed by root/admin, although that may not come without cost (broken system services and more). Most IDs won't be regenerated by the OS, when you clone/image/restore a particular OS installation. This is a well known issue with cloned windows installs (not using the official sysprep tools).

Linux users can generate a new id with dbus-uuidgen and put the id into /var/lib/dbus/machine-id and /etc/machine-id. Windows users can use the sysprep toolchain to create images, which produce valid images ready for distribution. Such images produce a new unique machine ID on each deployment.

Security Considerations

A machine ID uniquely identifies the host. Therefore it should be considered "confidential", and must not be exposed in untrusted environments. If you need a stable unique identifier for your app, do not use the machine ID directly.

A reliable solution is to hash the machine ID in a cryptographically secure way, using a fixed, application-specific key.

Development

TODO: Write development instructions here

Contributing

  1. Fork it (https://github.com/razorinc/machineid/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Contributors