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 3 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)
Note
There was previously a fourth way—rlmgen—that has since been deprecated.
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 |
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.
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.