Activation Keys

If you are going to use RLM Activation Pro, you will then need to create activation keys - these are the keys you give to your customers. When they have the activation key, they can then use Activation Pro to fulfill licenses for their products. Activation keys can be set up to allow unlimited use, or a fixed number of uses.

Note

Single quote (‘), double quote (“) and semicolon (;) characters are illegal in activation keys.

Activation keys consist of:

Activation type
Product definition name to be fulfilled
Fulfillment count
Number of independent activation keys to create
Hostid change (rehost) count (for rehostable hostid types)

In addition, when you create activation keys, you can also specify:

Last date valid for this activation key
Expiration date which overrides the expiration in the product definition
License version which overrides the version in the product definition
List of allowed domains for this key
Optional additional attributes for the license
Optional notes for the activation key (unused by RLM)
The actual activation key string
Contact person to associate with this activation key.
List of allowed hostid types, if you want to override the default and/or product definition

When you select the Activation Keys tab you will see a list of activation keys:

The first 2 boxes at the top always appear, but for the last 5 boxes, each one will only appear if there are one or more keys of that type.

At the bottom of the list there are 2 buttons (“Check All” and “Clear All”), and a red X:

Every activation key which can be deleted (i.e., activation keys with the red X on the right-hand side of the list) will have a checkbox on the left. If you would like to delete multiple activation keys in a single operation, check the boxes corresponding to these activation keys then click the red X at the bottom of the form. You cannot delete an activation key which has any fulfillments associated with it.

The small “gear” icon on the far-right-hand side is the “activate license” button. This button allows you to fulfill the license directly from the ActPro GUI (new in RLM v14.2). If the fulfillment doesn’t work, first check your license generator URL in the admin->database tab – we have attempted to set a good default for this, but it might not always work. In particular, it won’t work on Windows servers, where the trailing “.exe” will not be present in the URL.

A sample URL would be:

https://hostedactivation.com/cgi-bin/your-isvname_mklic

When you press the “activate license” button, you will see the following form :

The hostid and count parameters are required, “extra license parameters” are optional, and consist of valid RLM keyword=value pairs. If the value has spaces, enclose it in double-quotes, for example:

options=”a b c” customer=”xyz corp”

If there are no REFRESH type activation keys, the # rehosts allowed column is not displayed.

In order to create an activation key, press the Create New Activation Key button at the top (or bottom) of the screen. When you do this, you will see the “Create Activation Key” screen, as shown here:

Activation Key Type is one of the following:

Normal
Reactivate
Normal-Regen
Refresh (deprecated in RLM v9.3)
Subscription

These are described in the Activation Key Types section below.

The product name is the name of the product definition to be activated.

The # of fulfillments is the number of fulfillments allowed by this activation key. For Refresh and Subscription keys, this is always 1, and even if you enter a larger number, RLC stores the fulfillment count as 1. The meaning of fulfillment count depends on the type of fulfillment, see below.

The # of rehosts allowed is used for the revocation of rehostable licenses. Used for Normal, ReActivate and Subscription activation types, this controls the number of times your user can revoke their license and then re-activate it on any machine (including the machine it was revoked from). If set to 0, an unlimited number of rehosts are allowed. If set to a positive number, this is the total number of rehosts that are allowed. If an attempt is made to revoke a license which has already been revoked the # of rehosts times, the application will get an RLM_ACT_TOOMANY_HOSTID_CHANGES error.

The # of activation keys to create controls how many activation keys are created with the data in this form. If the key string is specified (see below), this exact key will be used if the # of activation keys is 1. If the # of activation keys is > 1, then the key string will have a 16-digit string appended for each unique activation key generated.

The Allowed domains (whitelist) is a space-separated list of domain names which are allowed to activate using this activation key. If a request comes in from another domain, it is rejected with RLM_ACT_NOT_WHITELISTED. The names in this list can be a substring of the hostname requesting the activation. So, for example, if you put the string “com” into this field, activation will be possible from any domain with “com” in the name (i.e., most domains). All names are case-insensitive, and the whole list must be less than RLM_MAX_HOSTNAME (64) bytes. If an activation key specifies allowed domains, the domain requesting the activation must be part of the allowed domains specification.

The Activation Key Expiration date for the activation key is the last date when the activation server will generate a license for this activation key. The activation server will continue to send previously-generated licenses if so requested. This is completely different from the license expiration date in the product definition – the last date valid is the last date when the activation server will create a new license for this activation key. Beginning in ActPro v12.0, you can specify an expiration date as YYYY-MM-DD, for example 2016-05-23 for May 23, 2016. You can convert all expiration dates in your database to this format using the “Normalize Dates” function in the Admin/Database tab.

The License Expiration Date, if specified, will override the expiration date specified in the product definition. If not specified here, the license expiration from the product definition is used. The date is specified in the same way as in the product definition, i.e., a positive integer indicates a license that expires that number of days from the date of activation, and a fixed date specifies a fixed expiration date. Any expiration date specified here overrides the expiration date of all licenses created by the product definition for this activation key. Beginning in ActPro v12.0, you can specify a fixed expiration date as YYYY-MM-DD, for example 2016-05-23 for May 23, 2016. The ActPro license generator will convert this date to the standard RLM format when the license is created. You can convert all expiration dates in your database to this format using the “Normalize Dates” function in the Admin/Database tab.

The Subscription Interval, used for Subscription keys only, is the basic subscription interval. This can be “month”, “quarter”, “year” or a number of days.

The Subscription Renewal Window is the # of days, prior to the subscription license expiration, that a re-activation of the subscription license is allowed. Once the date passes the expiration date minus the Subscription Renewal Window, the license generator will update the expiration date in the Activation Key and allow a new license to be generated.

The Product Version, if specified, will override the version specified in the product definition. If not specified here, the license version from the product definition is used. The version is specified in the same way as in the product definition, i.e., either a “normal” floating-point format version number, or an integer number of months for a date-based version. Any version specified here overrides the version of all licenses created by the product definition.

The Miscellaneous Options (hidden in screenshot above) are additional RLM license attributes which will be placed into the generated LICENSE. Any options specified in the activation key override corresponding attributes in the product definition, thereby allowing you to have default attributes which you modify for a particular customer when you create their activation key. These options are treated AS A UNIT, so specifying any of them in the activation key overrides ALL the options from the product definition. If you specify other license parameters in your call to rlm_activate() (or rlm_act_request()) those parameters will override both the product definition and the activation key.

The Disable, Allowed Platforms, Allowed Timezones, Share, and Hostid parameters can override the corresponding values in the product definition by checking the box for “Clear values from product definition”. Prior to Activation Pro v14.2, there was not a way to clear these values if they were specified in the product definition.

If this box is checked the product definition values for this parameter will not be used. If the “clear values” box is checked and no boxes below the “clear values” checkbox are checked, the corresponding parameter is removed and will not appear in the license. If any of the boxes below the “clear values” checkbox are checked, those values from the activation key definition will be used, independent of the setting of the “Clear values from product definition” checkbox - this is exactly the behavior of the pre-v14.2 Activation Pro product. This means it is now possible for the activation key to clear the corresponding value in the product definition.

The Notes field is unused by the activation software, other than in listings and reports.

The Contact Person choicelist allows you to associate a customer with this activation key. Create customers with the Add Customer button in the Setup Commands area at the top.

If you want to override the list of allowed hostids specified in rlm_isv_config.c with the rlm_isv_cfg_actpro_allowed_hostids() call (or the product definition, if specified there), you can select a set of allowed hostids in the Allowed Hostid Types section of this form. If you leave all these checkboxes blank, the default from rlm_isv_cfg_actpro_allowed_hostids() or the product definition will be used.

The activation key generated by RLC is a 16-digit number (with embedded dashes for a total of 19 characters) of the form:

aaaa-bbbb-cccc-dddd

For example:

4567-4997-7125-5436

Alternately, RLC will allow you to specify the activation key. If you specify a key and generate a single key, the exact key you specify will be used. If you generate multiple keys, RLC will append 16 characters (with 4 dashes) to the string you specified.

Note

The total length of the activation key cannot exceed 40 characters, so if you are generating multiple keys, this string cannot exceed 20 characters.

This activation key is treated as a string by all RLM activation components.

When you have completed entering the data, press the Generate Activation Key(s) button at the bottom of the form. Once you do this, you will see a screen with the activation key name(s) displayed, and a Back to List button. Pressing this button re-displays the list of activation keys.

This list gives you an overview of the activation keys in your Activation Pro system. If any activation key has no associated fulfillments, you can delete it by pressing the red “X” in the far right-hand column.

While viewing activation keys, hovering the cursor above the product name will display a popup listing the primary product’s license name, version, and type.

You can also view the fulfillments done for a particular activation key by clicking on the “Show” icon () at the end of each row in the Activation Keys display.

Activation Keys which are disabled (not deleted) will appear in gray in the list, and can be re-enabled later.

When you edit an activation key, a Clone this Activation Key button will appear at the bottom of the form. Press this button, then you can provide a new activation key name and the selected key will be copied to the new key name. (This feature introduced in Activation Pro v14.0).

Activation Key Types

The activation key type controls how the activation server processes requests. In all cases, for a node-locked license, the fulfillment count field represents the total number of independent licenses which can be generated. For floating licenses, the fulfillment count field represents the total license count of all floating licenses generated (multiplied by the individual license “# of licenses” multipliers, of course).

Note

We use the terms “activation key type” and “fulfillment type” interchangeably in this document.

Normal

The Normal activation key type is the most straightforward activation type, and represents what most people think of as software activation: each request from a new hostid generates a new license, and this license’s expiration date is computed at the time the license is activated. A subsequent request from the same hostid will cause the old generated license to be retrieved, with exactly the same license parameters. If you use the Normal fulfillment type for Rehostable licenses, you should always use a fixed expiration date, not a # of days, since if the user revokes the first license and re-activates it, a new license will be created, and you probably don’t want to allow the expiration date to move past the original expiration date.

Normal-Regen

The Normal-Regen activation key type works just like the Normal fulfillment type, except that new activation requests from the same hostid generate a new license, and consume activation count. This means that your user can re-activate the license on the same hostid and get a different license.

Warning

If you use this for any kind of counted license (floating or node-locked, counted), this means the customer can get N times the number of licenses you have authorized, SO PLEASE USE THIS ACTIVATION TYPE WITH CAUTION.

If you use the Normal-Regen fulfillment type for Rehostable licenses, you should always use a fixed expiration date, not a # of days, since if the user revokes the first license and re-activates it, a new license will be created, and you probably don’t want to allow the expiration date to move past the original expiration date.

Why would you want to use a Normal-Regen activation key type? The main reason would be for licenses where you do not really want to count how many fulfillments are done, but that you do want to change other parameters in the activation key so that your customer can re-activate the license using the same activation key and get their new license. With a Normal fulfillment, the customer would get the original license, which isn’t quite so useful.

Examples:

Licenses for RLM itself are not counted, but they are locked to an ISV name with the customer= field, and they specify the licensed RLM platforms using the platforms= field. We give activation keys to our customers for RLM, however, often a customer adds a platform. When this happens, we modify the platforms= definition in the activation key, and our customer can re-activate using the same activation key. (We also modify the version in the product definition when we release a new version of RLM.) We use a Normal-Regen key type for this.

Another example is our fulfillments for Activation Pro itself. We do not count the number of activation servers you run, but we do issue the licenses for one year. When you renew support, we update the expiration date in the activation key, and you are able to retrieve your new license with the same activation key.

Reactivate

For the Reactivate activation key type, additional activations on the same activation key are considered reactivations. A reactivation will have the same expiration date as the original activation. This can be used to allow your customer to move a time-limited license to a new host one or more times. So, for example, assume you sell a 1-year license, but you would like your customer to be able to move it one time during the year. In this case, set the fulfillment count to 2 and the activation type to Reactivation. Then, once your customer creates the first license it will have an expiration date one year out, but he can come back sometime later during that year and reactivate the license on another system. The new license would expire on the original expiration date. If he waited more than one year, no new valid license could be generated.

You should use the Reactivate fulfillment type for Rehostable licenses if you want to deliver a license which expires some number of days after it is first activated. In the case of rehostable licenses, however, the fulfillment count will NOT control how many times they can revoke and re-activate the rehostable license, and should be set to the actual fulfillment count you desire, since a revocation of a rehostable hostid returns activation count to the activation key. The # rehosts parameter will control how many times your user can revoke the rehostable license and re-create it. If you set the fulfillment count to a number > 1, you should be sure to set the # rehosts high enough to accommodate all licenses which will be activated with that particular activation key.

Subscription

The Subscription activation key type is used to manage Nodelocked License subscriptions.

When you create a Subscription Key, you enter the initial expiration date of the license, as well as the Subscription Interval and the Subscription Renewal Window. If you leave the expiration date blank, the initial expiration will be the date of activation plus the Subscription Interval.

Warning

You should NEVER use a relative expiration date (i.e., a positive integer) or “0” as the expiration date in a subscription key. (In ActPro v14+, the GUI will not allow you to enter a relative expiration date).

Also note that the expiration date from the product definition is never used for a Subscription-type key. Subscription keys allow a fulfillment count of 1 only, and in fact, the fulfillment count will be forced to 1 when you create the key.

Subscription keys can only be used for products with Nodelocked, Uncounted and Single license types. Any other license type specified in the product will result in an RLM_ACT_SUB_BADTYPE error return.

Once a subscription key is activated, the expiration date is written to the activation key. This will be the current date plus the Subscription Interval for the first activation if the actual expiration date was not specified when the key was created. At any time after the Expiration Date minus the Subscription Renewal Window, the license can be re-activated and the new license will expire on the Expiration Date plus the Subscription Interval. The license generator writes the new expiration date to the Activation Key. You should never have to update the expiration date manually in the subscription key, but if you do, you would need to remove the existing fulfillment if you are extending the expiration date.

If your customer attempts to re-activate a subscription license prior to the Subscription Renewal Window on a different hostid, the RLM_ACT_KEY_USED (-1005) error will be returned. Once the Renewal Window is reached, however, the license can be activated on any hostid.

If the customer re-activates a subscription license after the initial expiration, the subscription interval will be added to the current expiration date until a date later than the current-date plus the Subscription Window is achieved. For example, assume that the first activation results in a license which expires on Jan 15, the Subscription Interval is Monthly, and the Subscription Window is 5 days. If this license is re-activated on Jan 20, the new expiration will be Feb 15. If the license is re-activated on Feb 14, the new expiration will be Mar 15.

You should include the activation key in the license so that you can automatically request the new license. At any time after the expiration date minus the Subscription Renewal Window, you can do this most conveniently in your code after calling rlm_checkout() by calling rlm_license_exp_days() to decide that it is time to reactivate it, then rlm_license_akey() to get the activation key. Then you can call rlm_activate() to get the new license. If your window is set to 2 or 3 days, that means your customer will have 2 or 3 days for this activation to succeed.

The presumption with Subscription keys is that your customer continues to renew the subscription; you have nothing to do in this case. When your customer cancels the subscription, you disable or delete the activation key.

Example:

Let’s say you have a Subscription Activation Key that specifies a one-month subscription period and a 5-day Subscription Renewal Window. The activation key does not specify an expiration date.

If your customer activates this license on 12-Jan-2024, the generated license will expire on 12- Feb-2024, and this expiration date will be written to the activation key. Any attempts to reactivate the license prior to 7-Feb-2024 will result in the original license being returned (if from the same hostid) or RLM_ACT_KEY_USED if from a different hostid.

After 7-Feb-2024, a new activation request will cause the following to happen: The expiration date in the activation key will be updated to 12-Mar-2024. The fulfillment count will be decremented (to 0). The new activation will be allowed, and a license which expires on 12-Mar-2024 will be generated from the requesting hostid.

Now suppose the customer didn’t use the software until 15-Mar. His original license expired on 12-Feb, so the new activation will proceed, but since the current date (on the activation server) is past the next expiration date, the server will increment the expiration date, first to 12-Mar, then, noting that 12-Mar has already passed, it will update the expiration date again to 12-Apr-2024, and the new license generated will expire on 12-Apr-2024.

In your code, we suggest a algorithm similar to the following:

Check out the license.
Get the license “days to expire” with rlm_license_exp_days().
If the days to expire is < your subscription renewal interval, call rlm_license_akey(), and re-activate the license.
If the activation is successful, write the new license file out in place of the old one (i.e., overwrite the old license file).
The next time the software runs, it will use the updated license file.

Refresh

Refresh-type activations were deprecated in RLM v9.3, and should no longer be used.

Activation Key Processing

The processing for each type of activation key is described in the following table:

Activation Type	New request from the same hostid (with same count)	New request from new hostid (or same hostid with different count)	Expiration date of license
Normal	Prior license returned.	New license generated if sufficient fulfillment count is available.	Computed at activation time.
Normal-Regen	New (different) license generated and returned if sufficient fulfillment count is available.	New license generated if sufficient fulfillment count is available.	Computed at activation time.
Reactivate	Prior license returned.	New license generated.	Same expiration date as first activation done with this activation key.
Subscription	Prior license returned before Renewal Window, new license after Renewal Window.	Only allowed during Subscription Renewal Window.	Computed at activation time; updated in each Subscription Renewal Window.
Refresh (deprecated in RLM v9.3) – use REHOSTable licenses instead.	New license generated if request is on a new day, otherwise prior license returned.	New license generated until hostid change count exceeded, then RLM_ACT_TOOMANY_HOSTID_CHANGES error returned.	Computed at activation time.

In the table above, whenever the action listed is “prior license returned”, the remaining fulfillment count is not decremented. Whenever activation generates a new license, the remaining fulfillment count is decremented by the license count generated . If a rehostable hostid is revoked, the fulfillment count is incremented.