Creating Licenses

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.

Note

Every time you generate an RLM license, it gets a unique signature. Since RLM detects “duplicate” licenses by comparing the license signature, a newly-generated license will appear to be unique. This means that if you re-generate a license for your customer, even if it has the same parameters, it will add incremental licenses. If you need to regenerate licenses, Reprise Software strongly recommends that you use the issue date and the replace attribute.

License creation tools

There are 4 ways to create licenses using RLM:

  • rlmsign – command-line tool to sign a template license file

  • API call – rlm_sign_license()

  • RLM Activation Pro (an optional product)

  • rlmgen – GUI license generator

rlmsign

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

If you have a back-office sales tracking system, rlmsign is the easiest way to integrate license fulfillment. Create an unsigned license file for the sales order, then run rlmsign with this license file as its first parameter. rlmsign will sign the license file and make it ready to ship to your customer.

rlmsign reads the license file, computes the license keys for all the included licenses that specify your ISV name, and re-writes the file with the updated license keys.

rlmsign returns a 0 status if licenses were signed successfully, or if there were no licenses to sign. Otherwise, rlmsign returns a standard rlm error code from license.h.

Using rlmsign on Unix

% rlmsign license_file [bits-per-character] [-bits bits-per-character] [-maxlen len]

Using rlmsign on Windows

c> rlmsign license_file [bits-per-character] [-bits bits-per-character] [-maxlen len]

The optional parameter bits-per-character is one of 4, 5, or 6, and specifies the character encoding of the resulting license key. If not specified, bits-per-character defaults to 5.

bits-per-character

bits-per-character

Result

4

License key is hexadecimal and approximately 92 characters.

5

License key is numbers and uppercase letters only; the key is approximately 74 characters.

6

License is upper and lowercase letters, numbers, and 4 special characters (*, =, +, ~). Key is approximately 62 characters.

You can specify bits-per-character positionally as the 2nd argument, or you can use the -bits bits-per-character argument any place after the license_file parameter.

The optional -maxlen len parameter tells rlmsign to set the maximum length of LICENSE lines to the length specified. If this parameter is not specified, the default value of 70 is used. Any field on a license line which would cause the line to go over the maximum length will be placed on a continuation line. If a field can be split across lines (e.g., for fields that are quoted strings), then the field will be split when the maximum length is reached. The maximum length must be between 20 and RLM_MAX_LINE (1024) characters.

License creation API - rlm_sign_license()

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 is available for cases where this is not practical.

RLM also supplies the rlm_sign_license() API call to sign a license line in-memory. For details on the rlm_sign_license() API call, 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.

RLM Activation Pro

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. RLM Activation Pro is an optional product, and details of RLM Activation Pro are in the RLM Activation Pro manual.

rlmgen – GUI license generator

The rlmgen license generator can be used to create licenses interactively. rlmgen is a binary which contains an embedded web server – the UI is presented in your browser. For details on using rlmgen, see the next chapter - Creating Licenses – rlmgen.

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. The Reprise Product Names currently in use are:

  • rlm_demo - This product name is used by RLM to enable Detached Demotm licenses for your products.

  • rlm_failover, rlm_failover_server - This product name is used by RLM to enable failover license servers on a customer-by-customer basis.

  • rlm_roam - This product name is used by RLM to enable license roaming for your products.

  • rlm_server - This product name is used by RLM to create alternate hostids for license servers. The rlm_server license will not be visible in status requests, or in rlm_products() calls.

  • rlm_server_enable_vm - This product name is 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.

Creating Licenses – rlmgen

rlmgen is a GUI tool for use by ISVs to create one-off licenses based on stored product definitions.

rlmgen is a web-based application which allows you to create and edit product definitions for fulfillment, then create individual licenses for in-house or customer use.

rlmgen uses RLM licensing to control access to the two main functions:

  • Editing the product definition database (rlm_act_admin license)

  • Creating product licenses (rlm_gen_license license)

The use of these licenses will be described later in this section.

Running rlmgen

Usage:

rlmgen [optional port#]

Run rlmgen from the command line. rlmgen uses a web interface which runs on port 6600 by default. If you specify the optional port#, rlmgen will use this port number in place of 6600.

Once rlmgen is running, point your web browser to “hostname:6600” (http://hostname:6600/home.asp), where hostname is the name of the machine where you run rlmgen (or “hostname:alternate port#” if you specified an alternate port#).

rlmgen creates data files for product definitions in the same directory as the binary. It also expects these data files to be in the same directory when it attempts to read them.

rlmgen Licensing and Access Control

rlmgen uses 2 licenses to control access to back-office license operations:

  • rlm_act_admin license - this license enables the creation and editing of product definitions.

  • rlm_gen_license license - this license enables the creation of individual licenses using the “Create License” button.

When you install the RLM kit, nodelocked-uncounted licenses (locked to hostid ANY) are created for both of these licenses so that you can get started. If you do not care about access control to rlmgen, you need do nothing further. On the other hand, if you do care about access control to these functions, you should edit the licenses created during the install procedure to limit access to rlmgen. In any case, you should make sure that the license file is present in the same binary as the rlmgen binary if you move rlmgen to a different directory.

Since rlmgen is a web-based application, you will need to issue licenses for rlm_act_admin and rlm_gen_license for the IP addresses of the machines you would like to be able to perform these activities. Edit these licenses for your particular network.

Using rlmgen

There are 2 main activities you will perform with rlmgen:

  • Initial setup of your product definitions.

  • Generating individual licenses.

When you run rlmgen, the application will start a web server on port 6600 (or an alternate port if you specify on the rlmgen command line). Next, point your browser at port 6600 on the machine where you ran rlmgen.

Your browser will display a page that has a title area at the top, along with a column of command buttons along the left, and a main display area on the bottom right-hand side. The startup screen is shown below:

../_images/rlc.png

The command buttons are arranged in 3 groups, top to bottom:

  • Setup commands - “Create Product Definition” and “Setup License Generator”

  • License generation commands - “Create License”, and

  • Database viewing/updating commands - “View Product Definitions”, “View System Info”, and “About rlmgen…”

Each of these commands will be described in the sections which follow.

Setup Commands

The 2 setup commands are:

  • Create Product Definition

  • Setup License Generation

These commands are used to set up the database for license generation. Everything in rlmgen is driven from product definitions, so you should create at least one product definition first. Product definition allows you to specify a name for the “product” which is then associated with a license product name, version, and several other license parameters.

The Setup License Generation form allows you to specify which optional RLM license parameters will be presented in the GUI for specification. Any parameters checked on this form will appear in the license creation screens. If you specify some of these parameters as part of the product definition (in the “other license parameters” field), they will not appear in the list of checkboxes in Setup License Generation (since they are already specified for the product). You should leave any parameter which you do not want to put into a generated license unchecked in this form.

License Generation Commands

There is a single license generation command Generate License, which brings up a form that allows creation of a single license from parameters specified in the forms.

The data appearing in the license creation forms is customized by both the product definition as well as the Setup License Generation form.

Database Viewing/Updating Commands

These commands are:

  • View Product Definitions

  • View System Info, and

  • About rlmgen..

These commands all allow viewing of the product definition database. The first command also will allow you to edit product definitions, by pressing the “Edit” or “Disable” button at the end of the row in the display. Product definitions which are disabled are not deleted, but will appear in gray in the list, and can be re-enabled later.

View System Info displays information about the system where rlmgen is running, including the RLM platform, RLM version, and hostids for this system.

About rlmgen… displays information about the rlmgen program itself.