Cinnabar License Manager

Thanks for choosing Cinnabar License Manager (CLM) to help enforce your software licensing terms! Each software vendor has different requirements for runtime license enforcement. The beauty of CLM is that it is powerful and flexible enough to address almost any software licensing need. This document describes the concepts of software licensing, why you should use runtime license enforcement, and how CLM can enable you to do just that.

Software Licensing is the process by which most computer users acquire their software. Software is almost always licensed, rather than sold. Thus, when an end user pays for software, what he is actually paying for is not the software itself, but rather the right to use the software. The right of use that is granted to an end user usually comes with certain conditions, specified by you, the licensor. These conditions may restrict the user’s right of use to a limited time period, a limited number of machines, or in some other way. In most cases, such conditions are detailed in a printed or on-line license document.

Although most licenses purchased by end users come with conditions of use, in most cases the licensing conditions are not enforced in any proactive way. That is, once the user agrees to the conditions, the licensor simply trusts that the user will abide by them. Runtime License Enforcement enables you to enforce the conditions of a license in a proactive way, every time the software is used. If the license conditions are violated, your software can take some appropriate action, as defined by you.

CLM is a class library that enables programs written in the Java language to use Runtime License Enforcement. The CLM client API is very simple, with a single function that checks to ensure that the current runtime environment is in compliance with the desired licensing parameters. To illustrate the simplicity of the CLM API, consider the following code fragment:

LicenseManager mgr = new LicenseManager(clmLicenseStream, 
    productLicenseStream, publicKeyStream);

mgr.acquireLicense(product, feature);

In this example, if the call to acquireLicense returns without throwing an exception, then the current runtime environment is in compliance with the license conditions specified by the license file. It’s that simple!

CLM uses the following license parameters to ensure runtime compliance with the license conditions. Using these parameters, you can define what you are licensing, who is authorized to use it, and when or where they are authorized to use it.

In order to use Cinnabar License Manager to do runtime license enforcement, you must perform the following steps:

The following illustration gives an overview of the entire licensing process.

Figure 2.1. CLM Overview

CLM uses public-key cryptography to ensure the integrity of license files in the field (more about license files in a moment). Since CLM uses public-key cryptography, you have to create a keypair. A keypair is a matched set of keys – one private key, and one public key.

To create a keypair, you can use the LicenseTool program that comes with CLM (see Section 3.1, “Using the LicenseTool Program” for details). You can also use the generateKeypair Ant task to generate a keypair using an Ant build file (see Section 3.2, “Using the Ant Tasks” for details). Once you create a keypair, you use the private key to sign license files, and the public key to verify license files. You can decide if you want to use a given keypair for all the license files your company generates, or for only the license files generated for a particular product, or even for just a single use. The frequency with which you generate a new keypair is up to you.

To create a license file, you first specify the conditions of your license in a License Definition File (LDF). Then, you use your private key to sign the LDF, using the LicenseTool program. The LDF and its signature are packaged into a single file called the License File.

<license name="WidgetMaster6000">

<licensee name="Ralph’s Stop-n-Shop">

<feature name="saveToXml">

<attribute name="issuedBy" type="string" value="Nancy"/>

<license name="WidgetMaster6000">
  <licensee name="Ralph’s Stop-n-Shop">
    <feature name="saveToXml">
      <attribute name="clm-ExpireDate" type="string"
                 value="20030601"/>
    </feature>
  </licensee>
</license>

<license name="WidgetMaster6000">
  <licensee name="Ralph’s Stop-n-Shop">
    <feature name="saveToXml">
      <attribute name="clm-ExpireDays" type="int" value="30"/>
    </feature>
  </licensee>
</license>

<license name="WidgetMaster6000">
  <attribute name="issuedBy" type="string" value="Nancy"/>
  <licensee name="Ralph’s Stop-n-Shop">
    <attribute name="clm-NodeId" type="string"
               value="0020781F4336"/>
    <feature name="saveToXml"/>
  </licensee>
</license>

Integrating your application with CLM is very easy. You simply create a LicenseManager object, and then call the acquireLicense method of that object to verify that a license is available for the specified product and feature. To create a LicenseManager object, instantiate an object of the class com.cinnabarsystems.clm.LicenseManager, specifying the source of your CLM license file (provided to you by Cinnabar Systems), the source of the product license file(s) to check, and the public key to use to verify the product license files. Several constructors are available to accommodate different sources for the license files and public key data. For example, the following code creates a LicenseManager object that reads the CLM and product licenses from FileInputStreams, and the public key data from a resource stream:

InputStream myCLMLicenseStream =
    new FileInputStream("clm.lic");
InputStream myLicenseStream = 
    new FileInputStream("license.lic");
InputStream myPublicKeyStream =
    getClass().getResourceAsStream("pubkey");
LicenseManager mgr = new LicenseManager(myCLMLicenseStream, 
    myLicenseStream, myPublicKeyStream);

There are other convenient LicenseManager constructors that can read all the license files in a given directory – see the online API documentation for full details.

Once you create the LicenseManager object, you can call the acquireLicense method to attempt to acquire a license for a given product and feature. If the license acquisition is successful (i.e., at least one of the specified license files grants a license for that product and feature in the current execution environment), then acquireLicense will return successfully. If the license acquisition is not successful, then acquireLicense will throw some subclass of LicenseManagerException.

try
{
    License license = mgr.acquireLicense(product, feature);
}
catch(LicenseManagerException lme)
{
    // A license could not be acquired; take some 
    // licensor-defined action
}

If acquireLicense returns successfully, it returns a License object. This License object is the root of an object hierarchy representing the license parameters in the license file that satisfied the license acquisition request. You can use the License object to obtain more detailed information about the license file that satisfied the acquisition request.

String issuedBy = (String)license.getAttribute("issuedBy");

After your application is integrated with the CLM APIs, it will require CLM code to run. The following table summarizes the CLM binary files you must distribute with your application.

If you are using Cinnabar Systems' Canner™ to distribute your application, then the files listed above will be bundled into your executable, and it is not necessary to distribute them separately. You can find more information about Canner™ at http://www.cinnabarsystems.com.

When you create a License File, you do so using a License Definition File and the private key of a keypair. Later, your application uses the public key of the same keypair to verify the License File. Every License File is specific to a keypair – it can only be verified by the public key that is matched to the private key that you used to create the License File. Managing the storage and distribution of the keys in your license-signing keypair is critical to assure the effectiveness and security of CLM.

The private key of a keypair should never be distributed outside of your organization. It should be treated as a business asset, and safeguarded to prevent outside distribution.

The public key of a keypair must be accessible to your application at runtime, so that CLM can use it to verify that the License File is genuine and unmodified. Your application passes an InputStream for accessing the public key to the constructor of its LicenseManager object. Possible means of storing the public key are:

The security of the public key is important – if an attacker can change the public key, he can create and sign his own License Files, thus defeating CLM. Unfortunately, the nature of Java makes it difficult to ensure secure storage of any Java code or resource. Making it reasonably difficult for an attacker to change the public key, combined with obfuscating your application’s class files, will discourage most licensees from investing time in defeating your application’s runtime license enforcement code.

To enhance the security of public key storage, as well as to make decompilation of your Java programs all but impossible, we suggest you use Canner™, a separate product of Cinnabar Systems. You can find more information about Canner™ at http://www.cinnabarsystems.com.

Cinnabar Systems provided you with a license file that authorizes you to use CLM. You must distribute this license file with your applications that use CLM, and you must provide an InputStream to this license file as the first parameter to all the LicenseManager constructors.

Cinnabar Systems recommends that, when you distribute your application, you bundle the CLM license file into your application jarfiles- this prevents you from having to distribute an additional file with your applications. Bundling the CLM license file into your application jarfile also simplifies the process of protecting your applications with Cinnabar Canner- the CLM license file will be encrypted and included in the canned executable file, along with the Java classes in your jarfile.

LicenseTool is a utility program to help you create and test License Files, as well as create new license-signing keypairs. To run LicenseTool, use the java -jar command to execute the jarfile clm-tools.jar. Note that the file cinnabar.dll must be in the system PATH or in the same directory as clm.jar when LicenseTool is executed.

LicenseTool returns a zero value to the command shell to indicate success, and a non-zero value to indicate failure.

java -jar clm-tools.jar generate –n newkey

Saved new keys to newkey.private and newkey.public

java -jar clm-tools.jar create –i myldf.xml –o mylicense.lic 
    –n mykey

java -jar clm-tools.jar create –i myldf.xml –o mylicense.lic 
    –k mykey.private

Created license file mylicense.lic

java -jar clm-tools.jar verify –i mylicense.lic –k mykey.public 
    -l clm.lic

License file mylicense.lic verified ok.

java -jar clm-tools.jar test –p WidgetMaster6000 –f saveToXml 
    –i mylicense.lic –k mykey.public -l clm.lic

java -jar clm-tools.jar test –p WidgetMaster6000 –f saveToXml 
    –r –i .lic –k mykey.public -l clm.lic

License for WidgetMaster6000/saveToXml successfully acquired from 
mylicense.lic

java -jar clm-tools.jar dump –i mylicense.lic 

license, product name=WidgetMaster6000
        licensee, name=Ralph’s Stop-n-Shop
                feature, name=saveToXml
                      attribute, name=clm-Expire-Days, value=30

If you use Apache Ant in your build process, you can easily integrate CLM tools into your build. Five Ant Tasks are provided in the file clm-ant.jar. These Tasks provide all the functionality that the LicenseTool program provides, in a form that can be easily integrated into an Ant build process.

<property
    name="clm.classpath"
    value="clm-ant.jar;clm.jar"/>

<taskdef
    resource="com/cinnabarsystems/clm/ant/taskdefs"
    classpath="${clm.classpath}"/>

<generateKeypair
    newPrivateKeyFile="newkey.private"
    newPublicKeyFile="newkey.public"/>

<createLicense
    licenseDefinitionFile="myldf.xml"
    licenseFile="mylicense.lic"
    newPrivateKeyFile="mykey.private"
    newPublicKeyFile="mykey.public"/>

<createLicense
    licenseDefinitionFile="myldf.xml"
    licenseFile="mylicense.lic"
    existingPrivateKeyFile="mykey.private"/>

<verifyLicense
    licenseFile="mylicense.lic"
    publicKeyFile="mykey.public"
    clmLicenseFile="clm.lic"/>

<acquireLicense
    licenseFile="mylicense.lic"
    product="WidgetMaster6000"
    feature="saveToXml"
    publicKeyFile="mykey.public"
    clmLicenseFile="clm.lic"/>

<acquireLicense
    licenseDirectory="licenses"
    licenseFileExtension=".lic"
    product="WidgetMaster6000"
    feature="saveToXml"
    publicKeyFile="mykey.public"
    clmLicenseFile="clm.lic"/>

<dumpLicense
    licenseFile="mylicense.lic"/>