How Product Licensing Works With EasyLicenser
Server License Model (Professional
Edition Only)
User-Extensibility (Professional Edition
Only)
User Extensibility Mechanisms (Professional
Edition Only)
License Models And EasyLicenser Product
Editions
License Key Lifecycle Management
License Information Management
A Tour Of The Java Run Time Library
API
"Custom license parameter"
Interface
A Tour Of The C/C++ Run Time Library
API
License Key Management And Parameter
Interface
A Tour of Visual Basic 6 Application
Development with the C/C++ Run Time Library
A Tour Of The License Key Generation
Java API
Vendor-specific License Unit Policy
Class
Installation-specific EasyLicenser
Configuration Class
The purpose of this document is to explain the concepts behind EasyLicenser, the product’s architecture, and to provide an overview of working with EasyLicenser. The focus is on the underlying concepts and what you can do with EasyLicenser. The mechanics of working with EasyLicenser to accomplish the tasks can be found in the License Manager User Guide and API reference guides.
EasyLicenser is designed to support the primary activity of generating, distributing and validating keys with your product, as well as activities related to managing the keys and associated information on your customers and products.
Before you can start license protecting your products with EasyLicenser, you need to take the following preliminary steps:
In the steady state, you can either generate keys using the License Manager user interface console or (if you are licensed for the eCommerce option) with the key generation API’s. If you use the eCommerce option, you can maintain your own database of keys, customers and products. If you use the License manager console, EasyLicenser’s lightweight database manager is automatically used. In either case, you maintain a repository of all the keys that you generate.
The following diagram illustrates the process of managing keys with the License Manager console:
When you start the License Manager graphical console, the main screen you are presented with has all the widgets that are required to generate one key or batches of multiple keys.
EasyLicenser’s key components and their relationship are illustrated below:
The License Manager console provides the graphical user interface to simplify license key management. It is also required for management of an Easy License Manager installation.
The License Key Database Manager provides database management facilities for products, customers and license keys. It is used only by the License Manager Console.
License keys are generated using the License Key Generator Library. An eCommerce web site uses the library directly without user interaction. The License Manager Console also uses the library internally.
The EasyLicenser Configuration tracks the state of the EasyLicenser installation. It is automatically managed by the License Key Generator Library and the License Manager Console as keys are generated or vendor keys are updated.
On a given machine, you may have any number of EasyLicenser installations; however, only one installation may be active.
The License Key Checker Run Time Library is used to check a license key. There is a single Java run time library for all platforms, and one separate run time library for each ISV application platform and language combination, for Visual Basic and C/C++ applications. The appropriate language and platform specific run time library is distributed with your product, which uses it to check license keys at your end customer’s site. The Java run time library is also used internally by the License Manager console and License Key Generation Library components to validate end user keys and check vendor license keys.
The two license models that are supported by EasyLicenser are User and Server. Server licensing is available only with the Professional Edition.
The User license model is intended for development tools and end-user products that have the following characteristics:
The Server license model is intended for multi-user server products that have the following characteristics:
For a given license model, you may select a license type that defines at a more precise level how the licensing is measured. Associated with the license type, there may be one or more parameters that are specific to that type. An example of a license type is concurrent-user licensing for a server license model, accompanied by a “number-of-concurrent-users” parameter.
Only one license model and one corresponding license type may be in effect for a given license key. The exception is the extensibility mechanism, which can accompany or supersede a license type or model.
Orthogonal to license models and license types, there may be one or more licensing modes that limit the time and / or scope of the product’s usage. You may select any combination of licensing modes. Each licensing mode may be accompanied by one or more parameters that are specific to that mode. An example of a licensing mode is a time-limited license, accompanied by an “expiration date” parameter.
For any license model or type, you can optionally specify a mandatory operating system check for the associated user and / or host name against the environment in which it is running, without requiring application programming. This capability requires the Pro edition.
The supported license types are:
Only the user who installs the ISV’s product can use it. For example, if a customer “Joe” purchased the product from the ISV, then only Joe can use it.
If you opt for "soft" locking, your application may prompt for or otherwise obtain the user name and provide the information to the “check license key” EasyLicenser run time method in order to perform a validation.
If you specify operating system enforcement, the user name in the key is checked against the application's run time environment. The check can be limited to the operating system user account or a combination of the user name and the machine name.
The parameter that is associated with a named-user license is the user name. When an operating system check is enforced, the user name can be composed of an operating system user name and a machine name.
Your product is only licensed to be used on the machine on which it is installed. For example, if the product is installed on a machine with domain name “myworkstation.mycompany.com”, it is not supposed to be run from any other node on the network.
By default, node locking is logical and is intended to encourage compliance rather than impose an onerous administration burden on the end customer. That is, EasyLicenser does not by default physically match the supplied host name against the machine's network fingerprint. The end customer may freely rename the host machine or reconfigure its network topology without being required to communicate with you to exchange license keys or for any other purpose. However, the end customer is not supposed to make multiple product installations on different machines on the network.
If you specify operating system enforcement, the host name in the key is checked against the name of the machine on which the application is running.
You have the additional freedom to enforce any node locking strategy you desire, for example network card addresses and PROM Id's, by using the extensibility mechanism described below.
The parameter to the node-locked license type is the host name.
The server licensing model addresses the needs for licensing server products that have the characteristics of providing high business value, with relatively few installations, and that are accessed through client programs by potentially large numbers of concurrent users per instantiation. The products typically utilize large amounts of computing resources.
The license types that are supported by EasyLicenser are:
A specified maximum number of user accounts may be defined for use on the server. Typically, many concurrent users may be associated with each named user. The concept is applicable to a limited class of servers such as database management systems and packaged application systems that support the notion of registered users.
The parameter is the upper limit on the number of named users.
A specified maximum number of concurrent users can access the single instantiation of the server. A “user”, also known as a “device”, is typically a network connection to the server. Each such “user” may have many actual concurrent users associated with it through resource pooling mechanisms.
The parameter is the upper limit on the number of concurrent users.
A maximum number of CPU’s may be in use on the machine on which the server is running.
The parameter is the upper limit on the number of CPU’s on the machine, regardless of how the CPU’s on the machine may be logically partitioned (applies only to high end server hardware).
There is an upper limit on the total MHZ of CPU power on the machine on which the server is running.
All server license types have associated with them two parameters: a logical host name and an upper numeric limit specification whose meaning varies with the specific server license type: maximum number of named / concurrent users, CPUs or CPU MHZ.
You can utilize the extensibility mechanism described below to, among other things, complement the above license types. For example, you can specify an upper limit on the number of concurrent users that varies with the time of day.
EasyLicenser supports the following license parameters for all license models and types:
You can enable and disable features that you define for your products, ranging from restricted functionality to selective features and options. For example, an evaluation version of a development tool product may have certain printing and export / import functions marked as disabled. At the time of defining a new product, two frequently-used options, Edition and Eval, are pre-defined for convenience and may be overridden.
You can define an expiration date for the license on its product, and can choose to issue warnings prior to expirations, permit restricted functionality after expiration, provide a grace period after expiration, or disallow functionality after expiration according to your policy. For example, an evaluation key may have a 30 day expiration period and a 15 day grace period.
You can define a usage limit whose meaning is dependent on your product. For example, the usage limit can mean the number of times a file is written to disk for a development tool, or the number of times an application is run, for an end-user game program.
You can utilize the extensibility mechanism described below to, among other things, complement the above license modes or define arbitrary license parameters. For example, you can constrain the list or type of hosts that copies of your product can run on.
A license key can have any combination of the above parameters specified.
The following information is embedded into each generated license key and is available to you via the License Manager Console or the key generation API’s without being processed by the run time library at the customer site:
You can use the user-specified cookie to contain arbitrary information, as described below under User Extensibility Mechanisms.
With the Professional edition of EasyLicenser, two extensibility mechanisms are available for you to embed custom functionality:
You can embed arbitrary information into the custom cookie field. The custom cookie information for a generated key is available to you through the License Manager GUI and the license key generation API’s, but is unavailable at run time when license keys are checked. It is not processed during license key checking.
The mechanism is useful for embedding information that you wish to use later during a customer audit, and which you do not wish to make visible at an End Customer site. For example, if you re-issue a key to a customer who says they lost their key, you can note that fact in the custom cookie. That note will serve as an explanation if a subsequent audit turns up multiple copies of the same unique key.
You may augment the licensing policies that are supported by EasyLicenser, by defining your own rules and providing their associated handler code to the EasyLicenser run time at the time a key is being checked.
There are many uses of this extensibility mechanism. Some examples are:
(a) You may decide to impose a usage policy that is based on a time-of-day schedule. For example, in order to define different concurrent user limits during and after business hours, you may define an appropriate syntax and enter the following information into the custom key field:
conc=(9-17:100,17-00:20;00-9:0)
(b) You may be an OEM Reseller whose OEM may wish to restrict usage of their product to within the scope of your product, so that your end customers cannot decompose your product, extract the OEM’s embedded product and use that product for other purposes. You can meet the requirement by embedding a key provided by the OEM into the custom key field, possibly accompanied by other custom information, for example:
oemkey=H18KKJH28JNG373H5OJ5B
You correspondingly code a custom license key checker that conforms to an interface specification that is defined by the EasyLicenser run time. The custom key checker code is included with the ISV’s product so that the EasyLicenser run time can invoke it while it is checking the ISV’s license key.
The editions of EasyLicenser support the various license models, license types and parameters as follows:
EasyLicenser
Edition |
License Model
|
License Type
|
License
Parameters |
Standard |
|
|
Any combination of: Option enabling, Time limited, Metered. |
|
User |
Named User or Node-locked. |
|
Pro |
|
|
Any combination of: Option enabling, Time limited, Metered. User extensible to supplement / override with custom cookie and custom key. |
|
User |
Named User or Node-locked. User extensible to supplement with custom license type. |
|
|
Server |
Named-user, concurrent user, CPU Count or CPU Mhz. Always node locked. User extensible to supplement with custom license type. |
|
A key goes through multiple states in its life cycle as a result of events and actions. The specific state that a key is in determines the actions that can be performed on it. The specific transition of the key between two specific states influences its side effects on the license manager state and the external environment.
EasyLicenser is designed to generate keys that are globally unique among all keys generated using EasyLicenser. This helps you manage and audit your keys. If two different keys are identified to be in use and they are determined to have the same unique identification, this serves as an alert for an investigation, and the keys can be analyzed for an explanation.
There is a unique identifier associated with each key, whose value is based on a subset of the key’s contents. The unique identifier is based on a combination of your ISV user name, the license model (user or server) and license type (concurrent-user, named-user, etc.), the product name and your end customer's company name. The ISV user name is the unique name assigned to you by the easylicenser.com web site when you first purchase an EasyLicenser license or request an evaluation key. The license model and license type are internally-assigned numeric codes.
The lifecycle of a license key that is managed by the License Manager console is illustrated below.
A key can be in one of four states:
Nonexistent:
The key does not exist in the key database.
New:
The key is created but not yet available to anyone. In the process of creating the key, your license unit quota balance is depleted.
Published:
The key has been published so as to be available to your customer in a format that is amenable to further manual or automatic processing by the customer.
Exported:
The (published) key has been exported so as to be available to external systems in a format that is amenable to automatic processing, including importing into EasyLicenser.
In a typical usage scenario, a key is generated and comes into existence as a New key, which is then published, changing its state to Published. From time to time, you may wish to delete new or published keys. Deletion removes the keys from the key database, changing their state back to Nonexistent.
If you generate time limited evaluation keys, you may wish to occasionally perform garbage collection and reclaim expired keys, which are keys whose expiration date is beyond the current date. The process of reclaiming a new or published key deletes it from the key database and replenishes your license unit balance quota by an equivalent amount.
It is often desirable to export keys so as to make them available to external systems. Exporting a key creates an externally accessible copy of the key in an Exported state, which is suitable only for external processing or for importing into License Manager. The original key can remain in the key database in a Published state or be removed from it through a Reclaim or Delete action which reverts the original key to a Nonexistent state.
Correspondingly, it is occasionally required to import keys from a file of exported keys. This may be due to the need to consolidate keys from multiple EasyLicenser installations, or to retrieve archived key data.
There is exactly one instance of a given key identified by a unique identifier among the states Nonexistent, New and Published. However, an Exported key may exist corresponding to a key in either a Nonexistent or Published state.
The database serves as a combination of a contact management database and a license key repository. It has the following tables:
The table stores information on your products. Each entry represents one of your products, and is uniquely identified by a product name. Associated with the product name are allowed product options and their associated lists of allowed values, together with miscellaneous information such as creation and modification dates.
The table stores information on your customers. Each entry represents one of your customers, and is uniquely identified by a customer name. Associated with the customer name are contact information and notes, together with miscellaneous information such as creation and modification dates.
The table stores information on all new and published keys. Each entry represents a new or published key, and is uniquely identified by a unique key identifier, described above under Unique Key Identification. Associated with the key identifier are the license key itself, information on its creation and its published status.
The following diagram illustrates the relationship between the entities:
The relationship between the entities is loose; it is possible and reasonable to drop products and customers long after keys that refer to them have been erased.
Screens are provided to create and update a customer’s information. You can also export and import customers in a variety of formats, including an XML format that is amenable to automated processing, a human-readable text format and comma- and tab-separated formats that are amenable to being imported into relational database systems as well as popular contact managers. The fields of a customer record closely resemble those of popular contact managers.
In addition, you can search for customers based on customer name patterns and creation (“customer-since”) dates, as well as contents of customer notes. The list of matching customers can be operated on to delete or export selected customers, obtain the details of a selected customer, or obtain information on all the keys belonging to the customer.
Screens are provided to create and update a product’s information. You can also export and import products in a variety of formats including an XML format that is amenable to automated processing, a human-readable text format and comma- and tab-separated formats that are amenable to being imported into relational database systems.
You can also search for products based on product name patterns. The list of matching products can be operated on to delete or export selected products, obtain the details of a selected product, or obtain information on all the keys that reference the product.
When license keys are generated, they are made available in a license key work area, where immediate-term followup work can be performed. The follow-up work consists of publishing selected newly-generated keys or deleting selected keys. When work is completed, the keys can be cleared from the work area.
Screens are provided to search for and assemble license keys meeting a wide range of criteria. In addition to specifying patterns matching specific customers and products and key creation date ranges, it is possible to identify expired or expiring keys, and locate unpublished keys.
The list of matched keys can be operated on to delete, export or publish selected keys, obtain the details of a selected key, or obtain a list of customers corresponding to a set of selected keys.
This combination of screens
can be used to perform several useful functions including:
When you import customer, product or license key data, you can control what happens to malformed rows and duplicate data. Either condition can be made to abort the import process. Alternatively, offending rows can be ignored and recorded in a discard file, or duplicate rows can be applied to override existing records.
When you import license key data, only published and unexpired keys are imported. Correspondingly, only published keys are exported.
The run time library API is packaged in a Jar file ezlicrunVV.jar. It consists of the following classes and interfaces:
The purpose of the EzLicException* exception classes is to define the hierarchy of license key exceptions that can be thrown and caught, and to provide factory methods for throwing the exceptions.
The base exception class EzLicExceptionBase is the superclass of all the exception classes. It is never instantiated directly. It provides a factory method for throwing a specific exception subclass. The factory method is ordinarily never used by your application code; however, it is a useful facility when you define your own license key checking mechanisms that utilize EasyLicenser’s extensibility mechanisms.
The application code catches the appropriate exception subclass of interest, or EzLicExceptionBase if it doesn't care about the specific exception. The English text of the message can be obtained using a “getMessage” method. For internationalization, the caller can also obtain the message code and use it to drive the selection of a language specific message string. Alternatively, the application code can catch the specific message and manage its own selection of a language specific message.
The internal code in the EasyLicenser run time library throws the appropriate exception as part of checking a supplied license key. A custom license key handler provided by the ISV may also explicitly throw an exception if it wants to have a fine degree of control over the thrown exception, but is not required to do so.
When the application uses the "secure" license key checking API call, it can provide to the API call its own exception class that is inherited from EzLicExceptionBase for the purpose of throwing an exception upon success (as opposed to failure). This is useful for making it difficult for a third party to reverse-engineer and manipulate the application code to bypass license key checking.
Ihe EzLicCustomLicenseInterface interface defines the protocol for handling a custom license key. It is used only if you want to customize your license key management.
If you are interested in adding custom license management to the framework, you can implement this interface and provide its implementation for a “checkCustomKeyCode” method. The method is automatically invoked by the implementation of the license checker class below, if a custom key is found to be specified in the key and an instance of the implementation of this interface is passed into the API. The method automatically throws an “Invalid Custom Key” exception if the check fails. The implementation may also choose to explicitly throw other exceptions instead.
The EzLicenseInfo class manages the state of the information pertaining to a license key and provides a set of “check license key” methods to check a license key for validity and pending or expired quotas and dates.
The application code creates an instance of EzLicenseInfo and invokes the appropriate “check license key” method on it to check a given license key. If the check fails, an appropriate exception is raised. Otherwise, the state of the license info instance is set to the values extracted from the license key. The state includes the license model, license type, named-user user name, expiration date, metering quota, etc. information, which is accessible through accessor methods. If the secure API call is used, an exception can be arranged to be thrown upon success, as described above.
The application may optionally provide a custom key handler and an associated context that the “check license key” calls-back as part of the license key checks, if the application is interested in implementing custom license key management to complement or replace the standard license key management.
The application may optionally provide threshold quotas and days and grace quotas and periods for time limited and metered licenses. When the license expiration date or balance quota falls within the range, appropriate warning codes are returned but an exception is not raised.
The application may optionally use this EzLicenseCustomUtil utility class to manage the generation and decomposition of a custom key if it consists of multiple keyword-value pairs.
The EzLicCustomKeyHandler class provides methods for managing the contents of a custom key, when the key is organized into a set of name value pairs. After the license key is checked, a getCustomKeyValue static synchronized method can be called to retrieve the value corresponding to a keyword. You can use this mechanism to manage embedded OEM keys. Your OEM’s code can obtain an embedded key which it can then interpret as a license key and process accordingly. The embedded key is not required to be constructed with EasyLicenser. You can also reverse roles and serve as the OEM for OEM resellers who use EasyLicenser to manage their keys.
The C/C++ run time library is currently available on Windows and a number of Unix and Linux platforms enumerated in the setup guide. The run time library is packaged as a shared library or DLL (“ezLicenserlibVV.dll on Windows)”, where VV is the major revision number, for example “11” for 1.1.
The run time library API is defined in C, and is accessible to the C or C++ application developer by including the “ezLicenseInfo.h” header file.
The API surfaces the following types and API calls:
These are integer values returned by the API calls. Their definitions are available in "ezLicStatusCodes.h", which is implicitly included by "ezLicenseInfo.h". Negative status codes are equivalent to exception conditions in Java, and imply error conditions. A positive status code implies a bitmap of warning codes, which are also defined in "ezLicStatusCodes.h".
"ezLicCustomKeyHandler.h" defines the signature of the optional custom key handler that may be provided by the application developer for processing a custom key that is optionally embedded in the generated license key. The implementation details of the handler are up to the application developer. The custom key handler is not available to a VB programmer, who is required to manually process custom keys after performing a basic license key check.
These are available in "ezLicenseInfo.h". API calls are provided for the following purposes:
(a) To allocate and release a "license info" context block which is used for maintaining license parameters corresponding to a specific license key, for operating in a multithreaded environment.
(b) To get various license parameters such as the license model and expiration date from the license info context block.
(c) To check a license key and set its parameters in a supplied "license info" context block. There are four flavors of API calls available: simple API calls for basic single-user and server key checking, a functionally complete API call for checking any key with optional custom key handling, and a secure API call for checking a key in a manner designed to foil attempts to reverse engineer and bypass key checking by a hacker.
Constants defining various limits such as maximum key size are available in "ezLicLimits.h", which is implicitly included by "ezLicenseInfo.h".
A C/C++ application includes "ezLicenseInfo.h". In order to check a license key, it allocates a "license info" context block, and then invokes an appropriate API call to check the license key, supplying the license info context block as a parameter. The return code is examined for error and warning conditions. If there is no error condition, the "getter" API calls are invoked against the license information context block to obtain specific license parameters if required by the application, for example to obtain the custom cookie and licensed options.
All time information is expressed as a long integer that corresponds to
the POSIX time_t specification (number of seconds since
The C/C++ run time library can be used in a multithreaded environment. However, the API calls are not all guaranteed to be threadsafe on all platforms. It is the responsibility of the application developer to serialize license key checks at the license-key-check API call level of granularity. The remaining API calls are threadsafe.
On Windows, the DLL interface module "ezLicenseInfoVV.bas" that is included with the product packaging under the "vb6\src" directory is included in the project definition of each Visual Basic application that is to be license protected with EasyLicenser. It is designed to be used in conjunction with the EasyLicenser C/C++ Windows run time library, whose C API calls are mapped to VB6 API calls which are used in a manner similar to C/C++ programs for checking license keys at run time.
There is one important difference in the available functionality: in addition to the threadsafety constraints imposed by the C/C++ run time library, it is also not possible for a Visual Basic 6 program to provide a custom key handler. However, this does not mean that custom keys cannot be processed in Visual Basic 6 programs; rather, the VB6 program is responsible for retrieving the custom key from the license information context block after the latter has been set up by checking the license key, and then checking the custom key according to its requirements. Therefore, it is important to note that custom key functionality is available with Visual Basic applications and requires a little more coding on the part of the application developer.
The key generation API is packaged in ezlicgenVV.jar. It uses the Java run time API ezlicrunVV.jar. The API manages all aspects of generating ISV keys.
When generating ISV keys, the vendor license keys are appropriately checked and the quota and state information are automatically managed in the EasyLicenser configuration files. License key generation is enabled with the eCommerce Option of EasyLicenser.
The API consists of the following classes:
The EasyLicenseFullInfo class extends the public license info class available in the run time library to include complete information that is not available to the run time environment at the end customer site.
The class defines attributes and their associated accessors and mutators that pertain to license key generation and are not visible to the run time when checking license keys. Such attributes include the ISV’s user identity, the key creation date, an optional ISV-specified cookie and the company name of the end customer.
Methods are provided to:
(a)Generate an ISV key. A key is generated by instantiating the class, filling its attributes through its mutators, and invoking the “generate key” method, which returns the generated key.
(b) Fully parse a key over and above the parsing performed by the Java run time license key checker method. If a key needs to be audited for details, the “parse license key” is used against a created instance of the class to decompose the key into its constituents that are saved in the class and available through its accessor. Only the creator of a key is allowed to parse it. The creator is the user account that was used at the time of generating the key.
An instance of the EzLicenseVendorLuPolicy class can be retrieved from the EasyLicenser Configuration class, where it is embedded. It provides the ISV key generation code with the information necessary to determine how the license unit quota consumption is impacted by the type of ISV key that is generated.
The policy elements include:
The EzLicenseConfig class provides information that is specific to the state of a specific installation of EasyLicenser. This includes information on installation dates, registration status, installation options, and balance usage quota. In addition to the attribute accessors, a method is provided to load the configuration state of the current installation of EasyLicenser from the file system.
For information on how to perform a particular administrative, key management or information management task using the License Manager console, see the License Manager User Guide.
For information and examples on how to use the Java run time library API’s to license-protect your Java application, see the Java ISV Application Development Guide. For specific information on using the run time library API’s, see the Java Run Time Library API Reference Java documentation.
The C/C++ ISV Application Development Guide describes how to license-protect your C/C++ application with the EasyLicenser C/C++ Run Time Library on all supported platforms. The Visual Basic 6 Application Development Guide describes how to use EasyLicenser to license-protect your Visual Basic 6 application program on Windows with the EasyLicenser C/C++ Run Time Library and its associated Visual Basic DLL Interface module.
If you are integrating automatic key generation into your Java servlet or JSP based eCommerce web site, see the Java eCommerce Application Development Guide for information and examples. Specific information on using the key generation API’s is available in the E-Commerce License Key Generation API Reference Java documentation.