Skip to content

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.

  1. Version. When validUntilVersion is set (not 0) and lower than the package's major version, the license is invalid: "The license was valid until version '{n}'."
  2. Expiry. When licenseExpires is 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.
  3. 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.5 does not match 95.1.5.77.
    • Domain: valid when the requested host name ends with a licensed domain, ignoring case. A license for example.com covers example.com and www.example.com, and also example.com.local and www.example.com.local. It does not cover example.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 (::1 counts 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 .local variant, plus localhost on a local request when the license has alwaysAllowLocalhost.
  • Unlimited: nothing, except localhost on a local request when the license has alwaysAllowLocalhost.
  • 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() and IsTrial() both return true.

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.