int slm_key(instance, way, key, keydata, options)
SLM_INSTANCE instance;
int way;
char *key;
struct slm_keydata *keydata;
unsigned long options;
DESCRIPTION
slm_key() may be used to encode and decode an 伸an License Manager license key.
伸an License Manager keys encode one or more feature names, server identification (code), a hard limit on the number of licenses for the feature, a soft limit on the number of licenses for the feature, and the following optional characteristics: start date, expiration date, domain specification, and vendor data.
There are two types of keys available:
Single server key A single server will manage licenses. This is the most common type of key generated.
Redundant key Redundant keys are used when multiple redundant servers for fail-safe operation is desired. When one server goes down, a backup server automatically takes over.
Keys may also encode a single feature or multiple features:
Single Feature Key A single feature key contains one feature name, plus relevant information for that feature.
Multi-Key Multi keys encode between 1 to 11 features in a single license key string. Multi-Keys are ideal for applications with more than one feature. You, the vendor, can give your customer a single license key to enable between 1 and 11 features of your product.
In Multi-Keys, the feature names are assumed to be in ascending integer order starting with keydata->feature. Thus, if a 3-feature Multi-Key is generated, and
keydata->feature is ?0,?then the Multi-Key will encode a license for ?0,??1,?and ?2.
?Each license within a Multi-Key shares the same host code, start date, expiration date, domain, and vendor data. Only the feature and number of licenses for each feature will differ.
You may use slm_key() to decode multi-keys, as well as to re-encode the keys to write out to the key files. For each feature to re-encode, slm_key() must be called with option SLM_LITERAL_HOSTIDS (described below). In addition, you must generate the datetag and hostcodetag information for each key file by calling slm_date_encode() and slm_hostcodetag_encode(), respectively.
Keys may also be of several access types:
Floating Licenses will be available to anyone on the network.
Personal (node-locked) Licenses will only be accessible to users on a designated host.
Domain Licenses will only be accessible to those users within a designated domain (subnet or group of subnets).
License keys are all decimal digits. With a 2-character feature name, keys are generally 16 to 20 characters. Vendor data and other information may make the key longer.
ARGUMENTS
instance The instance handle created by slm_startapi().
way Its value can be either SLM_ENCODE to generate a key, or SLM_DECODE to decode a key. When a key is encoded, the contents of keydata are read and a key is written into key. When a key is decoded, key is decoded, and keydata is filled in.
key A license key buffer of minimal length SLM_KEY_LEN+1. When a key is encoded, the contents of keydata are read and a key is written into key. When a key is decoded, key is decoded, and keydata is filled in.
keydata The address of an slm_keydata structure. When a key is encoded, the contents of keydata are read and a key is written into key. When a key is decoded, the key is decoded, and keydata is filled in.
options
SLM__LITERAL_HOSTIDS The host IDs are passed literally to create the key with further encryption. This option is convenient for re-crypting keys.
SLM_LITERAL_KEY If encoding, return a key as plain text, without passing it through the encryption stage. If decoding, assume the key has already been been decrypted (i.e., already in plain text).
SLM_STD_KEYS This is the standard option. Use this value if none of the other options apply.
The slm_keydata structure is defined in slm.h is as follows:
typedef struct slm_keydata
{
char feature[SLM_FEATURE_LEN+1];
char *code[SLM_MAX_SERVERS+1];
int server_count;
long nlic[SLM_MAX_SERVERS+1];
long soft_nlic[SLM_MAX_SERVERS+1];
int multikey;
int resource_attached;
time_t start_date;
time_t expiration;
char vendordata[SLM_VENDORDATA_LEN+1];
int domain;
} slm_keydata_t;
The definition of each field is provided below.
feature An all-decimal string between 2 and 12 decimal digits. For example, ?0,??9,??124,?and ?74638723?are all valid feature names. Two-character features names make the shortest keys.
Multi-Key feature names must be between 2 and 8 characters.
code One or more server codes generated by slm_gencode() or elmadmin -c: for each server code, pass in only those digits to the right of the forward slash (/), with all spaces deleted. These must appear in ascending order. (Use strcmp() to determine order. The lowest value goes first in list.) Multiple server codes indicate a redundant key.
server_count The number of server codes specified in code. If this number is zero, then an any-host key will be generated. Any-host keys are not tied to any particular host. Such keys are often useful for demo versions of software. Always generate any-host keys with an expiration date; without an expiration date, you generate an unlimited number of copy-able key to your application.
nlic The number of licenses to assign for the feature(s). If there is a single entry in this array, a standard key is generated. If there are multiple entries in this array, a multi-key is generated. If an entry is negative, the license key generated will be for -nlic non-floating (node-locked) licenses, as discussed above.
There is a limit of 9,000,000 floating licenses or 999,990 nodelocked licenses. Keys that encode more than 9,000 floating licenses or 900 nodelocked licenses will be longer by 3 characters. SLM_UNLIMITED_LICENSES means an unlimited number of licenses, and SLM_UNLIMITED_NODELOCK_LICENSES means an unlimited number of nodelocked licenses.
soft_nlic The soft limit. When the soft limit is exceeded, a message is logged in the elmd log file and the client application is notified. A value of zero means no soft limit.
multikey The number of entries in nlic. This may be at most SLM_MULTIKEY_MAXNUMFEAT (currently 11).
resource_attached If non-zero, a resource file is automatically loaded by elmd for this key.
start_date The start date of the feature in POSIX time in seconds. Zero means no start date is specified. Start dates must be above SLM_EPOCH (Jan 1, 1989 00:00:00, defined in slm.h). Note that start and expiration dates are stored in time-zone-independent format. They may be compared in the current time zone using slu_zonetime().
expiration The feature expiration date in POSIX time in seconds. Zero means no expiration. Expiration dates must be above SLM_EPOCH (Jan 1, 1989 00:00:00. defined in slm.h). Note that start and expiration dates are stored in time-zone-independant format. They may be compared in the current time zone using slu_zonetime().
vendordata Any string that you wish. The vendor data is for your application's use only?he license manager simply packages it and maintains it. It may be examined by your application via slm_getfeatureinfo(). A structure for the vendor data may be enforced with slm_getvdata() and slm_putvdata().
The vendor data may contain any alphanumeric ASCII character, including space and tilde. (If the string is all digits, the key will be shorter.) If vendordata contains all decimal digits, it may be at most SLM_VENDORDATA_LEN characters (currently 94). If vendordata contains any other characters, it may be at most SLM_VENDORDATA_LEN/2 characters (currently 47).
A common use of vendor data is encoding the product release number. For example, 20 in vendordata could mean that this key is valid for release 2.0 or earlier.
Although multiple features can be licensed with several keys or with a multi-key, the vendor data can also be used to supply multiple licenses within a single key. For example, in an accounting system, individual modules might be licensed by setting a bit in a single-character vendor data.
Vendordata In Binary Modules Licensed
"1" 001 #1 only
"2" 010 #2 only
??011 #1 and #2
... ... ...
??111 #1, #2, and #3
The procedure would be to call slm_getlicense() for the feature, which may be the accounting system name, and then use slm_getfeatureinfo() to discover the vendor data, and consequently, find the particular modules licensed.
It is wise to keep the vendor data as short as possible?t extends the key length by one plus the size of vendordata.
domain If desired, you may limit clients who may access a feature by a specifying a domain. If domain is ?,?only clients on the same Class-C network as the license server may check out licenses. (Same Class-C means their four-component IP addresses are identical except for the right-most component.) Similarly, domain may be specified as ?
B?or ??to limit access to Class-B or Class-A clients, respectively. If domain is zero, no restriction is enforced. This feature is not available for NetWare.
RETURN VALUES
SLM_OK The encoding or decoding was successful.
SLM_ERROR You are not authorized to build keys.
SLM_INVALID_ARG The argument way is not SLM_ENCODE or SLM_DECODE.
SLM_INVALID_DOMAIN The domain is invalid.
SLM_INVALID NLIC An invalid number of licenses was specified.
SLM_INVALID_SERVERCOUNT Too many servers were specified.
SLM_INVALID_FEATURE The feature name is invalid.
SLM_INVALID_VENDORDATA The vendor data contained invalid or too many characters.
SLM_INVALID_EXPIRATION The expiration date is invalid; it is either prior to SLM_EPOCH or too far into the future.
SLM_CODE_CORRUPT One or more entries in the array code is corrupt.
SLM_INVALID_STARTDATE The start date is invalid; it is either prior to SLM_EPOCH or too far into the future.
SUGGESTIONS
Short feature names and vendor data means short keys, which translates to happy customers.
