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 Professional 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. 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.
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.
The supported license types
are:
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.
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 "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.
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.
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 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.
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.
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.
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.
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.
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 (Professional Edition Only)
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. 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.
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.
All editions of EasyLicenser
enable 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.
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, Node-locked or Orion server. User extensible to supplement with
custom license type.
|
|
|
|
Server
|
Named-role, concurrent user, CPU Count or CPU Mhz. Always node
locked. User extensible to supplement with custom license type.
|
|
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.
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:
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.
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:
- Identifying customers
whose evaluation keys are about to expire.
- Identifying keys that
haven’t yet been published.
- Identifying the biggest
and most loyal customers.
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 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.
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 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.
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:
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.
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.
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:
Activation - use during product installation or activation
upon first use.
Steady state license check - use wherever license checks
are to be performed during normal license operations.
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.
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 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:
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, 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.
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:
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.
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.
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:
Activation - use during product installation or activation
upon first use.
Steady state license check - use wherever license checks
are to be performed during normal license operations.
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.
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:
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
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 and the current configuration's balance license unit quota is incremented
by the quote contained in 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 license units.
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:
