Click to go to home page

Concepts


Preface

How Product Licensing Works With EasyLicenser

Preliminary Steps

Key Generation And Management

EasyLicenser Architecture

Licensing Model

Single-User License Model

Orion-User License Model

Server License Model

License Parameters

License Cookies

User Extensibility Mechanisms

Access Controlled Keys

License Key Lifecycle Management

Unique Key Identification

License Key Lifecycle

License Manager Database

Product

Customer

Key

License Information Management

A Tour Of The Java Run Time Library API

Exception Class Hierarchy

"Custom license parameter" Interface

License Info Class

Extended API Class

Custom Key Utility Class

Custom Key Management Class

A Tour Of The C/C++ Run Time Library API

Status Codes

Custom Key Hander Interface

License Key Management And Parameter Interface

Extended License Key Management Interface

Limits

A Tour Of The License Key Generation Java API

Full License Info Class

Vendor-specific License Unit Policy Class

Installation-specific EasyLicenser Configuration Class

Next Steps


Preface

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.

How Product Licensing Works With EasyLicenser

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.

A single-user License Manager GUI desktop application is provided for interactive creation and management of license keys, products and customers. A license key generation Java library is also available for programmatic generation of keys when you are licensed for the eCommerce option.

EasyLicenser adopts the integration approach to license management: when developing your application, you code against our C/C++ or Java run time libraries for the purpose of checking license keys, and when you deploy your application, you include the run time libraries with your distribution.

Preliminary Steps

Before you can start license protecting your products with EasyLicenser, you need to take the following preliminary steps:

      1. The first step is to perform a one-time download of the EasyLicenser product, which you have already done.
      2. Next, you perform the development activities involved in interfacing your product to EasyLicenser’s run time library.  To do this, you use the appropriate language-specific run time library API documentation that is included with the product.
      3. Finally, your product packaging should include or embed the appropriate EasyLicenser run time library.

Key Generation And Management

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 will need to maintain your own database of keys, customers and products.  If you use the License manager console, EasyLicenser’s embedded single-user 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.

      1. After you compose your parameters for a batch of keys, you activate key generation, and then publish the keys to a file in a format of your choice.  The contents of the file may be in XML format if desired, which permits automated processing for emailing customers or embedding in product configuration files.

        If you are an Original Equipment Manufacturer (OEM) and you wish to license-protect your product so that it is used only in the context of your OEM reseller’s products, you may issue keys to the OEM reseller.

        Conversely, if you are an OEM reseller and your product includes one or more OEM products, your OEMs can use EasyLicenser to provide you with keys that you can embed into your license keys.

      2. You can distribute the keys for your product in one of several ways according to your product and your preferences.

        For example, you can email keys to your customer, who may have downloaded your product or installed your product from a CD in trial mode.  Alternatively, you can embed the key in a property file and make the combination of the property file and your product binary available for download to a paying customer.

        For products that are distributed on CD-ROM, your assembly line can stamp a serial number on each CD case, where the serial numbers are auto-generated from the License Manager and are used as the basis for generation of keys that are embedded into the product CD.  Your product can ask the user for the serial number during installation or first-time execution.  The serial number in this case corresponds to the user or host name input to license key generation.

        You can also automate key distribution using a custom-built web site, or you can use Agilis' Orion network license server as an automatic key distribution mechanism over the Internet with minimal coding.

      3. You may have generated time limited evaluation keys for your customers.  Periodically, you can use the License Manager to identify customers whose evaluation keys are expiring, and then contact the customers to convert them into paying customers.

        When you convert a customer, you generate a production license key that you can ship to your customer so that they can simply plug in the production key into their copies of your product instead of being required to install a production copy of your product.

      4. At the time of renewal of your EasyLicenser subscription license agreement with Agilis, you will receive a renewal EasyLicenser key from us for extending your expiration date.  Upon receipt, you will recharge your EasyLicenser license with the new key using the License Manager console.  You can do this in the middle of your key generation operations without disruption.

      5. Occasionally, should circumstances warrant it, you may wish to conduct an audit of your customer’s keys to verify conformance to your product license terms.  You can do this by obtaining your customers’ keys and analyzing their details with the License Manager.

      6. Occasionally, you may wish to export your database to an external system, or import data from an export file that was previously generated, possibly from another EasyLicenser installation.  You may wish to perform this operation for many reasons, including data consolidation, selective backups, for report processing in a relational database, and for interchanging data with contact managers or other database systems.  You can utilize the License Manager console’s import / export facilities to perform this database maintenance operation.

      7. To protect your configuration and databases from media failures, you will likely perform frequent backups using the License Manager’s backup facility.  In the event of media failure, the corresponding restore facility can be used to restore the state of your installation to a specified backup.

EasyLicenser Architecture

EasyLicenser’s key components and their relationship are illustrated below:

The License Manager console is a single-user desktop application that provides the graphical user interface to simplify license key management.  It is also required for management of an EasyLicenser License Manager installation, unless you are using the eCommerce option and its API for managing your installation's EasyLicenser licenses.

The License Key Database Manager provides database management facilities for products, customers and license keys.  It is an embedded single-user database that 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 for a specific operating system account.

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 C/C++ applications.  The appropriate language and platform specific run time library, together with any depended-on 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.

Licensing Model

The two license models that are supported by EasyLicenser are User and Server. If you are using the evaluation copy of EasyLicenser or you are an Orion customer, your EasyLicenser installation is network licensing enabled: an Orion subcategory of user licensing supports generation of Orion user licenses for use with the Orion network license server for floating licensing and product activation.

The User license model is intended for development tools and end-user products that have the following characteristics:

    1. Human beings interact with the product directly.
    2. A given instance of the program supports only one user (but it may communicate with servers or with other single-user programs that support other users (for example multiuser games over the Internet)).
    3. The license is to be node-locked on a per-user basis.

The Server license model is intended for multi-user server products that have the following characteristics:

    1. They do not directly interact with human beings.
    2. A given instance of the program supports multiple users through client application programs.
    3. The server is multithreaded and / or otherwise has knowledge of the number of concurrent users or devices whose limit is to be controlled by the licensing system. Note that this is different from what is traditionally referred to as floating licensing that requires a floating license server.

An Orion license is intended for desktop, server or other products that have any of the following characteristics and requirements:

    1. A high level of automation of the node-locked licensing process is desired, and / or a high degree of flexibility in license relocation and revocation are desired, for which Orion's product activation capabilities are needed.
    2. Concurrent-user licensing is required for desktop applications and / or server applications that are inherently unable to track concurrent user / device counts, for example clustered servers and servers having a process-per-user architecture.
    3. The licensing system, whether for node locking or floating licensing, is desired to be hosted and accessed over the Internet or a wide area network.

Orion is a separately licensed product, and EasyLicenser's relationship to Orion is limited to generating Orion server licenses. The application itself is integrated with Orion's runtime client libraries instead of with the EasyLicenser runtime libraries.

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.

Single-User License Model

The supported license types are:

Named user

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. If the latter, the operating system username and hostname are specified in the format user@hostname. The hostname, if specified, is either unqualified or fully qualified as a function of the operating system platform. The ezlmgetmcinfo command line utility is provided to help you accurately obtain this information in the correct format from your customers.

When an operating system check is enforced, the user name is specified as null at application run time - the EasyLicenser runtime library automatically introspects the username and / or hostname from the runtime environment and matches it against the license key content.

Node locked

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 system 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, your application specifies null as the hostname parameter to the license key checking API's, and the host name in the key is automatically 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.

Orion-User License Model

The supported license types are:

Orion server (Network Licensing Enabled Edition only)

A number of instances of users of the ISV’s product up to a specified limit can simultaneously use and / or be registered to use your product in conjunction with a specified instance of the Orion network license server.

From the perspective of license key generation, there is no constraint on the location or identity of the users, but there may be a number of constraints imposed on the machine on which the Orion license server runs.

Although EasyLicenser is used to generate Orion license keys, an application that is enabled for floating licenses does not use the EasyLicenser run time libraries for checking licenses; Orion's client libraries are used for this purpose. The client libraries, in conjunction with the Orion server, provide floating licensing, automatic node locking and product activation functionality.

For further details, refer to the Orion product documentation.

Server License Model

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:

Named role

A specified maximum number of "role" accounts may be defined for use on the server.  Typically, many concurrent users may be associated with each named role.  The concept is applicable to a limited class of servers such as database management systems and packaged application systems that support the notion of roles.

The parameter is the upper limit on the number of named roles.

Concurrent user

A specified maximum number of concurrent users can access the single instantiation of the server.  A “user”, which can also be 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.

CPU count

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).

CPU MHZ

There is an upper limit on the total MHZ of CPU power on the machine on which the server is running.

Server License Type Parameters

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 roles, concurrent users, CPUs or CPU MHZ.

It is the responsibility of the application to obtain the current usage value from its environment when performing a server license key check.

License Parameters

EasyLicenser supports the following license parameters for all license models and types:

Option enabling

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 or removed.

The specific meaning of option values and their checks are the responsibility of your application. From the perspective of EasyLicenser, options are passed through to your application following an otherwise-successful license key check. The exception is a set of built-in system options for Orion license keys used with the Orion server; these are internally processed by Orion and not surfaced to your (Orion-enabled) application.

Time limited

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.

Time-limited license checking is managed internally in the EasyLicenser run time library. The responsibility of the application is limited to specifying desired a warning threshold and grace period.

Metered

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 also use EasyLicenser's secure API's to automatically manage metered usage consumption for you, in which case your application's responsibility is limited to managing the persistent storage of encrypted information returned by the run time library using a mechanism of your choice.

A license key can have any combination of the above parameters specified.

License Cookies

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

User Extensibility Mechanisms

Two extensibility mechanisms are available for you to embed custom functionality:

Custom cookie

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. The custom cookie is ordinarily not made available to an end user and is not processed by the EasyLicenser runtime library, although it is visible to the application.

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.

Custom 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

(c)   You may wish to distribute a single key for a product suite, such that each product in the suite is separately licensed with its unique parameters such as expiration date and usage limits. You can meet the requirement by generating a separate key for each product in your suite and then creating a master key into which you embed the individual product keys, and identify and process them at run time with a custom key handler that recursively processes the embedded keys.

(d)   You may wish to perform platform-specific enforcement of hardware parameters of your choice, for example boot disk drive signatures, Ethernet MAC addresses or PROM identifiers. You can meet the requirement by providing your customer machine's fingerprint as the custom key value, and implementing a custom key handler that introspects its runtime environment to recompute the machine fingerprint and compare it with the value in the custom key.

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.

Access Controlled Keys

EasyLicenser enables you to generate access-controlled keys: keys that require authentication at the time of a license key check based on a password that is known only to the application. At the time of defining a product, a secret password is specified. The product details screen feeds back a public key corresponding to the password. The password is embedded into each key that is generated based on the product. When your application invokes the license key checking API, it provides the password's public key and product name. In order for the license check to succeed, the product name as well as the secret password corresponding to the public key must match the corresponding entries in the key.

License Key Lifecycle Management

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.

Unique Key Identification

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, and the key creation timestamp in milliseconds since the Unix epoch.  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.

License Key Lifecycle

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.

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 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.

License Manager Database

The database serves as a combination of a contact management database and a license key repository.  It has the following tables:

Product

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. A product may also have a secret password associated with it in order to generate access-controlled keys.

Customer

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.

Key

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.

License Information Management

Customer Management

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.

Product Management

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.

License Key Management

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:

Data Import / Export

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.

A Tour Of The Java Run Time Library API

The run time library API is packaged in a Jar file ezlicrunVV.jar.  It consists of the following classes and interfaces:

Exception Class Hierarchy

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 implementation of 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 check 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.

"Custom license parameter" Interface

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.

License Info Class

The EzLicenseInfo class manages the state of the information pertaining to a license key and provides a number 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 license key checking API calls include secure checking calls that accept an encrypted key cookie and return an updated key cookie. The key cookie is a run time concept and is not to be confused with the custom key and custom cookie, which do not change in value at run time. The key cookie contains license state information such as system timestamp, current use count and arbitrary application state. API calls are provided to retrieve a key cookie's contents; however, it is not modifiable by an application.

All flavors of the license key checking API calls are available with signatures that accept a product name and application password public key for checking an access-controlled key. If the key is access-controlled, the product name and application password must match what is specified in the key in order for the license check to succeed.

System clock checking is by default enabled for all keys. This is accomplished with a hidden file, which is by default located at the user home directory. You can use enhanced versions of the license key checking API's to specify an explicit directory for the hidden file, and / or suppress system clock checks for keys that are detected to be perpetual.

Extended API Class

The EzLicenseExtendedAPI class provides a higher-level licensing functionality that also reduces the level of development effort involved in integrating an application. The extended functionality includes:

  1. Optional deferred node locking, which enables you to issue a license to an end user without collecting node locking information from them, with a controllable shelf life time window within which the end user has to install the license.
  2. Optional deferred time-limited licensing, which simplifies the logistics of managing large numbers of anonymous time-limited trial licensing, by enabling you to package a single relative-time-limited license key with your downloadable.
  3. Automatic license quota management, for metered licensing. This eliminates the need for you to write code to manage updates to metered quota consumption.

The extended API provides high level API calls for:

  1. Activation - use during product installation or activation upon first use.
  2. Steady state license check - use wherever license checks are to be performed during normal license operations.
  3. Deactivation - use during product uninstallation or explicit deactivation.

The API extends the EzLicenseInfo class.

To perform activation, the application code invokes an activateLicense factory method, which if successful returns an instance of the EzLicenseExtendedAPI class, which can then be introspected in the same manner as the underlying EzLicenseInfo class, as well as to obtain a dynamic "key cookie" whose value mutates during subsequent license checks (unlike a license key).

To perform a license check in the steady state (and possibly update metered usage consumption etc.), the application code invokes a checkLicense static method, providing the last-generated state of the key cookie. If the check is successful, an instance of the EzLicenseExtendedAPI class is returned as before, which can then be introspected as before, in particular in order to obtain an updated dynamic key cookie.

To deactivate the license, the application code invokes a deactivateLicense static method, providing the last-generated state of the key cookie.

Custom Key Utility Class

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.

Custom Key Management Class

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.

A Tour Of The C/C++ Run Time Library API

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 20 for 2.0.

The run time library API is defined in C, and is accessible to the C or C++ application developer by including the ezLicenseInfo.h or (if using the extended API described below) the ezLicenseExtAPI.h header file.

The APIs surface the following types and API calls:

Status Codes

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.

Custom Key Hander Interface

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.

License Key Management And Parameter Interface

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, as well as to securely manage license state such as current quota consumption.

All license key check API calls are available with signatures that accept an optional application password and product name for checking access-controlled keys (those generated for products having an application password defined for them).

(d)    System clock checking is by default enabled for all keys. This is accomplished with a hidden file, which is by default located at the current working directory. You can use enhanced versions of the license key checking API's to specify an explicit directory for the hidden file, and / or suppress system clock checks for keys that are detected to be perpetual.

Extended License Key Management Interface

These are available in ezLicenseExtAPI.h. The extended API provides a higher-level licensing functionality that also reduces the level of development effort involved in integrating an application. The extended functionality includes:

  1. Optional deferred node locking, which enables you to issue a license to an end user without collecting node locking information from them, with a controllable shelf life time window within which the end user has to install the license.
  2. Optional deferred time-limited licensing, which simplifies the logistics of managing large numbers of anonymous time-limited trial licensing, by enabling you to package a single relative-time-limited license key with your downloadable.
  3. Automatic license quota management, for metered licensing. This eliminates the need for you to write code to manage updates to metered quota consumption.

The extended API provides high level API calls for:

  1. Activation - use during product installation or activation upon first use.
  2. Steady state license check - use wherever license checks are to be performed during normal license operations.
  3. Deactivation - use during product uninstallation or explicit deactivation.

The API defines an extended extended license info context block which contains an instance of the license info context block.

To perform activation, the application code invokes an activateExtAPILicense factory API call, which if successful returns an instance of the extended license info context block, which can then be introspected in the same manner as the underlying license context block, as well as to obtain a dynamic "key cookie" whose value mutates during subsequent license checks (unlike a license key).

To perform a license check in the steady state (and possibly update metered usage consumption etc.), the application code invokes a checkExtAPILicense API call, providing the last-generated state of the key cookie. If the check is successful, an instance of the extended license info context block is returned as before, which can then be introspected as before, in particular in order to obtain an updated dynamic key cookie.

To deactivate the license, the application code invokes a deactivateExtAPILicense API call, providing the last-generated state of the key cookie.

Limits

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 that uses the standard API 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 midnight January 1, 1970 Coordinated Universal Time (the new name for Greenwich Mean Time))

The C/C++ run time library can be used in a multithreaded environment.  All the API calls are threadsafe on all supported platforms.

A Tour Of The License Key Generation Java API

The key generation API is packaged in ezlicgenVV.jar.  It uses the Java run time library ezlicrunVV.jar.  The API manages all aspects of generating ISV keys and recharging the EasyLicenser installation with new EasyLicenser keys obtained from Agilis.

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:

Full License Info Class

The EasyLicenseFullInfo class extends the public EzLicenseInfo 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 generateKey method, which returns the generated key. If it is desired to generate an access-controlled key, the product's password is supplied to the key generation method. Correspondingly, at run time in the customer environment, a successful license key check requires a match of both the application password and product name.

Simpler and more direct methods are also provided to generate a user, server or Orion license with one line of code. These are, respectively, generateSingleUserKey, generateServerKey and generateFloatingKey.

Finally, in order to generate an incremental replacement key that is chained to another key (so as to restrict its use to serve as an upgrade key only), the generateChainedKey API call is used. Note that the built-in key chaining functionality is applicable to Orion license server key generation only.

(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. If the key is access-controlled, the corresponding product password's public key and product name are also required to be specified and match in order to perform a successful parse.

(c) Recharge the current EasyLicenser installation with a compatible EasyLicenser key provided by Agilis for the purpose of programmatically adding to your license unit quota and / or extending your license expiration date at an eCommerce installation.

Your web site can be programmed to receive as input an EasyLicenser key obtained from Agilis and invoke the recharge EasyLicenser key API call, providing your user name. If the user name matches what's in the key and in the current configuration and the keys are compatible (they have the same edition and options and there is no conflict in their parameters such as expiration dates), the key is accepted, the current configuration's balance license unit quota is incremented or replaced by the quote contained in the input key, and the license expiration date is extended to that of the input key.

(c) Deactivate the current EasyLicenser installation and return a confirmation token that you can provide Agilis as proof that you indeed removed your installation, if required for the purposes of returning or exchanging your license.

Vendor-specific License Unit Policy Class

The EzLicenseVendorLuPolicy class is obsolete, and exists for historical reasons related to backward compatibility. It is of no concern to Agilis' customers.

Installation-specific EasyLicenser Configuration Class

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. Other visible methods that set configuration values and save the configuration state are available for Agilis-internal use; these are password-protected and are not intended for use by Agilis' customers.

Next Steps

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.  

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.


Copyright © 2002+ Agilis Software LLC, Santa Clara, CA, USA. All rights reserved.