Licensing Concepts¶
Licensing concepts are documented here as they are reverse engineered from the previous version. The previous version's behavior is the specification: this documentation describes it, it does not redesign it.
Every rule on this page is implemented by the validator library
PackageGarden.Licensing, which every Soeteman Software package embeds. See
Integrating the validator for how a package uses it.
The three secrets of a product¶
A package that uses licensing carries three encrypted values:
| Value | Where it lives | Contents |
|---|---|---|
| Product key | Compiled into the package | The product's own AES key and IV, encrypted with the fixed generator key of the licensing system |
| Product parameters | Compiled into the package | Trial settings: supportsTrial and trialIsLocalHostOnly |
License file (.lic) |
Installed by the customer | The license itself, encrypted with the product's key |
All three are Base64 text containing encrypted XML in the namespace
http://www.soetemansoftware.nl/licensing/license/1.0. The encryption is AES-256 in
CBC mode with PKCS7 padding.
An empty or corrupt product key or product parameters make the validator throw
LicenseKeyCorruptException: that is a packaging error, not a customer problem.
The license file¶
A license holds:
| Field | Meaning |
|---|---|
product, company, email |
Who the license was issued to, for which product |
licenseType |
Domain, Server or Unlimited |
alwaysAllowLocalhost |
Also valid on local requests (see below) |
validUntilVersion |
Highest major package version the license covers; empty or 0 means any version |
licenseExpires |
Expiry date and time; empty means it never expires |
generated |
When the license was issued (informational) |
allowedDomainOrIps |
The licensed domains (Domain license) or IP addresses (Server license) |
A license file that cannot be decrypted with the product's key, for example the license of another product, is simply invalid; the validator does not throw.
How a license is checked¶
The checks run in this order. The first one that fails makes the license invalid.
- Version. When
validUntilVersionis set (not0) and lower than the package's major version, the license is invalid: "The license was valid until version '{n}'." - Expiry. When
licenseExpiresis set and earlier than the current local date and time, the license is invalid: "The license was valid until '{date}'." An expiry earlier today is already expired. - License type.
- Unlimited: valid on every host and server.
- Server: valid when one of the IP addresses of the machine running the site is
exactly one of the licensed IPs. Partial matches do not count:
95.1.5does not match95.1.5.77. - Domain: valid when the requested host name ends with a licensed domain,
ignoring case. A license for
example.comcoversexample.comandwww.example.com, and alsoexample.com.localandwww.example.com.local. It does not coverexample.co.uk.
The version and expiry checks apply to every license type, including Unlimited.
Local requests and alwaysAllowLocalhost¶
A request is local when:
- the remote and local IP address of the connection are the same, or
- there is no local IP address and the remote address is a loopback address, or
- no remote IP address is known (
::1counts as not known).
When the license has alwaysAllowLocalhost and the request is local:
- a Domain license also accepts the host
localhost; - a Server license is valid regardless of the machine's IP addresses.
Requests without an HTTP context¶
Outside a request (a background job, a scheduled task, startup code) the validator has
no host, no local flag and no IP list. The host is then reported as Unkown (the
legacy spelling is kept), a Domain license is invalid, and a Server license is invalid.
The validator does not throw.
Messages for invalid licenses¶
GetInvalidLicenseMessage() returns the reason of the last failed check, followed by
the package's support text. Domain and Server messages are HTML: they contain <br/> and
list the licensed domains or IPs as <ul><li>…</li></ul>, or None. Packages show
these messages as they are.
Example for a domain license on the wrong host, with support text "Please contact support" (one line in reality):
The license for domain 'www.other.com' is invalid. Please contact support.<br/>Your license has been approved for the following Domains: <br/><ul><li>example.com</li><li>example.com.local</li></ul>
Licensed domains and IPs¶
LicensedDomainsOrIps() lists what a license covers, for display in a package:
- Server: the licensed IP addresses.
- Domain: every licensed domain and its
.localvariant, pluslocalhoston a local request when the license hasalwaysAllowLocalhost. - Unlimited: nothing, except
localhoston a local request when the license hasalwaysAllowLocalhost. - No license file: an empty list.
Trials¶
Trials are controlled by the product parameters, not by a license:
supportsTrial |
trialIsLocalHostOnly |
Without a license file |
|---|---|---|
false |
any | Not licensed |
true |
false |
Trial on every request |
true |
true |
Trial on local requests only |
- A trial applies only when there is no license file (none, or an empty one).
- When a license file is present, the package is never in trial, even when the license is invalid. An invalid license does not fall back to a trial.
- A valid trial counts as valid:
IsValid()andIsTrial()both returntrue.
Caching¶
A package normally creates one validator and keeps it:
IsValid()remembers a valid result. An invalid result is checked again on the next call.IsTrial()remembers its first result.- The host, local flag and IP addresses are read once, when the validator is created.
Known limitation¶
The licensing scheme is symmetric: the key that decrypts a license can also encrypt one. Someone who extracts the keys from a package could in theory create licenses. A stronger scheme (signed licenses) would invalidate every existing license, so it is out of scope for this version.