Click to go to home page

What's New In EasyLicenser 2.5


Preface

New Features

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 License Manager

Upgrading eCommerce Key Generation System

Upgrading Applications For The New Runtime Library

Compatibility Considerations

Compatibility Of Product Definitions

Key Compatibility

Runtime Library API Compatibility

Changes To Product Packaging

Utility Programs

Additional Demo Applications

Packaging For C/C++ Platform Support

Next Steps


Preface

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.

New Features

The key themes behind EasyLicenser 2.5 are:

License Manager Usability Enhancements

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:

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

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

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

  4. 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 License Management Utilities

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:

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

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

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

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

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

  6. Command-line key information utility: ezlicmgrkeyinfo.sh, ezlicmgrkeyinfo.bat, ezlicmgrkeyinfo25.jar

    Displays information about a license key.

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

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

Runtime Library API Enhancements

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:

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

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

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

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

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

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

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

License Key Generation API Enhancements

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.

Updated Platform / Language Support

Platform and language support has been fine-tuned in response to customer demand as follows:

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

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

Improvements To License Manager UI Manageability And Deployability

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:

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

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

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

Upgrading From Previous EasyLicenser Versions

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.

Upgrading License Manager

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:

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

  2. Position to within the existing product installation root directory (that is, in the ezlic1.1 or ezlic2.0 subdirectory).

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

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.

Upgrading eCommerce Key Generation System

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:

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

  2. Position to within the existing EasyLicenser eCommerce product installation root directory (which may not necessarily be the ezlic1.1 or ezlic2.0 subdirectory).

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

Upgrading Applications For The New Runtime Library

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:

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

    Modify your application's classpath to refer to the above libraries instead of ezlicrun11.jar / ezlicrun20.jar. If you are upgrading from EasyLicenser 1.1 and you are using the digital signature mechanism, it is recommended that you specify the library name qualified by a path when invoking the signature API call. Otherwise, there are two additional considerations:

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

    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.

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

Compatibility Considerations

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.

Compatibility Of Product Definitions

This is applicable only to the License Manager user interface.

Key Compatibility

Key compatibility has two aspects: the License Manager user interface and the run time libraries.

Runtime Library API Compatibility

The new runtime library introduces additional API calls while continuing to support existing API signatures.

Changes To Product Packaging

The product packaging has been revised to accommodate new functionality and to streamline multiplatform support for C/C++ run time libraries as follows:

Utility Programs

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.

Additional Demo Applications

The Java and C/C++ demos include an additional demo application that illustrates the use of the new extended API.

Packaging For C/C++ Platform Support

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

Next Steps

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.


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