Offline license activation and validation

Two kinds of offline

• Intermittently connected. Laptops on planes, unreliable networks, a license server down for maintenance. The application has been online before and will be again. A lease cached after the last online check is the usual answer.
• Never connected (air-gapped). Machines in secure facilities or on isolated networks. They need a license that can be delivered on a USB stick or by copy and paste, and an activation that does not require the machine to reach a server.

Three common approaches

Velsigil’s SDKs implement the first: signed offline leases for your applications. Its panel can also issue signed license files (a feature of Velsigil’s Studio plan), which Velsigil itself uses for its self-hosted installations; the SDKs do not verify them. Velsigil does not implement request-and-response file activation.

How a signed offline lease works

Every successful online validation returns a fresh lease when the product allows offline use. A Velsigil lease is a compact signed token:

token    = base64url(JSON payload) "." base64url(Ed25519 signature over the first part)
payload  = { v, typ: "lease", productId, licenseId, activationId, hwidHash,
             plan, features, licenseExpiresAt, iat, exp }
hwidHash = SHA-256(hwid)
exp      = min(iat + offlineLeaseHours * 3600, licenseExpiresAt)

Offline, the SDK accepts a stored lease only if, in this order: the signature verifies with the public key built into the application; typ is lease; the product ID matches; hwidHash equals the SHA-256 of this device’s hardware ID; and the current time is before exp. Because exp is capped by the license’s expiry, a lease never outlives the license. Because it is bound to the device, copying a lease to another computer does not work.

Choosing a lease length

The seller sets the offline lease hours per product, from 0 (no offline use) to 8,760 (one year). The default is 24 hours.

• Short leases (hours to a day) bound how long a revoked, refunded or shared license keeps working on a device that stays offline. Users with poor connections see more interruptions.
• Long leases (weeks) suit users who travel or work in the field. A revoked or shared key keeps working on devices that stay offline until the lease ends.

Whatever you choose, the lease never runs past the license’s own expiry date.

Clock tampering: an honest limitation

An offline check has nothing to compare against except the device’s own clock. A signature proves when a lease was issued, not what time it is now. A user who sets the clock back can keep the device’s time before the lease’s expiry for longer than the real lease period. No offline scheme can fully prevent this.

Velsigil’s SDKs use the local clock plus an offset they learned from a signed server answer, and an online check replaces the lease whenever the server is reachable. Beyond that, the defense is keeping lease hours as short as your users can tolerate and validating online whenever possible.

Revocation reaches a device at its next contact

Revoking a license on the server cannot reach a device that stays offline. What matters is what happens the next time it connects. Velsigil’s SDKs delete the stored lease as soon as the server gives a signed, definitive refusal: invalid key; expired, suspended, revoked or banned license; revoked device; failed device verification; device limit reached; device not activated or not found; blacklisted; or product disabled. A successful check without a lease, because the seller turned offline use off, also deletes it.

Other refusals keep the lease, such as maintenance (product_paused), a required update or a temporary activation limit. So a revoked license stops working offline as soon as the application reaches the server once.

Fall back only on network errors

The most important rule in an offline design is when to use the cached lease. If an application falls back whenever the online check fails, an attacker only has to block or tamper with the answer to switch it into offline mode. Velsigil’s SDKs for C#, C++, Python and Node.js fall back only on network_error: no connection, a DNS, TLS or timeout failure, or a 502, 503 or 504 from a gateway without a Velsigil error body. Any answer from the server, including an unsigned error, is returned as is, and an answer that fails verification is invalid_response, never an offline pass.

License files for self-hosted software

Leases fit applications that are online most of the time. Server software that customers install on their own networks needs something that works without any network call: a signed license file, delivered with the software and verified with a public key built into it.

Velsigil itself, installed on a buyer’s server, is licensed with a signed license file (.lic) instead of a lease. With Velsigil’s Studio plan, the panel can issue such files per product (opt-in):

• A file is signed with the product’s key and states which releases it covers (“updates until”).
• It is either perpetual or, for subscription plans, states the end of the paid term (“valid until”) and of a grace period (“grace until”, 0 to 90 days, 14 by default).
• The format has no expiry check: a file never becomes invalid with time. The instance count in it is informational; an offline file cannot enforce it.

License files and leases are separate mechanisms. The Velsigil SDKs verify leases, not license files: to use license files in your own software, you would need your own verifier.