Integrating RLM Into Your Product

OVERVIEW - Software License Management Basics

If you have used other license management products, you can skip this section. If this is your first time, however, we have included an overview of how license management products operate.

RLM is similar in structure to most popular license managers. RLM consists of 3 major components:

A client library
A license server (RLM has 2 license servers - a generic server called rlm and an ISV-specific server.)
A text file which describes the licenses granted (the license file).

Your application is linked with the client library which provides access to the license management functions.

The license server is used for floating licenses and logging of usage data. Your license administrators also have the ability to control certain aspects of the license server’s operations by specifying options in The ISV Options File in the License Administration manual.

The RLM client library (linked into your application) and the license server are both controlled by license authorizations stored in a text file called the license file.

Most license managers provide APIs with calls to control many of the aspects of licensing behavior, as well as options within the license servers to control licensing behavior. The design philosophy of RLM is to preserve the simplicity of the system for both ISVs and license administrators by avoiding all unnecessary options in the client library and the license servers and moving all these options to the license file, where they are visible and understandable by everyone. In general, license policy should be kept out of the application and the license server, and placed into the license itself. This makes for a more understandable licensing system for both ISVs and license administrators. The API is simpler, and the license server performs in a more standard way from ISV to ISV. This prevents license management confusion in license administrators. We learned this the hard way when we supported hundreds of customers in the past, and applied these lessons to the design of RLM.

INTEGRATING RLM Into Your Product - The 6 Steps

In order to add license management capabilities to your product, there are 6 main steps:

Decide on your Licensing Strategy
Create your Keys (public/private key pair)
Add RLM API calls to your application
Configure and build your RLM Kit
Package your software for shipment
Create licenses for your customers

These steps are described in the following sections.

1. Decide on your Licensing Strategy

RLM allows you to request and release licenses for products. The license for a product has certain attributes, which are described in the license grant itself (which is contained in the license file).

The most basic license attributes are:

ISV name (you pick this when you purchase RLM)
Product name
Highest Version supported
Node-locked or floating (if node-locked, the node identification)
Expiration date

Before you integrate RLM into your application, you must decide which products you wish to license and select the product names for the licenses. It is generally recommended that you choose names that correspond very closely to the name which your customer purchases - it makes license administration much more straightforward for your customers if the name of the product in the license is the same as what they purchased.

Note

Product name must be less than 40 characters.

In addition, each license request will specify a version. The two main strategies for selecting versions are either (a) make the version number match the major version of your software, in which case a new license would be required by your customers for each major release of your product or (b) only change the version in the license request occasionally, when you want to force your customers to purchase a new license.

So, before you start to integrate the code into your application, you should decide:

Where do you want to request and release licenses
What is the name of the license(s)
What license version to request.

Note

There is more information about these issues in the chapter on Creating Licenses.

Generally, the first two decisions will stay the same over the life of the software product, while you will update the license checkout version from time to time.

2. Create your Keys (public/private key pair)

Before you use RLM, you need to create a public-private key pair. You should only do this one time, since the key pair will affect the licenses you create, and you want to be able to process older license keys with newer versions of your software.

Note

You should do this once, not once per platform you install.

To create your key pair, run the rlmgenkeys utility. rlmgenkeys creates a pair of files:

rlmpubkey.c - your public key - this gets built into your application and your ISV server
rlmprivkey.c - your private key - this gets built into rlmsign to create your license keys

To run rlmgenkeys:

% cd kit-dir
% cd src
% ../platform-dir/rlmgenkeys

Where:

kit-dir is the directory where the RLM kit resides, and
platform-dir is the RLM binary directory for the machine on which you are running.

If you do not share src directories on your various platforms, run rlmgenkeys once and copy the resulting files to all the other src directories you use. Once you have created your key pair and installed it in the src directories in all your RLM kits, do a “make” in each kit to update the rlm.a library.

Warning

You should be very careful with these two files. DO NOT LOSE THEM. Do not allow your private key file (or rlmsign) outside your company. If your private key file (or rlmsign) becomes compromised, others will be able to make licenses for your products. Once you generate these files, you should copy them to a safe place where they will not be lost, and where they will be secure.

When you upgrade to a newer version of RLM, you will be asked for the location of these two files, so that the new version will generate compatible keys with your older versions.

3. Add RLM API calls to your application

Everything you need for most applications is contained in the 8 functions in the RLM core API.

These functions are described in Appendix A – RLM API.

Core API

These 8 functions provide all basic licensing operations needed for most applications:

Function	Description
rlm_init(), rlm_init_disconn()	Initalize licensing operations with RLM.
rlm_close()	Terminate licensing operations with RLM.
rlm_checkout()	Request a license.
rlm_checkin()	Release a license.
rlm_errstring()	Format RLM status into a string.
rlm_stat()	Retrieve RLM_HANDLE status.
rlm_license_stat()	Retrieve RLM_LICENSE status.
rlm_get_attr_health()	Check license status by checking server.

If you have special licensing needs that are not addressed by these functions, see Appendix A – RLM API which lists all RLM API functions.

4. Configure and build your RLM Kit

There are 4 configuration items you must complete before you build your RLM kit:

Install your RLM license.
Create your public/private key pair, which is done one time only and which was done in step #2, above. (See 2. Create your Keys (public/private key pair)).
Configure your RLM parameters.
Modify the makefile to change the ISV name “demo” to your ISV name (if you previously installed a demo kit).

Note

You can skip this last step if you have an evaluation kit.

To install your RLM license, first retrieve the license from our activation server using the activation key given to you when you purchased RLM (keep this key handy, it will not change across versions of RLM or when you buy new platforms). Next, cut and paste the output into the file src/license_to_run.h

Note

RLM kits are pre-built with demo license keys which expire in approximately 2 months from the date of kit release, so you may be able to skip this step if you are evaluating RLM).

Expand for an example license_to_run.h.

(this is a demo license which expired on 1-jul-2007):

/******************************************************************************
COPYRIGHT (c) 2007-2011 by Reprise Software, Inc.
This software has been provided pursuant to a License Agreement
containing restrictions on its use. This software contains
valuable trade secrets and proprietary information of
Reprise Software Inc and is protected by law. It may not be
copied or distributed in any form or medium, disclosed to third
parties, reverse engineered or used in any manner not provided
for in said License Agreement except with the prior written
authorization from Reprise Software Inc.
*****************************************************************************/
/*
* Description: License to use RLM
*
* Replace the RLM license on the four lines after:
*
* #define RLM_LICENSE_TO_RUN \
*
* with the license you received from Reprise Software.
*
*
*/
#ifdef RLM_LICENSE_TO_RUN
#undef RLM_LICENSE_TO_RUN
#endif
#define RLM_LICENSE_TO_RUN \
"1-jul-2007 \
sig=\"c2N250Z4hGt2HCMWNcye*Xe35YI8LGZf0ihLbEfJ8Bfe~zS0IFwu7R78Iye1ao\""
#define RLM_ISV_NAME "demo"

Your applications and your ISV license server are built from components supplied by Reprise Software. You need to provide 2 custom inputs for the build:

Your Public Key, for license key verification - rlm_pubkey.c - (This was done in step #2, above. See 2. Create your Keys (public/private key pair)).
A file of RLM customizations called rlm_isv_config.c (this file is contained in the src directory on the kit)

rlm_pubkey.c is created by the rlmgenkeys utility. You should run this only once to create your public/private key pair. Once you create these files, save them - if you lose one of these files, you will no longer be able to generate license keys compatible with older versions of your software.

Customizing RLM with rlm_isv_config

rlm_isv_config.c contains calls to:

set up your ISV name
install your RLM license (do not change this call)
specify the oldest server your application can use
specify the range of servers your settings file works with
enable the server to run on virtual machines
enable roaming on servers that use transient hostids
create “single” licenses when licenses are roamed, instead of uncounted
disable the RLM clock windback detection for expiring licenses
create a FLEXlm-compatible lock file
enable or disable Windows disk serial numbers which require admin access to use
enable disconnected license transfer
enable or disable client-side broadcast to find the license server
disable the use of the generic license server
enable license client-side caching
enable license server security checks
register ISV-defined hostids
include or exclude code for optional hostids (e.g., dongles, etc)
specify the types of hostids which Activation Pro will accept
specify the URL of your activation server (for Alternate Server Hostids)
disable the file id check and native hostid check for rehostable hostids
enable the remote time extension of roaming licenses.
Define isv-defined encryption handshake for the rlm web services API
specify the promise interval for HTTPS communications.
Specify hostid types that are disabled.

Edit this file before compiling your isv server, license generator, or applications.

Note

Your ISV name is, in general, case insensitive. The ONLY EXCEPTION to this rule is in the case of FLEXlm-compatible lock files. Since FLEXlm uses case-sensitive ISV names, the lockfile name must be case-sensitive. Therefore, if you are creating a FLEXlm-compatible lockfile, you should enter your ISV name in the exact case as in FLEXlm. The case of the name will affect the lockfile name, but only the lockfile name. Everywhere else in RLM, your isv name will be converted to lowercase.

Once you have created these 2 files you create your ISV server by typing “make” in the kit directory, and you are ready to link your applications with the RLM libraries.

Note

RLM kits are pre-built with demo license keys which expire in approximately 2 months from the date of kit release, so you may be able to skip this step if you are evaluating RLM).

5. Package your software for shipment

With RLM, you specify nearly all licensing options in the actual license that you ship to your customers. However, there are a few issues that you need to consider before you ship your application:

Review the RLM API calls you make in your application to be sure that you use product names that are suitable (we strongly recommend using the name of the product that is in general use), and that the version numbers are correct. If you intend for your customers to be able to use old licenses from your product, be sure that the version number in the rlm_checkout() call is appropriate.
If we have provided you with special debug libraries, make sure you use the nondebug libraries from the standard kit for your release.
Review the options you used to Build Your License Server.
Ensure that you have included the RLM Server, your ISV Server, and the RLM License Administration Tools (rlmutil, rlmhostid, rlmreread, rlmswitch, etc) in your distribution kit.
If you use the optional rlmID1 hardware keys with your product, make sure you ship the Aladdin utilities with your distribution kit. See Appendix D – Optional Hostid Installation Instructions for more details.
Review the Best Practices for RLM Integration section and ensure that your product and installation are well-behaved.

6. Create licenses for your customers

When you ship your product to your customers, it will require a license to run. Generally, you want to grant different license rights to each customer. In order to do that, you create a unique license file for each customer.

Format of the license file

The license file consists of lines of readable text which describe the license server node, some parameters of the license server binaries, and the actual license grants to your customers. For a complete description of the license file format, see The License File.

Types of Licenses

While there is a single format for the license file, the licenses you create can have many different meanings. For more details, see Creating Licenses.

License creation tool

RLM is shipped with a license creation tool called rlmsign which can be integrated into your fulfillment process. This tool reads a template license file and computes the license key for each license contained in the file. This license key authorizes the license and prevents tampering with the other license parameters. For more information on rlmsign, see Creating Licenses.

License creation API

In some cases, it is more convenient to build the license in-memory and sign that license directly before it is written to a file. In general, it is better to create the licenses in a file and use rlmsign to sign the licenses, however an API call, rlm_sign_license(), is available for cases where this is not practical. For details on the usage of rlm_sign_license(), see Appendix A – RLM API.

Note

Do not call rlm_sign_license() in an application or utility that ships to customers. Doing so will cause your private key to be included in the application executable or binary, which could expose it to hackers, possibly enabling them to create counterfeit licenses for your product.

Internet Activation

RLM Activation Pro allows the ISV to give a customer an activation key which then allows the customer to retrieve their license from the ISV website at a later time. The activation key is a short string (resembling a credit-card number) which can be generated in advance. Once the customer knows the system where they wish to use the software, the RLM activation software creates the license and transmits it to the user, creating the license file for them. Details of RLM activation are in the RLM Activation Pro manual. RLM Activation Pro is an optional product.

Reserved Product Names

In general, your product names need only be unique to your company. However, any product name beginning with the 4 characters “rlm_” is reserved. Currently, the following Product Names are in use:

Product Names

Name	Description
rlm_demo	Used by RLM to enable Detached Demo:sup:`TM` licenses for your products.
rlm_failover, rlm_failover_server	Used by RLM to enable failover license servers on a customer-by-customer basis.
rlm_roam	Used by RLM to enable license roaming for your products.
rlm_server	Used by RLM to create alternate hostids for license servers. Also note that the rlm_server license will not be visible in status requests, or in rlm_products() calls.
rlm_server_enable_vm	Used by RLM to enable license servers to operate on a particular virtual machine. (Note that you can enable your server to work on all virtual machines by calling rlm_isv_cfg_set_enable_vm() with the second parameter set to a non-0 value.) Also note that the rlm_server_enable_vm license will not be visible in status requests, or in rlm_products() calls as of RLM v9.0.
rlm_no_server_lock	Used to configure your ISV server so that multiple copies can be run on a single system. This should be done for in-house use of your ISV server only, for example, when supporting cloud computing with a number of your customers. Note that the rlm_no_server_lock license will not be visible in status requests or in rlm_products() calls. The reason this is for in-house use only is because if license administrators could run multiple copies of your ISV server he could serve the same license file from each copy, thus multiplying the number of licenses you intend for him to run.

Note

License replace processing uses the single-character product name ‘*’ to indicate all licenses, so you should avoid a product name of “*”.

The first 5 steps are done once or perhaps once per release of your software. The final step is done each time you sell your software to a customer.

Using RLM with the Visual Studio GUI

If you use the Visual Studio GUI interface on Windows, the procedure to configure the RLM libraries is as follows:

In a command window, build the RLM SDK as specified in Installing RLM. You need do this only once per release of RLM.
In your project settings / properties in Visual Studio:
- Under C/C++, add <RLM SDK path>\src to the Additional Include Directories (where <RLM SDK Path> is the path to the installed RLM SDK)
- Under the Link/Input/Additional Dependencies or Additional Library Path, add <RLM SDK path>\<platform>\rlmclient.lib (where <platform> is x86_w3, x86_w4, x64_w3, or x64_w4.
- Under the Link Command Line or Project Options section, make sure the following libraries are included:
  ws2_32.lib
  
  Advapi32.lib
  
  Gdi32.lib
  
  User32.lib
  
  winhttp.lib
  
  netapi32.lib
  
  kernel32.lib
  
  oldnames.lib
  
  shell32.lib
  
  wbemuuid.lib
  
  comsupp.lib
  
  ole32.lib
  
  oleaut32.lib
  
  libcmt.lib
Include these libraries if you’re using VC++ 2015 or later:
libvcruntime.lib

libucrt.lib

Then you will be able to use RLM in your project without leaving the GUI.

Using optional RLMID hostids

RLM currently supports one optional hostid choice:

rlmid1 - a hardware key manufactured by now SafeNet, Inc.

This optional hostid has specific requirements both when you build your product and when you ship it; it is available only on certain platforms.

Your license server (and the generic server) will be pre-built to support all rlmid devices on all supported platforms, so you are already enabled to use rlmid1 hardware keys as a server hostid. This means that if you only want to use rlmid1 devices to lock your license server, there is nothing more to do.

In your application, however, you need to enable the various rlmid hostids should you chose to use the particular hostid for nodelocked licenses.

Platform Support

The following table lists the first RLM version in which support is available for the particular rlmid device. Only the listed platforms are supported.

platform

rlmid1

x86_l2

v11.1

x64_l1

v11.1

x86_w1

v5

x86_w2

v5

x86_w3

v9

x86_w4

v12.0

x64_w2

v5

x64_w3

v9

x64_w4

v12.0

Startup Delay

Adding support for rlmid devices will cause your application to experience a short delay at startup time. We tested the following scenarios, using a loop of 2000 iterations which does rlm_init(), rlm_checkout(), rlm_checkin(), and rlm_close() of an uncounted license, on a 3GHz AMD desktop system:

Scenario

Total time

loops/second

seconds/loop

no rlmid support, license locked to ANY

30 seconds

66.67

0.015

rlmid1 support, license locked to ANY

37 seconds

55.55

0.018

rlmid1 support, license locked to rlmid1

40 seconds

50

0.02

rlmid1

The rlmid1 devices are manufactured by SafeNet (formerly Aladdin Knowledge Systems). They are a small purple USB hardware key containing an internal serial number. The hostid is printed on the outside of the key as “rlmid1=xxxxxxxx” where xxxxxxxx is the serial number (hostid) of the key.

Enabling rlmid1 devices in your application

Windows kits contain everything required to use the optional rlmid hostids, and support is configured into the ISV server by default - no additional installation steps are required. However, client-side support is not included by default, and you must follow these instructions to add support for using rlmid1 devices in your application.

Proceed as follows:

In order to enable rlmid1 devices for nodelocking in your application, locate the following 3 lines in rlm_isv_config.c:

#if 0
#define INCLUDE_RLMID1
#endif

Change the first line from #if 0 to #if 1. Re-build your rlm client library (by typing “make” on Unix, or “nmake” on Windows).

When you re-link your application, you will need to include the library rlmid1.lib (on Windows) or rlmid1.a (on Linux) from the RLM binary directory.

At this point, your application is enabled to use rlmid1 devices. You will notice that your application grows by approx. 900kb on Windows, and there will be a short delay the first time you request a license, when RLM attempts to determine the ID of any rlmid1 devices connected to the local system.

For information on shipping your product with rlmid1 devices, see Appendix D – Optional Hostid Installation Instructions.

Advanced API Functions

There are some options you can set within your application. Generally, the defaults will work, but if you want more control, you can look at Appendix A – RLM API for a description of all the available RLM API functions.

Clock Tampering Detection

RLM will attempt to check for system clocks that have been set back when it checks out a license that expires. This check will happen in the license server for floating licenses or in the client for node-locked licenses. This check is automatic; you do not need to modify your application in any way to affect this check.

RLM Host IDs

RLM supports several different kinds of identification for various computing environments, as well as some generic identification which are platform-independent.

RLM’s host identification (hostid) types are:
Type	Meaning	Example	Notes
ANY	runs anywhere	hostid=ANY
DEMO	runs anywhere for a demo license	hostid=DEMO
serial number	runs anywhere	hostid=sn=123-456-789	Used to identify a license, any string up to 64 characters long.
disksn	Hard Disk hardware serial number	hostid=disksn=WDWX60AC946860	Windows only.
32	32-bit hostid, native on Unix, non X86 based platforms	hostid=10ac0307	This is the volume serial number on windows, and is not recommended.
ip (or internet)	TCP/IP address	hostid=ip=192.156.1.3	Always printed as “ip=”. Wildcards allowed.
ether	Ethernet MAC address	hostid=ether=00801935f2b5	Always printed without leading “ether=”.
rlmid1	External key or dongle	hostid=rlmid1=9a763f21	External key or dongle.
uuid	BIOS uuid	hostid=uuid=699A4D56-58BF-1C83-D63C-27A8BEB8011A	Windows only.
user	User name	hostid=USER=joe	Case-insensitive
host	Host name	hostid=host=melody
gc	Google Compute Engine	hostid=gc=3797742226458986650- .k6qt9v5h38w2adwqgc9fdhdf3w0m761p	Linux only. DEPRECATED.

Warning

The Google Compute host ID is deprecated as of v14.2 and should not be used.

To determine the hostid of a machine, use the hostid type from the table above as input to the rlmhostid command:

rlmutil rlmhostid hostid type

For example:

rlmutil rlmhostid 32

or

rlmutil rlmhostid internet

When an application requests a license from a license server, it will transmit the hostid information from the local machine to the license server, so that the server can process node-locked licenses without additional queries to the application. The application will transmit a maximum of 25 different hostids: * one 32-bit hostid, if present on this platform * 1 or 2 Disk serial numbers (windows only) * up to 3 IP address * up to 5 ethernet MAC addresses (ether=) * up to 6 RLMID portable hostids * a UUID hostid, if present * a minimum of 3 ISV-defined hostids (usually more, but guaranteed to be at least 3)

Note

In RLM v15.0, the server will add the client’s external IP address to the list of IP addresses supplied by the client. This IP address is not added if it is the same as one of the client-supplied IP addresses.

For more information see Appendix C - RLM Hostids.