License key security: sharing, keygens and replayed answers

The threat model

Random keys instead of checksum keys

Many older schemes generate keys with a checksum or a hidden formula that the application checks offline. Once someone reverse-engineers the formula, they can write a key generator that produces unlimited valid keys. The fix is to make a key a random lookup token: the application cannot tell a valid key from an invalid one; only the server can.

Velsigil keys look like PREFIX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX: an optional product prefix and 25 characters drawn from a 31-character alphabet by a cryptographic random generator, about 124 bits. Guessing one is not practical, and the server limits how fast anyone can try.

Asymmetric signatures: the app can verify but not sign

If an application trusted a plain “valid” from the network, anyone could stand up a fake server or edit the response. With an asymmetric signature, the server signs each answer with a private key, and the application verifies it with the matching public key built into it. A public key cannot create signatures, so extracting it from the binary does not help an attacker.

Velsigil gives each product its own Ed25519 key pair; the private key never leaves the server and is never exported. The SDKs verify the signature over the exact bytes of the answer before parsing anything, and never pick the key from the answer itself. That is also why the public key, product ID and API URL must be compiled in: a user who could change the public key in a settings file could run their own server with their own key.

Requests from the application are deliberately not signed: any secret embedded in a client binary can be extracted, so it would add no security.

Replay protection

A genuine signed answer is still dangerous if it can be reused. Velsigil binds every answer to its request:

• Each request carries a fresh 32-byte random nonce, and the signed answer must echo it, so a recorded answer does not match the next request.
• Each request carries a timestamp. The server refuses requests outside the allowed clock skew (300 seconds by default) with a signed clock_skew, and the SDK corrects its offset and retries once.
• The server remembers the nonces it accepted. A repeated nonce gets a signed replay_detected and raises a security event.
• For device-bound requests, the signed answer names the device it was produced for, and an answer for another device is rejected.

Keys stored as hashes

A license database is a list of things people pay for. Velsigil never stores the raw key: the database keeps a keyed HMAC-SHA256 of it (keyed with the server’s master secret), the prefix and the last five characters for support. A key is shown once, when it is created or regenerated, and exports never contain raw keys. Regenerating a key creates a new one and invalidates the old key’s portal sessions and download links. Device secrets and API keys are likewise stored only as hashes.

Making sharing visible and limited

You cannot stop a customer from telling a friend their key. You can make it pointless beyond the device limit, and visible when it happens:

• Limits: a maximum number of devices per plan or license, a daily activation limit and an optional cooldown between new devices.
• Device secrets: a spoofed hardware ID without the secret shows up as a mismatch, and with strict binding is refused.
• Detectors in the security center: device churn, more than 10 IP addresses per license in an hour, more than 3 countries in a day (with Cloudflare in front), replays and secret mismatches.
• Actions: suspend, revoke or ban a license; a ban can blacklist every device on it and the customer’s email address.

Detectors only flag. Velsigil never bans a license automatically; you decide. The hardware-locked licensing guide covers device binding in detail.

Brute-force limits

The client API allows 60 requests a minute per IP address and 30 per license key and per hardware ID. Twenty or more invalid keys from one IP address within 10 minutes block that address from the client API for 30 minutes and raise a license_bruteforce event. On the Linux setup, Caddy adds an edge limit of 60 requests per 15 seconds per IP address.

What no licensing system can stop

Everything above makes server answers impossible to forge without your signing keys, and makes sharing visible. None of it stops a determined person from patching the check out of your program. Obfuscation, packers, native compilation and integrity checks raise the cost; none of them is a security boundary. Design with that in mind:

• Keep what is valuable on your server: cloud features, content, data and updates. A cracked client should get as little as possible. Velsigil’s release downloads, for example, are only handed out after a server check.
• Check the license in more than one place and keep the result object, not one global boolean.
• Fail closed: anything other than a verified success means unlicensed.
• Treat a failed verification as an attack signal, not a network glitch.

The staff side

Attackers also go after the panel. Velsigil hashes staff passwords with Argon2id and rejects common and breached passwords; the breached-password check sends only the first five characters of a password’s hash. Owners and admins must use TOTP, and sensitive actions ask for the password and code again. Every change, sign-in and denied action goes to an audit log, kept for 365 days by default. If a product’s signing key leaks, rotate it: rotation destroys the old key and invalidates every build that embeds it, so plan it together with a client release.

Velsigil’s security requirements are based on OWASP ASVS 4.0.3 Level 2, a design target rather than a certification, and Velsigil has not had an external penetration test yet.