License Manager Usability Enhancements
Command Line License Management Utilities
Runtime Library API Enhancements
License Key Generation API Enhancements
Updated Platform / Language Support
Improvements To License Manager UI Manageability And Deployability
Upgrading From Previous EasyLicenser Versions
Upgrading eCommerce Key Generation System
Upgrading Applications For The New Runtime Library
Compatibility Of Product Definitions
Runtime Library API Compatibility
Packaging For C/C++ Platform Support
The purpose of this document
is to describe the new features in EasyLicenser 2.5, their benefits,
how to use them, and where to look for detailed information. Note that although
it is possible to directly upgrade from EasyLicenser 1.1 to EasyLicenser 2.5, this
document is focused on features that are new in EasyLicenser 2.5. EasyLicenser 1.1
users should first review
What Was New In EasyLicenser 2.0 for information
on new features that were introduced in EasyLicenser 2.0.
Target audience: existing EasyLicenser 2.0 administrators and developers upgrading to 2.5.
Note that there is no visible impact on end users.
The key themes behind EasyLicenser 2.5 are:
Usability enhancements to the License Manager console, in particular for the management of license keys.
Introduction of command line utilities for license management functions, in order to enable automation of license key generation and EasyLicenser license management from shell scripts.
Enhancements to runtime licensing functionality, in particular deferred-mode node locking and relative time limited licensing.
Adjustments to platform and language support based on current platform needs.
Improvements to manageability and deployability through removal of restrictions.
In addition to bug fixes and numerous minor improvements such as addition of edit / delete confirmation dialog boxes, addition of file chooser dialog boxes, and other similar functionality tweaks, the most significant improvements to the License Manager UI console are:
License key work area functionality
The scope of the license key work area on the main screen is extended to provide full
license management functionality for all keys belonging to the
currently-selected customer and product, not just the newly-generated
keys. The full functionality includes the ability to export selected
license key(s) and view the details of a selected key (and then optionally
clone or chain the key). Also, when new license keys are auto-generated and auto-published,
previously-selected license keys in the work area are not published together with
the new keys.
License key cloning and chaining
It is possible to quickly and conveniently generate a key that is similar an existing key but
with a few changes to the key parameter values. This is useful for generating
replacement keys for existing customers, and for generating similarly-composed keys
for multiple different customers where the keys differ only by the
customer name and node locking information, and possibly a few option value
selections.
When the key is for the Orion license server, the key can be specified to be
chained so that it can only be applied in the right order relative to
the preceding key installed on the Orion server, thereby providing an added
level of security.
Key cloning and chaining functionality is accessed from the Key Details
screen: you identify the key you want to clone or chain from, either in the
license key work area or the license key management screen, then select the
key and click the Details... button. In the Key Details
screen, you click on a new Enable Cloning checkbox and (if
chaining) the Enable Chaining checkbox. Depending on the checkboxes
clicked, some of the key detail fields become editable. After making the
incremental modifications to the key parameters, you click the
Make Cloned Key or Make Chained Key button to generate
and optionally publish the cloned / chained key.
Important Note: License key cloning and chaining functionality is enabled only provided
the EasyLicenser key provided by Agilis is at version 2.5 or higher. If you
upgrade an existing EasyLicenser 2.0 installation, this functionality
is disabled.
Product definition: network licensing options update
The network licensing options that are head-started when the Add Network License Options button is clicked
in the Create Product / Product Details screen now include all network licensing options accepted by Orion
server version through 2.0.10. Previously, the missing new options since the Orion 1.0 release needed to be entered manually if required.
Sorted lists
All lists are alphabetically sorted on their natural primary keys. For license
keys, the sort order is based on customer, product and creation timestamp.
Command line utilities are provided to enable license management and key
generation to be performed from command line scripts. The utilities enable
you to automate license key management and license configuration management
functions from shell scripts and also to trigger the functions from CGI
scripts for web sites that don't use Java technologies and therefore cannot
conveniently utilize the Java-based license key management back office API's.
The command line utilities are implemented as executable jar files that are located
under the ezlic2.5 directory, accompanied by shell script wrappers.
The utilities are:
Command-line license key cloning / chaining utility: ezlicmgrclonekey.sh, ezlicmgrclonekey.bat, ezlicmgrclonekey25.jar
Generates an edited clone of an existing license key, or (for Orion server keys only) a replacement key that is chained to an existing key.
Command-line EasyLicenser configuration deactivation utility: ezlicmgrdeact.sh, ezlicmgrdeact.bat, ezlicmgrdeact25.jar
Deactivates the EasyLicenser configuration and produces a return receipt file as proof of deactivation.
Command-line EasyLicenser configuration dump utility: ezlicmgrdmp.sh, ezlicmgrdmp.bat, ezlicmgrdmp25.jar
Dumps information on the EasyLicenser configuration such as balance license units,
expiration date, etc.
Command-line license key generation utility: ezlicmgrgenkey.sh, ezlicmgrgenkey.bat, ezlicmgrgenkey25.jar
Generates a license key. Only normal license keys can be generated. In order to generate cloned and / or
chained keys, use the ezlicmgrclonekey utility described above.
Command-line import utility: ezlicmgrimp.sh, ezlicmgrimp.bat, ezlicmgrimp25.jar
Imports product / customer / license key export files previously created with
the License Manager UI in an import-capable format (XML, CSV or TAB).
Command-line key information utility: ezlicmgrkeyinfo.sh, ezlicmgrkeyinfo.bat, ezlicmgrkeyinfo25.jar
Displays information about a license key.
Command-line machine information retrieval utility: ezlicmgrmcinfo.sh, ezlicmgrmcinfo.bat, ezlicmgrmcinfo25.jar
Retrieves machine information for OS-level node locking. The machine information can be selected to be either
the OS hostname or the OS hostname qualified by the OS username.
Command-line EasyLicenser configuration recharge utility: ezlicmgrrecharge.sh, ezlicmgrrecharge.bat, ezlicmgrrecharge25.jar
Recharges the EasyLicenser installation with a new EasyLicenser key provided by Agilis.
To get help on any specific command line utility, run the utility without arguments. To directly invoke the executable jar on Windows, either double-click the executable jar from Windows Explorer, or select the executable jar file for the Run command window from the Start window. To directly invoke the executable jar from a command window on any platform (including Windows), open a command window, position to under the ezlic2.5 directory, and type java -jar <jar-file> <arguments>.
A new Extended API is added to the runtime library. In addition to providing higher-level abstractions that simplify application integration without sacrificing functionality, the extended API provides new capabilities including:
Relative time-limited licensing
In conjunction with an enabler key provided by Agilis, the API can be used to realize
completely autonomous relative time-limited functionality that allows you to
distribute your product together with a single time-limited license key such
that each user's activation triggers his respective time-limited license independent
of other users, without any interaction between you and the evaluator. The API also
provides basic safeguards against serial evaluation on the same end user machine.
The API is ideal for managing trial licensing for anonymous downloads from download sites and for
CD-ROM based trial software distribution through reseller channels.
Deferred node-locked licensing
In conjunction with an enabler key provided by Agilis, the API can be used to realize
node-locked licensing functionality that allows you to
generate a license key in response to a customer order without requiring the
end user to provide you with node locking information. At the time of generating
the license key, you can specify a shelf life within which period your end customer
needs to activate their license, thereby protecting your license key from unauthorized
use over time. The license automatically locks itself to the machine on which it is
installed at the time of license activation, which typically occurs at the time of
application installation or upon first use.
The API is ideal for simplifying the order fulfillment process,
especially when order fulfillment is done for software sales that
are managed by reseller channels and you need to control the license
key generation process.
Automatic metered licensing and other license state management
An automatic license metering mechanism is built into the extended API, which
manages all aspects of securely tracking use counts for metered licensing
purposes. The API also provides an extensibility mechanism that enables
you to securely track and manage arbitrary application state. For example, the
extensibility mechanism
can be used to track cumulative application execution elapsed times,
specific user input data of interest, and provide additional
safeguards against rollback of license state for example by recording the
time obtained from a remote time server for future cross-checking against
the system clock and the hidden file's record of the update time.
The API is ideal for implementing licensing policies involving
tracking and / or controlling state changes over time,
for example metered licensing usage consumption.
The signatures and semantics of existing Core API calls are preserved for backward compatibility. In addition, the following enhancements are provided:
Strict password checking
The license checking API calls include new signatures for the purpose
of accepting a strict password check parameter that enforces a
matching application password in the license key to correspond to the application
password public key that is provided by the application. The default value for existing
core API calls is false for backward compatibility; however, it is strongly recommended
that the new signatures be used, with a true value for the parameter, and correspondingly
that you promptly replace any keys that you generated based on a product definition that did not
have an application password specified. For the extended API (which in turn uses
the core API's), password-checking is implicitly strict.
Hidden file directory parameter semantics extension to filenames
The hidden file directory parameter can also be used to specify the name of the hidden file. If the
hidden file directory parameter value is detected to end in a .ehf extension value, this is
interpreted to mean a full path specification for a file name rather than a directory
specification. Otherwise, the prior semantics are preserved, and the default hidden
file name .ezl20ck (C/C++) / .ezlm20jk (Java) is appended to the specified or default hidden
file directory to determine the absolute path of the hidden file.
The enhancement enables the application to exercise a higher degree of control over the
placement of hidden files. For example, multiple hidden files may be managed in the same
directory, each for a separate license, in a complex licensing scenario.
Runtime library version introspection
API calls are provided that enable the application to introspect the major and minor version numbers
of the runtime library at run time.
The enhancement enables the application to dynamically determine what licensing API capabilities
to use as a function of the runtime library version, as well as to detect incorrect installation
configurations.
Timestamp checking control
The semantics of the alwaysCheckTimestamp control parameter have been refined to completely
turn off system clock integrity checking if specified to be true. Previously, the parameter worked
only for perpetual licenses - a time limited license key would cause the parameter value to be ignored
and system clock checking to be unconditionally enforced.
A set of simplified stateless key generation API calls are added so as to enable
the back office system to generate a license key with a single API call. A separate
API call is provided for each type of key: single-user desktop license (generateSingleUserKey),
EasyLicenser-based server license (generateServerKey), and Orion server license (generateFloatingKey).
For Orion license server key generation, an additional generateChainedKey API call is provided for the purpose of generating
a chained key based on an existing key.
The signature and semantics of existing key generation API calls are preserved for backward
compatibility. Further, it is no longer necessary for the application to explicitly set
the license mode bitmap bits when defining time-limited or metered licenses or
licenses having the custom key and / or cookie defined by the application - these
operations are implicitly performed by the corresponding setter API calls.
Platform and language support has been fine-tuned in response to customer demand as follows:
C/C++ runtime library platforms:
The C/C++ runtime library is available
for 32-bit Windows (all versions), 32-bit Solaris 10 on SPARC, 32-bit Solaris 10 on Intel, and
32-bit Linux on Intel (all versions based on Linux 2.4+ kernel having the
runtime libraries corresponding to gcc 3.3 and above).
HPUX and AIX support are discontinued, as is support for old versions of Linux
and Solaris.
The version-based naming convention for the runtime library shared library files is discontinued,
with the name frozen at the last version. Instead, API calls are provided that enable
the application to introspect the major and minor versions of the library at runtime
at an end customer deployment.
The runtime library for all supported platforms is included with the standard
EasyLicenser product distributions, in addition to being available as a separate download.
Support for 64-bit versions of the above platforms, as well as additional platforms, is planned.
Runtime library extensions for Visual Basic and .NET:
These are no longer supported in their present form.
A native managed .NET runtime library replacement is planned, for more proper support for
all .NET languages including C# and Visual Basic .NET. In the interim, the
current post-2.0 unmanaged ActiveX DLL, available as a separate download, may be used for .NET applications.
Since there is no backward compatibility implication with respect to license keys, prior versions of the EasyLicenser runtime library for platforms that are now not supported will continue to work with equivalently-composed new keys generated with EasyLicenser 2.5. What is missing for the desupported platforms and languages is the new runtime library's functionality and bug fixes.
Several restrictions which were put in place due to the prior license unit based online purchase model and which resulted in undue restrictions have been removed from the License Manager UI:
Multiple-installation restriction:
It is possible to maintain multiple active License Manager installations
under the same operating system user account. However, as before, once an
installation is recharged with a production license key, the installation cannot
be relocated.
Restriction on import of unpublished and expired keys:
It is possible to import keys that are not in a "published" state, as well as keys
that have expired.
Restriction on data loss during deactivation:
When an EasyLicenser configuration is deactivated, data and export files are no longer
deleted.
The restrictions contine to apply if the EasyLicenser installation is based on old EasyLicenser keys, for example if you upgrade an existing EasyLicenser 2.0 installation to the EasyLicenser 2.5 level, until you recharge your installation with an EasyLicenser 2.5 level key issued by Agilis.
There are three types of upgrades: upgrading the license manager installation itself, upgrading an eCommerce web site or other back office system that uses the EasyLicenser key generation API's, and upgrading your application to use the EasyLicenser 2.5 run time libraries.
You can upgrade your existing EasyLicenser 1.1 or EasyLicenser 2.0 installation to EasyLicenser 2.5 without affecting your balance production license units or existing data as follows:
Download a fresh copy of the EasyLicenser upgrade package from the EasyLicenser web site at http://www.agilis-sw.com/ezlm/anondownload/ezlicmgrupgrd.zip or other URL provided by Agilis.
Position to within the existing product installation root directory (that is, in the ezlic1.1 or ezlic2.0 subdirectory).
Unzip the downloaded file into the directory. Your existing data and configuration files are preserved and are compatible with the current release.
Performing an upgrade of an existing production installation to EasyLicenser 2.5 has its limitations and constraints:
If you are upgrading from EasyLicenser 1.1, the upgrade will not automatically enable you to generate Orion server license keys. For this functionality, you will need to obtain a new Orion-enabled production EasyLicenser key from Agilis.
The upgrade will not automatically enable you to clone license keys or generate chained keys. To enable this functionality, you will need to obtain a production EasyLicenser 2.5 level EasyLicenser key from Agilis.
The upgrade will result in an EasyLicenser 2.5 installation that has "ezlic1.1" or "ezlic2.0" as its root directory, and a combination of EasyLicenser 1.1 / 2.0 and 2.5 libraries. Although this does not impact its functioning, it is nevertheless disconcerting. You can clean up the files ending in "11" or "20" (except for the files in the cpp directory since the shared library naming convention for C/C++ runtime libraries has been frozen); however, the installation root directory cannot be renamed, otherwise the EasyLicenser configuration will no longer be usable.
Performing the upgrade is therefore appropriate if you have a large balance of production license units and you want to use the new features of the EasyLicenser 2.5 License Manager other than Orion licenses and / or license key cloning and chaining.
You can upgrade your existing EasyLicenser 1.1 or EasyLicenser 2.0 based eCommerce site to EasyLicenser 2.5 without affecting your balance production license units or existing data as folows:
Download a fresh copy of the EasyLicenser eCommerce package from the EasyLicenser web site at http://www.agilis-sw.com/ezlm/anondownload/ezlicmgrecom.zip or other URL provided to you by Agilis.
Position to within the existing EasyLicenser eCommerce product installation root directory (which may not necessarily be the ezlic1.1 or ezlic2.0 subdirectory).
Unzip the downloaded file into the directory. Your existing data and configuration files are preserved and are compatible with the current release.
Performing an upgrade of an existing eCommerce production installation to EasyLicenser 2.5 has the following implications:
If upgrading from EasyLicenser 1.1, or upgrading from an EasyLicenser 2.0 installation that does not have an Orion-enabled production key, the upgrade will not enable you to generate Orion server license keys. For this functionality, you will need an Orion-enabled production EasyLicenser license key from Agilis.
If upgrading from EasyLicenser 1.1, note that as of EasyLicenser 2.0, the upgraded key generation library allows you to programmatically recharge your license units directly from your web application, so you no longer have to use the License Manager GUI for this purpose. If upgrading from EasyLicenser 2.0, the upgrade also provides you with the recharge command line utility that enables you to recharge your license units from a command line or shell script.
You should upgrade your existing EasyLicenser 1.1 and EasyLicenser 2.0 based applications to the EasyLicenser 2.5 run time libraries even if you do not take advantage of the new features, in order to benefit from bug fixes and internal functionality improvements. Perform the upgrade as follows:
Java applications:
In your product packaging, replace ezlicrun11.jar or ezlicrun20.jar and ilscrypt10.jar
with the two libraries:
ezlicrun25.jar located at the lib subdirectory of the product installation.
ilscrypt10.jar located at the extlib subdirectory of the product installation.
The classpath also needs to include the directory containing the jar libraries.
The directory path containing the jar libraries cannot contain URL-encodable characters, in particular white spaces. All directory names are required to consist of alphanumeric characters, '-', '_' and '.'.
C/C++ applications:
In your product packaging, replace your
platform-specific ezLicenserlib11.so/dll/a or ezLicenserlib20.so/dll/a shared library with the
ezLicenserlib20.so/dll/a shared library located at the platform-specific
subdirectory under the cpp/lib subdirectory of the product installation.
Note that the shared library versioning is frozen at "20" and will not change
in future versions. Note also that API calls are available for introspecting
the runtime library major and minor versions.
Modify your application's makefiles to refer to the new shared library (Windows:
import library ezLicenserlib20.lib) instead of the current library.
It is recommended that you upgrade your application source code to utilize the new API's,
in particular the core API's that accept a strict password check parameter.
The license key checking API's that accept product name and application passwords are
required to be used if you will be generating application password protected keys.
See below for a full discussion of key compatibility considerations.
Performing an upgrade of your application to the new EasyLicenser 2.5 runtime libraries has the following implications:
If the new API's are used, the upgraded application will work with all EasyLicenser keys including legacy (1.1) keys.
When upgrading from EasyLicenser 1.1, if the application source code is unmodified and therefore continues to use the existing API's, the application will work with EasyLicenser 1.1 keys and keys generated with EasyLicenser 2.0 as well as EasyLicenser 2.5 based on product definitions for which an application password is not specified.
When upgrading from EasyLicenser 2.0, if the application source code is unmodified and therefore continues to use the existing API's, the application will work with keys generated with EasyLicenser 1.1 and EasyLicenser 2.0 as well as EasyLicenser 2.5.
Backward compatibility is preserved between the three versions: EasyLicenser 1.1, EasyLicenser 2.0 and EasyLicenser 2.5. In addition, forward compatibility is maintained to the maximum extent possible. The specific rules governing compatibility between EasyLicenser 1.1, EasyLicenser 2.0 and EasyLicenser 2.5 are enumerated below.
This is applicable only to the License Manager user interface.
Backward compatibility: The EasyLicenser 2.5 License Manager GUI can be used to import, export, view details and otherwise process existing product definitions that were created with EasyLicenser 1.1 or EasyLicenser 2.0.
Forward compatibility: The EasyLicenser 1.1 License Manager GUI can be used to import, export, view details
and otherwise process product definitions that are created with EasyLicenser 2.0 or EasyLicenser 2.5 provided the
products don't have application passwords associated with them, and provided the products' option
names don't contain the ':' character.
The EasyLicenser 2.0 License Manager GUI can be used to import, export, view details
and otherwise process product definitions that are created with EasyLicenser 2.5.
Key compatibility has two aspects: the License Manager user interface and the run time libraries.
License Manager backward compatibility: The EasyLicenser 2.5 License Manager GUI can be used to import, export, publish, view details and otherwise process existing keys that were generated with EasyLicenser 1.1 or EasyLicenser 2.0.
License Manager forward compatibility: The EasyLicenser 1.1 License Manager GUI can be used to import, export, publish, view details and otherwise process keys that are generated with EasyLicenser 2.0 or EasyLicenser 2.5 provided the keys are not based on product definitions having application passwords defined on them.
Runtime library backward compatibility: The Java and C/C++ EasyLicenser 2.5 runtime library will correctly process keys that were generated with EasyLicenser 1.1 or EasyLicenser 2.0.
Runtime library forward compatibility: The Java and C/C++ EasyLicenser 1.1 runtime library will correctly process keys that are generated with EasyLicenser 2.0 or EasyLicenser 2.5 provided the keys are not based on product definitions having application passwords defined on them, and the keys are not Orion server keys.
The new runtime library introduces additional API calls while continuing to support existing API signatures.
API backward compatibility: A Java or C/C++ application can use the new runtime library with no source code modifications. From the perspective of the application logic, the existing semantics are preserved for the current API calls.
API forward compatibility: Not applicable by definition. If the application uses any of the new API calls, it needs to be packaged with the new runtime library.
The product packaging has been revised to accommodate new functionality and to streamline multiplatform support for C/C++ run time libraries as follows:
In addition to the command line utilities described above under Command Line License Management Utilities,
the util directory includes additional Java utilities over and above the makelibdigest utility added in EasyLicenser 2.0:
a datetodays utility that translates a date to a number of days from the time of execution for the purpose of computing expiration days to
input into the License Manager utility when generating time limited licenses, and a sysinfo utility that displays the Java runtime
system environment for diagnostic purposes.
Utilities in the util directory are invoked with the run.bat / run.sh command. To obtain help information on a
utility, invoke the utility with no arguments.
The Java and C/C++ demos include an additional demo application that illustrates the use of the new extended API.
Beginning with this release, the C/C++ platform support that is included with the core packages encompasses all supported platforms, which are currently 32-bit Windows, 32-bit Linux on Intel, and 32-bit Solaris on Intel and SPARC. Also, the major and minor number versioning in the shared library names is discontinued and frozen at the last value of "20".
For information on considerations in upgrading from
EasyLicenser 1.1 that are pertinent to EasyLicenser 2.0, refer to the What Was New In EasyLicenser 2.0.
For information on how to use the new License Manager
user interface, refer to the License Manager User Guide.
A guide to programming with the new Java run time library API's is available as part of the
Java ISV Application Development Guide. Its corresponding API
reference is available in the Java Run Time Library API Reference.
Example applications that illustrate the use of the run time library are included in the demo
directory.
A guide to programming with the new C/C++ run time library API's is available as part of the
C/C++ ISV Application Development Guide. Its corresponding API
reference is available in comments in the header files located at cpp/include.
Example applications that illustrate the use of the run time library are included in the cpp/demo/src
directory.
A guide to programming with the new Java license key generation API calls is available as part of the
Java eCommerce Application Development Guide. The corresponding API
reference is available in the Java E-Commerce License Key Generation API Reference.