New Validation System Explained – EmEditor (Text Editor)

On version 24.0.0, we introduced a registration validation system to improve the already existing registration system. This validation system is able to track the number of devices a customer has registered EmEditor on.

This blog serves to be transparent about our motivations and to document how the validation system works. If we update the validation system in the future, we will also update this page.

Motivation

In the past, there was no way for us to detect a user who is sharing their license with ten other people, or those who are using their license on more devices than allowed by the EULA (end-user license agreement). We would like customers to purchase enough licenses to follow the terms of the license. This would ensure fairness among customers who have purchased multiple licenses.

Requirements

This section lists the requirements we had for the validation system.

Functional

The validation system should loosely enforce the device limit clause of the license. It should not sacrifice customer satisfaction, so we should not make this limit a surprise.
Registration is run once upon submission of the Register Product dialog box or any of the other registration flows. Validation is run once every time the EmEditor is opened.
Registration requires EmEditor to be able to connect to support.emeditor.com via HTTP. Validation does not require internet connection.
Users should be able to use an offline license that allows the app to register and validate without connecting to our server. In case a user experiences errors with normal registration, an offline license would allow an alternative way to register.
Privacy rights of users should be maintained. The collection of personal information will be opt-in.
It should fit into the existing registration system and not make it a new way to register. Current users should be able to register without having to learn new steps.
- Uninstalling the app should unregister the device.
Users can log in to the Emurasoft Customer Center to view devices so that devices can be unregistered outside of the app.
Customers who have purchased from non-2Checkout resellers will have to register the product and create a customer center account. This is because there will be no way for them to see their devices online without an account.
The system should be tested in the background in version 23. It should be fully in effect from version 24.

Technical

The system should be simple so that it is easier to maintain.
A machine can be identified with a machine ID.
- We determined that the registry value
  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\MachineGuid
  is a suitable ID.
- EmEditor Portable can be installed on a USB, with its settings stored in the USB. The USB can be used on many machines, and the validation system would detect different machine IDs. Therefore if the app detects that it is a portable version running on a USB, registration does not occur.
EmEditor can be installed per-user on a multi-user machine. We must combine all EmEditor installations on the same machine as one unit to the device count.
There should be a way to override the limit for a given registration key, just in case.
A signed token containing the device info should be stored on the user’s device. This associates the current device with the device record stored in the database.
The system should be able to integrate a floating license system if we decide to in the future.

Output

You can view a list of all devices on the Registered Devices page of customer center.
If the device limit is reached, a notification will appear. The user can still use the app even if the device limit is exceeded.

If the user bought the app from a non-2Checkout reseller and has not registered the product, a notification will ask the user to register the product.

Device table

The device table is stored in our database and records all devices that were registered. Note that a History record is associated with a purchase and it is where a registration key is stored. A Device record is defined in Go as follows.

type Device struct {
	DeviceID             string
	UserID               int
	HistoryID            sql.NullInt64
	StripeSubscriptionID sql.NullString
	MachineID            uuid.UUID
	RegistrationDate     time.Time
	ValidationDate       time.Time
	InstallationType     InstallationType
	Label                string
	Unregistered         bool
}

The fields are explained in the documentation for Registered Devices.

Privacy measures for label

The Label field may contain personal information. The Label device field in the Register Product dialog box defaults to {computer name} {user name}. The personal information inside the label field is not necessary for the basic functionality of the app. Therefore, we made the label field opt-in to stick to our policy of privacy by default.

Local Device token

A LocalDevice token is stored locally on the user’s device in the form of a JWT (JSON Web Token). It associates the current device with the database Device record. It also allows EmEditor to do some validation even if it is offline. The token payload is defined as follows.

type LocalDevice struct {
	DeviceID  string
	MachineID uuid.UUID

	// StripeSubscriptionID is empty if this device is not associated with a subscription.
	StripeSubscriptionID string
}

The expiration date of the token is set to the expiration date of the registration key.

For per-user installations, the token is stored in the registry as LocalDeviceToken in Computer\HKEY_CURRENT_USER\Software\EmSoft\EmEditor v3\Common.

Device count

This section describes how we determine how many devices you can register. This is subject to change if we change the terms of the EULA.

To calculate the number of units towards the device limit for a specific registration key, we use the following MySQL query.

SELECT count(DISTINCT MachineID) as deviceCount
FROM devices
WHERE HistoryID=? AND Unregistered=FALSE

For Stripe subscriptions, the following query is used.

SELECT count(DISTINCT MachineID) as deviceCount
FROM devices
WHERE StripeSubscriptionID=? AND Unregistered=FALSE

For a given history ID, we first get all devices that are still registered. Then we count the number of unique machines. If there are multiple devices with the same MachineID, they are likely multiple per-user installations on the same machine.

The EULA allows the licensee to install EmEditor to up to two devices per license. If EmEditor is for personal use and not installed on corporate computers, the licensee can install EmEditor to five devices per license.

Offline registration

An offline license allows a user to register without an internet connection. Registration only requires a license file.

A customer can request an offline license file. The customer must include their registration key or Stripe order ID in the request. We will reply to the customer’s email address within a few business days with the license file. The license file is a text file that contains a JWT token with the following payload.

type LicenseFile struct {
	LicenseID string
	UserID    int
	FullName  string
	Email     string

	// Is nil if not a Stripe subscription
	StripeSubscriptionID *string

	// Is nil if not a registration key
	HistoryID *int
}

The offline license token is saved to the registry entry OfflineLicense.

There are three ways that the device limit is enforced and illegal sharing of the license file is prevented. 1) When EmEditor can access the internet, validation is performed. 2) We will only send the license file via email instead of downloading from our website. 3) The Registration Information dialog will display the license owner’s full name and email.

OfflineLicense table

Usage of offline licenses is tracked using the OfflineLicense table. It includes the machine ID to track how many machines used the license and the Revoked flag to allow us to revoke a license.

type OfflineLicense struct {
	LicenseID            string
	UserID               int
	MachineID            uuid.UUID
	StripeSubscriptionID sql.NullString
	HistoryID            sql.NullInt64

	// Revoked indicates that this license cannot be used
	Revoked bool
}

Registration Information dialog box

Registration Information displays information about the user’s registration. This is useful for knowing what your registration status is, and to diagnose any issues with validation. It also allows the user to edit the device information and to unregister.

The dialog runs validation and shows whether or not it was successful.

Registration process

There are four scenarios where registration may happen.

Most users will register through the Register Product dialog box.
Register using the MSI installer.
Offline registration using the command line.
If you unregistered a device, then opened EmEditor on that device, the device will be registered automatically.

There are two online registration flows, depending on if a registration key is used (RegisterDevice()) or a Stripe subscription is used (RegisterDeviceSubscription()). The third registration flow is for offline registration (StoreOfflineLicenseAndValidate()).

In this section, “Client” refers to the local EmEditor app on the user’s machine. “Server” is our backend server and database.

Finding a subscription to use

If the user signed in, the server tries to find a valid Stripe subscription that has 0 associated devices.
If no subscription has 0 associated devices, then it tries to find a subscription that has not exceeded the device limit.
1. If there is a usable Stripe subscription, RegisterDeviceSubscription() is called.
2. If such Stripe subscription does not exist, it will find a valid registration key that has not exceeded the device limit. RegisterDevice() is used for registration keys.

Registration with registration key (RegisterDevice())

If a device token already exists, the client sends an unregister request to the server. The token and registration key is deleted from the registry.
The client sends a registration request to the server, which includes the registration key, machine ID, label, and installation type.
The server queries deviceCount (defined in previous section) to determine if the registration key can be used to register the device
A Device record is created.
The client receives the device ID. Using the device ID, the client requests a local device token.
The server creates and responds with the local device token. The expiration date of the token is set to the registration key expiration date. The client writes the token to local storage.

Registration with Stripe subscription (RegisterDeviceSubscription())

If a device token already exists, the client sends an unregister request to the server. The token and registration key is deleted from the registry.
The client sends a registration request to the server, which includes the Stripe subscription, machine ID, label, and installation type.
The server verifies that the Stripe subscription is valid.
The server queries deviceCount (defined in previous section) to determine if the Stripe subscription can be used to register the device.
A Device record is created.
The client receives the device ID. Using the device ID, the client requests a local device token.
The server creates and responds with the local device token. The expiration is set to one month in the future if the subscription status is active. If the subscription status is canceled, the expiration date is set to the end date of the current billing period. The client writes the token to local storage.

Registration with offline license (StoreOfflineLicenseAndValidate())

The user registers an offline license by saving the license file to the filesystem, then running the command line option

/ol "licenseFilePath"

This list outlines the offline registration process.

Delete the registration key, local device token, and offline license token from the registry.
Read the license file and save it to the registry.
Run ValidateDevice().

Validation process (ValidateDevice())

Validation occurs every time the app is opened.

If local device token does not exist in the registry, call ValidateOfflineLicense().
The token’s signature is validated. The actual machine ID is compared with the machine ID in the token. The result is ignored if the app is running on a removable drive.
- If validation fails due to expected reasons such as a mismatched machine ID, the reason is outputted as status text, and the device token is deleted.
- For other unexpected errors such as network error, validation succeeds.
A random number generator determines if validation should stop here. This is to reduce the load of requests to our server.
The validation function sleeps the thread for a certain duration. This is again to reduce the request load, as we assume that macros and other automated use cases that rapidly start and close the app would only run it for a short duration.
The client requests the Device data for the stored device ID.
If the device is associated with a Stripe subscription, the server verifies that the Stripe subscription is valid.
If device.Unregistered == true, the client attempts to register the device.
The device.ValidationDate is updated.
If the token was issued before current time - 7 days, a new token is created to replace the old token.

Offline license validation process (ValidateOfflineLicense())

Offline license validation occurs if the registry does not contain the local device token. If an unexpected error occurs, validation succeeds. This means that if the user is offline, validation will still succeed.

If the offline license token does not exist, validation succeeds. One case where this may happen is if registration previously failed due to a network error but the registration key was valid. This allows EmEditor to be used in such case.
Read and validate the token.
Request the server to validate the offline license with the token and machine ID.
The server validates the token.
For Stripe subscriptions, the server checks that the subscription has the status “active”.
If an OfflineLicense entry for the license ID does not exist, it is created with the token data.
If the entry exists and license.Revoked == true, it returns StatusLicenseRevoked. Otherwise validation succeeds.

Uninstallation

When you uninstall the desktop version of EmEditor, your device will automatically be unregistered. This makes it easy to install to another machine without having to unregister the previous device manually. Because the portable and Store App versions do not have an uninstallation process, they will not unregister automatically when you remove those apps. Therefore if you have a portable or Store App and you are no longer using it on your device, you must manually unregister it from the Registered Devices page in Customer Center.

Support

If you have any questions or feedback about the validation system, feel free to send us a message.