1# machineid provides support for reading the unique machine id of most host OS's (without admin privileges) 2 3![Image of Gopher 47](logo.png) 4 5… because sometimes you just need to reliably identify your machines. 6 7[![GoDoc](https://godoc.org/github.com/denisbrodbeck/machineid?status.svg)](https://godoc.org/github.com/denisbrodbeck/machineid) [![Go Report Card](https://goreportcard.com/badge/github.com/denisbrodbeck/machineid)](https://goreportcard.com/report/github.com/denisbrodbeck/machineid) 8 9## Main Features 10 11* Cross-Platform (tested on Win7+, Debian 8+, Ubuntu 14.04+, OS X 10.6+, FreeBSD 11+) 12* No admin privileges required 13* Hardware independent (no usage of MAC, BIOS or CPU — those are too unreliable, especially in a VM environment) 14* IDs are unique<sup>[1](#unique-key-reliability)</sup> to the installed OS 15 16## Installation 17 18Get the library with 19 20```bash 21go get github.com/denisbrodbeck/machineid 22``` 23 24You can also add the cli app directly to your `$GOPATH/bin` with 25 26```bash 27go get github.com/denisbrodbeck/machineid/cmd/machineid 28``` 29 30## Usage 31 32```golang 33package main 34 35import ( 36 "fmt" 37 "log" 38 "github.com/denisbrodbeck/machineid" 39) 40 41func main() { 42 id, err := machineid.ID() 43 if err != nil { 44 log.Fatal(err) 45 } 46 fmt.Println(id) 47} 48``` 49 50Or even better, use securely hashed machine IDs: 51 52```golang 53package main 54 55import ( 56 "fmt" 57 "log" 58 "github.com/denisbrodbeck/machineid" 59) 60 61func main() { 62 id, err := machineid.ProtectedID("myAppName") 63 if err != nil { 64 log.Fatal(err) 65 } 66 fmt.Println(id) 67} 68``` 69 70### Function: ID() (string, error) 71 72Returns original machine id as a `string`. 73 74### Function: ProtectedID(appID string) (string, error) 75 76Returns 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). 77 78## What you get 79 80This package returns the OS native machine UUID/GUID, which the OS uses for internal needs. 81 82All machine IDs are usually generated during system installation and stay constant for all subsequent boots. 83 84The following sources are used: 85 86* **BSD** uses `/etc/hostid` and `smbios.system.uuid` as a fallback 87* **Linux** uses `/var/lib/dbus/machine-id` ([man](http://man7.org/linux/man-pages/man5/machine-id.5.html)) 88* **OS X** uses `IOPlatformUUID` 89* **Windows** uses the `MachineGuid` from `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography` 90 91## Unique Key Reliability 92 93Do note, that `machine-id` and `MachineGuid` can be changed by root/admin, although that may not come without cost (broken system services and more). 94Most 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). 95 96**Linux** users can generate a new id with `dbus-uuidgen` and put the id into `/var/lib/dbus/machine-id` and `/etc/machine-id`. 97**Windows** users can use the `sysprep` [toolchain](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation) to create images, which produce valid images ready for distribution. Such images produce a new unique machine ID on each deployment. 98 99## Security Considerations 100 101A 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. 102 103> A reliable solution is to hash the machine ID in a cryptographically secure way, using a fixed, application-specific key. 104 105That way the ID will be properly unique, and derived in a constant way from the machine ID but there will be no way to retrieve the original machine ID from the application-specific one. 106 107Do something along these lines: 108 109```golang 110package main 111 112import ( 113 "crypto/hmac" 114 "crypto/sha256" 115 "fmt" 116 "github.com/denisbrodbeck/machineid" 117) 118 119const appKey = "WowSuchNiceApp" 120 121func main() { 122 id, _ := machineid.ID() 123 fmt.Println(protect(appKey, id)) 124 // Output: dbabdb7baa54845f9bec96e2e8a87be2d01794c66fdebac3df7edd857f3d9f97 125} 126 127func protect(appID, id string) string { 128 mac := hmac.New(sha256.New, []byte(id)) 129 mac.Write([]byte(appID)) 130 return fmt.Sprintf("%x", mac.Sum(nil)) 131} 132``` 133 134Or simply use the convenience API call: 135 136```golang 137hashedID, err := machineid.ProtectedID("myAppName") 138``` 139 140## Snippets 141 142Don't want to download code, and just need a way to get the data by yourself? 143 144BSD: 145 146```bash 147cat /etc/hostid 148# or (might be empty) 149kenv -q smbios.system.uuid 150``` 151 152Linux: 153 154```bash 155cat /var/lib/dbus/machine-id 156# or when not found (e.g. Fedora 20) 157cat /etc/machine-id 158``` 159 160OS X: 161 162```bash 163ioreg -rd1 -c IOPlatformExpertDevice | grep IOPlatformUUID 164``` 165 166Windows: 167 168```batch 169reg query HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography /v MachineGuid 170``` 171or 172* Open Windows Registry via `regedit` 173* Navigate to `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography` 174* Take value of key `MachineGuid` 175 176## Credits 177 178The Go gopher was created by [Denis Brodbeck](https://github.com/denisbrodbeck) with [gopherize.me](https://gopherize.me/), based on original artwork from [Renee French](http://reneefrench.blogspot.com/). 179 180## License 181 182The MIT License (MIT) — [Denis Brodbeck](https://github.com/denisbrodbeck). Please have a look at the [LICENSE.md](LICENSE.md) for more details. 183