Licensing of KCML & KClient


How users are counted.

When a terminal connects, for the first time, to the application server and starts KCML, a single KCML licence is used. If the terminal is using KClient, then a single KClient licence will also be consumed. This single KCML/KClient licence will allow up to four sessions from the terminal to connect at the same time, providing the same user ID is used. Subsequent sessions will consume one licence each. So five sessions will require two, six sessions will require three licences.

Different copies of KCML that are using different TERMFILEs on the same server will use the same licence pool unless $SYSTEMID has been set.

When sessions from the terminal have logged out, the licences are returned back to the free pool.

Certain Citrix/WTS systems may be restricted to one licence per session.


The KCML Licence File.

KCML and KClient are protected by a licence file, usually called lic.txt, that resides in the same directory as KCML. The licence file is a plain text file, which has several distinct sections.

Here is an example:

[General]
Serial=40155872
Address1=ACME Bolts Ltd.
Address2=Unit 1, Brunel Way
Address3=Reading
Address4=Berkshire
Address5=United Kingdom
Address6=RG10 0AB
security=!da5b c621 4bbf 8596
[MachineIdentity]
MID=AAC/5EyTy35cp6suan2PuYVeR9mVR1WLMwxjPFIApe4u1/V0UfW77H35apIAozlbXiRp4i1S8of9z6aWBceiydMyAvOok+6mmTbm9zAus94Xvl4ZiAJcVFr4b0KeuPI/c/V/BCauVmZj0iEJcyy12dWGMEI4L+2OCVgSXH0D0Dw4wK1/ZaJMTDWAjC2TUJWwiLQtv3Z7vVh+KzZPap3M9ysqd2S7a65YJQsiSTIOpy7bUA0tVr24Bnp+W0dYeJw4Oeo=!e137 f51a edfa 5f6a
[Protection]
CPU=2C25 FBC6 7E5D 8AD7!a189 c554 368d 649e
[KCML6]
GoldKey=5678!cb3f 07b4 6709 4eb5
Users=24,Serial=C17264587X!7a97 7104 7e07 fa52
Users=8,Serial=C09123491X!e7f1 05d6 94b0 0c38
Oracle=1!5ddb 88a2 5f16 2098
[KClient]
Users=16,Serial=C17264593C!83ed fcd3 afa2 bdf9
Users=16,Serial=C09165422C!5da6 2991 b326 f9c8
Style=1!8708 0e7f 88a2 2dfa

The contents of the file are protected by checksums to prevent fraud. Editing a licence file will invalidate it, the file will fail to load and KCML will return a Corrupt licence file error.

Other Keyloop products may also have their own entries in the licence file, for example KPrint will be licenced with a [KPrint] section.


[General] section

The [General] section of the file identifies the owner of the KCML licence. The first line is usually the Serial number, which is a unique identifier of the licence. This value should be used when requesting, from your Keyloop dealer, changes to your licence. Applications can find the value of this number by calling the $SER function.

Following the serial number will be the the customer's name and address. This information will be displayed, for a brief period, by KClient when connecting to the application server.


[Protection]

The licence is tied to the hardware of the application server, using a unique machine identifier. The licence cannot be copied from one machine to another. This machine ID a sixteen or thirty-two digit hexadecimal number, which can be found by running the getid program:

$ cd /usr/local/kcml
$ ./getid
2C25 FBC6 7E5D 8AD7

When you require a licence for a new machine, you will need to supply this value to your Keyloop dealer. The licence file you then receive should then have a [Protection] section, which has a CPU=machine ID line. For example:

[Protection]
CPU=2C25 FBC6 7E5D 8AD7!a189 c554 368d 649e

It is also possible for the [Protection] system to contain more than one CPU line which will allow the licence to work on more than one machine. This is particularly useful when falling back to a backup machine in the event of a Disaster Recovery procedure. Systems that use a single, eg Oracle, database server, but have multiple application servers, may also use this method.
For example:

[Protection]
CPU=2C25 FBC6 7E5D 8AD7!a189 c554 368d 649e
CPU=A425 152D 6D06 727A!0c40 1412 713b 19da
CPU=2CB7 BF4C 9D77 6597!317e df83 fa08 9d4b

[MachineIndentity]

The [MachineIdentity] section serves a similar purpose to the [Protection] section, in that it identifies the server's hardware. The section contains a MID key which, like the CPU key, identifies various hardware components. However the MID value is more flexible and can contain more components. The MID value is determined by running

$ cd /usr/local/kcml
$ ./getid -7
AAC/5EyTy35cp6suan2PuYVeR9mVR1WLMwxjPFIApe4u1/V0UfW77H35apIAozlbXiRp4i1S8of9z6aWBceiydMyAvOok+6mmTbm9zAus94Xvl4ZiAJcVFr4b0KeuPI/c/V/BCauVmZj0iEJcyy12dWGMEI4L+2OCVgSXH0D0Dw4wK1/ZaJMTDWAjC2TUJWwiLQtv3Z7vVh+KzZPap3M9ysqd2S7a65YJQsiSTIOpy7bUA0tVr24Bnp+W0dYeJw4Oeo=


[KCML]

This section determines maximum number of concurrent KCML users that are allowed to run on the application server. The limit is the total of one or more lines that begin with Users=.

[KCML6]
GoldKey=5678!cb3f 07b4 6709 4eb5
Users=24,Serial=C17264587X!7a97 7104 7e07 fa52
Users=8,Serial=C09123491X!e7f1 05d6 94b0 0c38

The above example will allow 24 + 8 = 32 concurrent KCML users.

Some, or all, of these lines can have an optional Date=yyyymmdd field. These lines will be only valid up to the specified date, beyond that they will not be added to the total.

For ASP systems, the [KCML] section can also contain a SYSTEMID value:

[KCML6]
GoldKey=5678!cb3f 07b4 6709 4eb5
Users=24,Serial=C17264587X!7a97 7104 7e07 fa52
Users=8,Serial=C09123491X!e7f1 05d6 94b0 0c38
SYSTEMID=4!0d92 8c70 7e9e 0cba

This value must match the value of the $SYSTEMID environment variable. When $SYSTEMID is set, KCML will attempt to open the licence using the filename lic.n.txt, where n is the value of $SYSTEMID. If lic.n.txt does not exist, then the normal filename of lic.txt will then be used.

Depending on the version of KCML that you are running, this can also be [KCML4], [KCML5], [KCML6] or [KCML7]. A section of [KCML] is equivalent to [KCML5] that is suitable for KCML 5.02 and 5.50.

The optional GoldKey entry can be used by applications which make use of the #GOLDKEY function.

[KClient]

The [KClient] section is very similar to the [KCML] section. It has one or more Users lines, the total of which determines how many KClient users may connect to the application server.


Oracle Database interface

The interface to Oracle database layer is provided a shared library, koracle.so. Access to the library's database routines is protected; when the shared library is loaded, via a call to KI_CONNECT, the licence file is checked.

Between KCML versions 5 and 6.40, the licence entry was a flag in the [KCML] section:

[KCML6]
GoldKey=5678!cb3f 07b4 6709 4eb5
Users=24,Serial=C17264587X!7a97 7104 7e07 fa52
Users=8,Serial=C09123491X!e7f1 05d6 94b0 0c38
Oracle=1!5ddb 81a2 5f16 2098

For KCML 6.60, however, there is a separate [Oracle] section in the licence file which stores the maximum number of users that can connect to the Oracle database:

[Oracle]
Users=5,Serial=C09123491X!b39b 7848 1978 a864

[SOAP]

When KCML is acting as a SOAP server, it will consume one KCML licence per instance. Originally, this licence was taken from the pool of licences for all KCML processes. If a lot of SOAP clients connected to the server at the same time the SOAP servers could consume all available licences, leaving none left for foreground sessions.

To overcome the problem, a licence file can now have a [SOAP] section:

[SOAP]
GoldKey=5678!cb3f 07b4 6709 4eb5
Users=24,Serial=C17264587X!7a97 7104 7e07 fa52
Users=8,Serial=C09123491X!e7f1 05d6 94b0 0c38

When a KCML SOAP server starts up, it will allocate a licence from a separate pool. Byte 75 of $PSTAT will be set to 'W'. The bytes of $MACHINE that are used to return licence counts will return information on the [SOAP] licence pool. If there are no more licences left in then the SOAP server will fail to start up and report the error to syslog:

KCML: ERROR /usr/local/kcml/kcml[root,31724]: Exited, 'SOAP session count exceeded'

The maximum number of instances of a particular SOAP server can be restricted with the $KCML_SOAP_LIC environment variable. This can be used to prevent a SOAP server consuming all [SOAP] licences, useful when there is more than one SOAP service.

SOAP servers that are running in an ASP environment, will require a SYSTEMID value in the licence file's [SOAP] section:

[SOAP]
GoldKey=5678!cb3f 07b4 6709 4eb5
Users=24,Serial=C17264587X!7a97 7104 7e07 fa52
Users=8,Serial=C09123491X!e7f1 05d6 94b0 0c38
SYSTEMID=4!0d92 8c70 7e9e 0cba

If the licence file does not contain a [SOAP] section, then KCML will revert to its original behaviour and will consume a licence from the pool of foreground licences, in this case byte 75 of $PSTAT will be set to 'B'.

When using KCML versions 06.20, 07.16 & 07.17 from build 23320 a [SOAP] licence will have an effective user count of 9999.

[Support]

See also KCML Support Access

The [Support] section was introduced with KCML 6.20, where access to an application's source code via KCML's workbench, is restricted. This section contains a Users value which is a bitfield that enables various development features.

[Support]
Users=15

This value can be found by inspecting byte 60 of $MACHINE.

The licence file that contains a [Support] section is usually installed into the same directory as KClient. This will ensure that only that terminal can view the application's code. For an application server that is used for internal development, it may be more convenient to have the [Support] section added to the licence file for KCML. This will enable development features for all KClient terminals that connect to the server. If the system is does not have a legimate [Support] licence then you will not be able to break into an application. KCML will also error with "Workbench access denied" if you attempt to start up the editor.

[Dealer]

This section is designed to provide the same source code security as the [Support] section.

The section has a Name attribute that identifies the author of the application. There are two possible configurations.
A server-side licence which defines a Users value will behave just like a server-side [Support] licence. For example:

[Dealer]
Name=123
Users=14

Will allow unrestricted access to the workbench.

However, if a dealer wishes to restrict access to their own terminals, then the server licence should not have a Users value:

[Dealer]
Name=123

To access the workbench, the dealer's terminals will require a client side licence which has a matching Name value and defines the appriate flags in the Users value. For example:

[Dealer]
Name=123
Users=14

Date Expired Licenses

Licence files can contain elements that expire on a given date. This is achieved by including the Date=YYYYMMDD keyword.
For example:-

[KCML7]
Users=10,Serial=C10070898X!81c6 d1e2 e0d1 28b6
Users=2,Date=20170325,Serial=C10070588U!d319 046a 5cc4 e7c3

Would allow upto 12 KCML7 users, two of which expire on the 25th of March 2017


Licensing Errors

Error MessageCauseRemedy
Invalid machine IDYour host's machine ID does not match with the CPU value in the licence file.Run getid to show the current value of your host's machine ID and then contact your Keyloop dealer.
Cannot open licence fileA licence file could not be found.Make sure the licence file has been copied into the same directory as KCML
Error reading licence fileA licence file was found, but could not be openedCheck the owner and permissions on the licence file. It should have read access for everyone
Corrupt licence fileThe contents of the file have been corruptedIf you have a backup of the file then use that, otherwise you will need to contact your Keyloop dealer so that the licence can be re-issued.
Terminal count exceededMore users have logged on than are allowed by the [KCML] section in the licence fileCheck that there no dormant sessions. Consult your Keyloop dealer for an increased number of users in your licence file
Forms user count exceededMore users have logged on than are allowed by the [KClient] section in the licence fileCheck that there no dormant sessions. Consult your Keyloop dealer for an increased number of users in your licence file
Maximum licence count has been exceeded on this terminalThe number of licences in use by a particular terminal has exceeded the limit set by the $KCML_TERM_LIC environment variableThis environment variable is used to restrict the number of sessions any one terminal can have. Either the terminal operator will have to close some sessions or increase the value of $KCML_TERM_LIC
Not licenced for this version of KCMLThe licence file does not contain an appropriate [KCML4], [KCML] or [KCML6] section.When upgrading the major KCML version, eg from KCML 5.20 to 6.00, you will also need to upgrade the licence file.
Shared memory system ID incorrectThe value of the $SYSTEMID environment variable does not match the value if the SYSTEMID tag in the licence fileMake sure $SYSTEMID is set to the correct value before kcml is executed.
SOAP session count exceededA SOAP server failed to start because there are no more [SOAP] licences left. Consult your Keyloop dealer for an increased number of [SOAP] users in your licence file
Maximum number of SOAP instances has been exceededAn attempt was made to start more SOAP servers than is allowed by $KCML_SOAP_LICIncrease the value of the $KCML_SOAP_LIC environment variable. You may also need to increase the number of [SOAP] users in the licence file

See also:

$LIC function
$SER function
$SYSTEMID & $KCML_TERM_LIC environment variables
Remote licence daemon
Using KCML in an ASP environment
ODBC licensing