How license keys work

A license key looks like a random string, but how it is made decides almost everything else: whether it can be cracked, whether you can revoke it, and whether your app works without a network connection. This page walks through the usual approaches and why Keygate uses the one it does.

Three ways to make a key#

Algorithmic keys

The oldest approach: the key is built by a formula, for example a few characters plus a checksum, and the app checks it by running the same formula. No server is needed. The problem is that the formula ships inside every copy of the app. Once someone extracts it, they can write a key generator, and every key it produces is as valid as one you sold. There is also no way to take a key back.

Signed keys

The key is a small piece of data, such as the customer and an end date, signed with a private key. The app holds only the public key, so it can check the signature but cannot create new keys. That fixes key generators. It still leaves keys that cannot be revoked, and the keys get long, because a signature alone is 64 bytes or more.

Random keys checked by a server

The key is just a random identifier, and a server knows what it belongs to. The app asks the server whether the key is valid. Keys stay short, can be revoked or refunded at any time, and the server can limit how many devices use each one. The cost is that the app needs the server at least once.

Keygate combines the last two: keys are random and checked by your server, and every answer from the server comes with a signed token the app can check offline afterwards.

Generating a random key#

A random key needs two things: enough randomness that nobody can guess one, and a format people can type. Keygate keys look like KG-4F2TLTRG-RWFPA6X4-WHZU639Y-2ADL6KY2: 32 characters from an alphabet without look alike characters such as I, O, 0 and 1. That is about 160 bits of randomness, far beyond what anyone can guess. In Python the same idea takes a few lines:

import secrets

ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"  # no I, O, 0 or 1

def new_key(prefix: str = "KG") -> str:
    groups = ["".join(secrets.choice(ALPHABET) for _ in range(8)) for _ in range(4)]
    return "-".join([prefix, *groups])

Use a cryptographic random source, secrets in Python or crypto/rand in Go, never the ordinary random module, whose output can be predicted.

Validating a key#

Checking a random key happens in two steps:

• Activation, once: the app sends the key and an identifier for the device. The server checks that the license is active and that a device slot is free, then records the device.
• Verification, from then on: the app sends the same pair, and the server answers whether this device may still use the license.

Verification should look the same for every kind of failure. If a made up key answers differently from a revoked one, anyone can use the difference to find real keys. Keygate answers verify with 404 LICENSE_NOT_FOUND in every case, and locks out an address after repeated failed calls. Activating licenses in your app shows the calls in full.

Working offline#

Asking the server on every start would lock customers out on a plane or behind a firewall. So after each successful check, Keygate returns a token signed with Ed25519. It names the license, the device and the time the app should check in again. The app stores it and verifies the signature with a public key on later starts, without any network call. When the token is due, the app asks the server again and gets a fresh one.

How long a token lasts is a trade off you choose per plan: a week is a common default. Shorter means a canceled license stops working sooner; longer suits customers who are often offline.

Common mistakes#

• Putting a secret in the app. An API key or private key inside a shipped app can be extracted. The license key itself should be the only credential the app sends.
• An identifier that changes. If the device identifier changes between runs, every start looks like a new device and uses up a slot. Use the operating system's machine ID.
• Locking people out when the network fails. Flaky connections are far more common than pirates. Give a few days of grace before turning features off.
• Forgetting refunds. A key should stop working when its payment is refunded or disputed, which means your payment provider has to reach your license system.