Repository navigation
docs: separate client-key and admin-key usage; describe installation ID accurately - #11
Merged
Merged
Conversation
…ID accurately Split the README usage example into an in-app part (product-bound client key: installation ID, activate, deactivate) and a server part (admin key: create keys and customers, block, unblock), and say why an admin key must never ship in an app. SignKey is shown on the server, since it needs an admin key. Describe GetOrCreateInstallationId as what it is: a random GUID combined with the machine fingerprint and a timestamp, hashed and saved to disk, not anchored to hardware. Same for its XML doc comment, which also no longer claims write failures throw. Also: GetCustomerWithKeys returns the customer's keys only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
README and XML doc-comment changes only. No code behaviour changes.
Client key vs admin key
The usage example called
CreateKey, which needs an admin key, right next to code that reads this machine's installation ID. Copied into a desktop app, that ships an admin key. The example is now two labelled parts:GetOrCreateInstallationId,ActivateKey(also used to re-check at start-up, since re-activating the same host reuses its slot),DeactivateKeywithHostId(required for client keys). Uses a product-boundclientkey.CreateCustomer,CreateKey(withAllowedHostsas an optional value reported by the app),BlockKey,UnblockKey. Loads the key from the server environment.It also says why: anything compiled into an app can be extracted. A note lists which calls need admin and which need at least
read-only(GetKey, the customer reads), so those stay on the server too.The Offline Licenses section already said
SignKeyneeds an admin key, but also said to call it "while the machine is online", which reads as in-app. It is now shown on the server, with the app sending its host ID and receiving the.licfile. The idempotency example (CreateKey) is marked as server code.Machine Identity
The README said
GetOrCreateInstallationId"Generates a stable UUID anchored to hardware". WhatServices/Identity.csdoes: on first call it joins a random GUID, theGetMachineId()fingerprint (empty if unreadable) and a millisecond timestamp, writes that to~/.keymint/installation-idunder the user profile folder, and returns the SHA-256 of the file contents. So the ID is random and file-backed, not anchored to hardware: hardware changes don't affect it, but deleting the file, reinstalling the OS or running as another OS user gives a new one. If the write fails, the exception is swallowed and each call produces a new ID. The README and the XML doc comment now say this. The doc comment claimed "guaranteed-unique, guaranteed-stable" and a "UUIDv4 seeded with hardware info", and its<exception>tag said write failures throwIOException; only reading an existing file can throw.GetMachineId()was described as based on "BIOS UUID, OS machine ID, and MAC address". It hashes the first usable one of those (on macOS the "OS machine ID" layer is the hardware serial number) and returnsnullif none is readable. Reworded.Other fixes
GetCustomerWithKeyswas described as "Gets a customer along with their license keys". It returns only the customer's keys. Reworded.Checks
dotnetis not installed on the machine this was prepared on, sodotnet buildwas not run. The only source change is inside///XML doc comments; the new<see cref="GetMachineId"/>refers to a method in the same class.