Tutorial


This page describes how to set up and use JChain for evaluation/commercial purpose. (Request free evaluation of JChain now, if you don't have one.)

Basics Integration and License Management Notes








Outline of Copy Protection & Licensing with JChain


  This section describes the outline of procedural flow of integration and license management.

STEP I. Determining Options

Evaluation users: skip this step.

Commercial users: you have several options to customize JChain (see "Order" page for details). If you're determined, place an order to us. You'll receive your own copy of JChain.

STEP II. Getting Your Licensor Key

Evaluation users: skip this step.

Commercial users: request your licensor key, using the JChain management panel. Once you receive your licensor key from us, ChainKey, take it into your JChain using the management panel.

STEP III. Embedding JChain in Your Product

Evaluation users: if you use the sample product that comes with JChain, you can skip this step.

Commercial users: put necessary JChain files/folders into your product. Add some lines into your source code to embed JChain There's a sample source code in "sample/src/".

STEP IV. Configuring JChain

Use the management panel and configure the licensing/copy protection properties by editing the property files of JChain.

STEP V. Releasing Your Product

Release your product protected by JChain.

STEP VI. Managing End-User Licenses

1) Get request files from customers. The request files are generated by the wizard for end-users.
2) Generate license keys for those request files.
3) Send the keys back to your customers.
4) Let your customers take in the keys using the wizard for end-users.

* Now, JChain Web can fully automatize these 4 steps using the http connection with your licensing server.

STEP VII. Managing Your Licensor Key

If your licensor key has an expiration date or limited number of issuable license keys, you'll need to update your licensor key, in order to keep using JChain.













Setting up JChain Licensor Server (1 - 4 hours)


  This section describes how to set up your server of JChain. This is necessary for both evaluation and commercial users.

STEP I. Deployment of JChain web application

(Sub-step 1) Extract the Archive

Extract the "jc150w.jar".
For quick evaluation, move the decompressed "JChainWeb_1.5" directory under C:\ (Windows OS) or $HOME/ (Linux/Unix OS). In the following, we assume "C:\JChainWeb_1.5", and use relative path from this folder. If you want to set up JChain in a different directory, please edit paths in the property files as described later.


(Sub-step 2) Determine Web App Name

Prepare a web server and a web app folder for JChain. We assume our web app name, which is also a folder name, "tjcw150" in the following. If you use another name or defaultroot, you'll need to edit paths in the property files.


(Sub-step 3) Set up JSP files

Copy the folder "licensor_tools\web\defaultroot\jchain" to the folder "tjcw150".


(Sub-step 4) Set up Libraries

Copy "jc.jar", "jcweb.jar" and "fileupload.jar" in "licensor_tools\web\defaultroot\Web-inf\lib" to the web app. Typically, into tjcw150\WEB-INF\lib.


(Sub-step 5) Set up "Properties directory"

Copy all files in "JChainWeb_1.5\licensor_tools\web\initial property files" to somewhere in the classpath of your servlet runner. Typically, into tjcw150\WEB-INF\classes.
This place (or directory) will be referred to as the "properties directory".


(Sub-step 6) Edit "jchain_management.properties"

Set the absolute path of the above "properties directory" in the property file named "jchain_management.properties". This file is in the "properties directory. For example,

   properties.directory=C://tjcw150/WEB-INF/classes/

Also, specify the web app name in this file. For example:

   servlet.base=http://localhost:8080/tjcw150/

Then, copy this file into the directory "licensor_tools". You may overwrite the existing file.


(Sub-step 7) Edit "jchain_licensor_env.properties"

Edit the following properties in the file "jchain_licensor_env.properties" in the "properties directory. If your JChainWeb_1.5 folder is directly under the root directory of the C drive, there's no need to edit them.

   chainkey.root=C:/JChainWeb_1.5/licensor_tools/
   (The absolute path of "licensor_tools" folder )

   authorizationDb.directory=C:/JChainWeb_1.5/licensor_tools/autho/
   (The absolute path of the folder where "licensorKey" file is to be stored )

Then, copy this file into the directory "licensor_tools". You may overwrite the existing file.


(Sub-step 8) Edit web.xml

Edit your deployment descriptor, and add all entries in
JChainWeb_1.5\licensor_tools\web\web_xml_entries.txt. If you have no entries in the existing web.xml, just use the file "licensor_tools\web\defaultroot\Web-inf\web.xml" without modification.


(Sub-step 9) Login the Management Panel

Now the server is basically set up. Start the web app, and access the management panel (JMP or JChain Management Panel):

   http://localhost:8080/tjcw150/jchain/mgmt/index.html
   or
   http:///tjcw150/jchain/mgmt/index.html

JavaScript of your browser must be enabled.
Now, use the default account to login the JChain Management Panel (JMP):

   username:admin
   password:admin


Then, you can follow the web pages and try JMP. There's a list of tasks in the left frame of the management panel ([MENU]). Basically, you can perform integration and license management by doing those tasks one by one from the top to the bottom. For evaluation purpose, skip task B2 and B3, and proceed to the "Integration".




STEP II. Preparing Accounts for Database and SMTP servers

1. User Database

JChain Web edition uses a database for the license management. The database stores data on copies and users of your products. It is reffered to as the "user database".


(Sub-step 1) Please prepare a database that JChain can use. Create a database named "jc_db" for quick evaluation. We assume the database name "jc_db" in the following. Prepare an account for JChain with all priviledges for the "jc_db".


(Sub-step 2) Update properties using JMP:

[MENU] > I1 > 1. Licensor Server Environment > 3. Your User Database

Make sure that the web app can find the designated JDBC driver. (Put the library somewhere in the classpath the web app use.)





2. SMTP server

JChain licensor server automatically notifies operators/customer support, of the arrival of unprocessed requests from your customers. Set up an account for SMTP server and register those operator's e-mail addresses with the management panel.


(Sub-step 1) Prepare a SMTP server and e-mail acccount that JChain can use.


(Sub-step 2) Update properties using JMP:

[MENU] > I1 > 1. Licensor Server Environment > 4. Automatized E-mail

Here, you can also add e-mail addresses of operators for automatic notification. Please enter your own, for quick evaluation.


STEP III. Confirming JSP for end-users

It is recommended to use the end-user wizard of JChain for the license management on end-users' side, since it is well automated. If your end-users can't use the wizard for some reason, the JSP for end-users is the alternative way. All license key requests made by using this JSP will be stored in the request queue of the server, and operators will be notified of the new request by e-mail.

Here, confirm that the JSP for end-users are working. Just access the following site to start using the JSP pages, and look around. The pages are self explanatory.

   http://localhost:8080/tjcw150/jchain/odpgs/demo.html
   or
   http://(your web server)/tjcw150/jchain/odpgs/demo.html



(A sample screen shot of the JSP for end-users)


You may freely modify and use files under jchain/odpgs. At least, you must edit demo.html and jc_menu.jsp and adjust "pnum" parameters in those files so that it matches to the product number you wish to use those jsp for.












STEP I. Determining Options


 

You have several options to strengthen your protection. Obfuscation makes it hard to analyze your software, but it doesn't prevent advanced reverse engineering effectively. You'll need to get your software encrypted and tamper resistant, in order to make it tough against cracking attempts.

For further information, please visit our web site.













STEP II. Getting a Licensor Key


 

Step 1. Request a licensor key using the management panel (JMP)

To request a licensor key (i.e. a license key for licensor to use JChain), click the following link in the menu of JMP, and just follow the wizard:

   [MENU] > B2. Request a licensor key




When entering your registration data, please fill it out carefully with accurate information.
(The registration information will not be disclosed to any third party.)
The following 2 fields will be especially important for you, because they will be displayed, while your customer run your software (as shown in the screen shot).
  • The name of the software to be protected with JChain
  • Your corporate/personal name as a software vendor





Step 2. Take in the licensor key you get

To take in (or import) a licensor key, click the following link in the menu of JMP, and specify the path of the key file. Then, wait for a while, until the wizard tell you that it successfully took in the licensor key:

   [MENU] > B3. Take in a licensor key


















STEP III. Embedding JChain in Your Product (Integration)


 

[Note] You can skip this section, if you're going to evaluate JChain by using a sample product which is protected with JChain. The sample can be found in the "sample" folder of the archive. Its source code is in the "sample\src" directory. Please read the readme.txt in the directory first, to use the sample.


(Sub-step 1) Follow the management panel (I1, I2, J1, J2) for integrating JChain with your products.


(Sub-step 2) Utilize the API and a sample source code (sample\src\SimpleProduct.java) for embedding JChain in your Java applications.

[Tips]
  • You can also use your own license parameters to complement the licensing with JChain
  • You can configure colors of the end-user wizard by a property file
  • You can do i18n/localization of the wizard
  • You can avoid using the wizard of JChain, and use your own instead

(Sub-step 3) Make sure that the "licensor_tools" directory, jc.jar, and "licensor_tools/templates" directory are all in the classpath of your development environment. Compile your modified application.


(Sub-step 4) Copy all files, except property files, in the "licensee_module" directory to the ChainKey root directory in your application. Make sure the ChainKey root is in the classpath in end-users' run-time environment.

( The ChainKey root directory must be uncompressed (i.e. not in a jar file) in end-user's environment, because the files such as license key must be stored and updated in the directory. For more on the ChainKey root directory, please checkout the following property:
[MENU] > I1 > 3.Products Management > End user local environment > Key: chainkey.root)


(Sub-step 5) Copy all files of the corresponding app folder of JChain (Use licensor_tools\app_2 for evaluation), into the ChainKey root directory in your application. Make sure the ChainKey root and jc.jar in it are both in the classpath in your customers' run-time environment. Your installer is supposed to do this job.


(Sub-step 6) Remove suffix _2 (or _N in general, where N is the product #) from all the property files in the ChainKey root of your application.

Now, the integration is complete.

[Warning] If the following property is set wrong, end-users can not connect to the licensor server. If you're using the default settings for quick evaluation, there's no need to edit this property.

  [MENU] I1 > 3.Products Management > End user local environment > Key: licensor.server.codebase















STEP IV. Configuring JChain


 

Step 1. Edit jchain_licensee_policy.properties

Parameters of the licensor server, license parameters for each products, and even license parameters for each license key can be configured by editing the property files. To edit the property files of JChain, click the following link in the menu of JMP, and follow the instructions on the page:

   [MENU] > I1. Edit properties


Category of those parameters include, but not limited to:
  • contact information for end-users
  • policy for checking end-users' computers
  • available license types
  • some default license conditions
  • how expiration reminder works
  • properties on the messages and language to be used
For the complete list and further details, see the descriptions in the management panel.


Step 2. Edit/Create jchain_messages_xx.properties
The default language of JChain is English. If no message properies are found, JChain uses the default English messages built-in the source codes.

To customize an English message, enter the corresponding entry in the jchain_messages_en.properties.

JChain comes with a Japanese standard message file jchain_messages_jp.properties. To use this file, edit the value of "enduser.locale" in the jchain_local.properties and put in "jp". Here's a screen shot of a wizard with Japanese messages.

[How to use another language]
If you have to create message for another language, create a new message file and edit the jchain_local.properties (see Step 3). To create a new message file, follow the next steps:

  1. Copy a jchain_messages_en.properties to jchain_messages_xx_native.properties. Use any appropriate suffix in the part of "xx". (e.g. fr, de, cn ...)

  2. Edit the values in jchain_messages__native.properties with the new language.

  3. Execute the following command to get the message property file:

    native2ascii jchain_messages__native.properties jchain_messages_xx.properties

  4. put the file "jchain_messages_xx.properties" in the ChainKey root directory in your product.


Step 3. Edit logo.gif
In standard JChain, a file named "logo.gif" is located in the following directory:
[ChainKey root]/com/chainkey/images/

This is your company logo displayed by the wizard for end-users. Please edit this file and replace the image with your own logo. The image size must be less than 200x150.

STEP V. Releasing Your Product


 

Ensuring the correct paths
As already mentioned, make sure that the jchain_local.properties will be adjusted to the end-user's computer at the installation of your product. Your installer will have to edit the ChainKey root specified in the "jchain_loca.properties". Also make sure that the ChainKey root and jc.jar in the product is in the classpath.

Testing/adjusting JChain before releasing
To examine the details of JChain's behavior, check out the "chainkey.log" (see "Logs"). For example, you can see the result of authorization and the percentage of the difference between the current computer-profile and the profile stored in the current key. Utilize this for adjusting the properties such as "allowance" in "jchain_licensee_policy.properties" ("allowance" specifies the maximum difference in profile, for JChain to identify a computer as itself.)

A sample log entry


2002/10/5,16:17:38.390, origin ID = 1041,
	[Summary]	Info: Difference calculated
	[Details]	Difference in profile = 0.03 percent.


Some common scenarios to be tested include:
  • Try a normal procedure from the beginning to the end
  • Modify a valid key file and run cklicensee.bat
  • Copy your product with a valid key to another (unauthorized) computer and run cklicensee.bat.
  • Modify the file system and run cklicensee.bat to see how the difference in profile increases.














STEP VI. Managing End-User Licenses


  A standard procedure of managing license keys is described in the following. Basically, all you and your
customer have to do is to follow their wizards for issue, reissue, lease extension, or license modifications.

Note: We assume the graphical wizard provided by JChain in the following, though it's not necessary.

Step 1. Get request files from your customers

Your customers can request a license key either by using the wizard for end-users or by using the JSP for end-users as described in the above. If your licensor server can not automatically permit issue/reissue of requested license key, the request is added to the "request queue" and all operators are notified of it by e-mail. The licensor server stores the request data in the "licensor_tools/profiles" directory ("request files).


Step 2. Generate license keys based on those profiles (key generator).

  [MENU] > O1. in the management panel shows you the queue of the unprocessed request from your customers. Select a request from the list, if any, and determine if you accep or reject it. By accepting a request, a license key for the request will be generated, and the request files are moved to "licensor_tools/profiles/accepted" folder. By rejecting a request, those files are moved to "icensor_tools/profiles/rejected" folder.


* The generated key file can be matched to the corresponding request file by its suffix. For example, 
    key_Wed_Sep_11_16-56-44_MDT_2002 and
request_Wed_Sep_11_16-56-44_MDT_2002


Step 3. Send the keys back to your customers. And your customers can take in those keys using the wizard.

Reply to your customers' e-mail with the generated keys attached, asking them to "take in" the key using the wizard.













STEP VII. Managing Your Licensor Key


 

If your licensor key has an expiration date or limited number of issuable keys, you'll need to renew/update/modify your licensor key, to use JChain beyond the date or limitation. Check out "Purchasing JChain" and "STEP II. Getting a Licensor Key", for how to request a licensor key.

Note:
* Please remember that re-issue of a licensor key is not free (see "Purchasing JChain").
* By re-issue or lease extension, you can not change the vendor name and product name which is registered to us and will be displayed to end-users (screen shot). Please explicitly request the modification of registration date, when ordering.

What's Key Updater


 

Key Updater

Updating a key is necessary for keeping the key valid, while the computer profile keeps changing. The daemon called "key updater" does this job.

While your software is running

JChain automatically starts a key updater after authorization. Even if your application discards the reference to the used CkLicensee object, the updater will keep working as a separate thread while your software (or JVM) is running.

You can customize the time interval of updating keys, by calling the setInterval method. It is important to set the interval short enough, if you adopt a severe policy for checking the computer profiles (see "allowance" in the jchain_licensee_policy.properties)

For finer control over the key updater, you can stop/re-start the thread by calling stopKeyUpdateDaemon()/startKeyUpdateDaemon() respectively. To protect a long-running program such as servers, it is important not to forget restarting the key updater after you manually stop it.

While your software is not running

The computer profiles will keep changing, while your software is not running. If your customers use your software daily basis (or perhaps even weekly basis), their keys will keep being valid because of the key updater JChain automatically starts. Or if you are ready to reissue license keys for your customers for free (and you can let licensor server do this automatically), that's all right, too. Otherwise, it is recommended for end-users to use the key updater as a scheduled task.

Appendix B. describes the details of the procedure for Windows and Linux/Unix users. Here's how to call the key updater from the command line:

java com.chainkey.jchain.CkLicensee "startupdater" arg1 arg2

where
arg1 is the interval of updates (in hour, and in the double format)
arg2 is the duration of the updater (in hour, and in the double format)

Examples:

  1) To update the key every hour and quit after 24 updates (incuding the 1st update immediately after the updater starts)
   java com.chainkey.jchain.CkLicensee "startupdater" 1.0 23.5

  2) To update the key just once and quit
   java com.chainkey.jchain.CkLicensee "startupdater" 1.0 0.1

This is what's inside the tool named "keyupdater.bat" in the ChainKey root directory. For Windows end-users, you can edit this file before the release of your product, and register it to end-user's task scheduler to perform it once a day. Appendix B is prepared for you to use in your documentation, so that your customers can set up the key updater by themselves. Average users could finish it in about 5 minutes, and the task scheduler (or crond) will take care of the license key thereafter. See the "Appendix" page for more information.

Note:
* The ChainKey root directory must be in the classpath for the keyupdater.bat to work properly on Windows platform.
* The key updates are logged in the "chainkey.log". Check it out to make sure that the key is updated as specified. If you're using cron daemon, you'll receive report on the updates by mail (see Appendix B for further information).

Keeping licensor key valid
Licensor keys also need updates. But you don't have to worry about this, while your licensor server is up running. Otherwise, please register the following command to the scheduled task of your computer:

java com.chainkey.jchain.licensor.CkLicensor "startupdater" arg1 arg2

where
arg1 is the interval of updates (in hour, and in the double format)
arg2 is the duration of the updater (in hour, and in the double format)

Examples:

  1) To update the key just once and quit
   java com.chainkey.jchain.licensor.CkLicensor "startupdater" 1.0 0.1

  2) To update the key every 2 hours and quit after 12 updates (incuding the 1st update immediately after the updater starts)
   java com.chainkey.jchain.sa.licensor.CkLicensor "startupdater" 2.0 23.0

This is what's inside the tool named "licensorkey_updater.bat" in the ChainKey root directory. If you use the licensor functions of JChain on Windows OS, you can edit this file and register it to your task scheduler. Note that the ChainKey root directory must be in the classpath for the batch file to work properly.

See Appendix B. for the procedure to register "licensor-key updater". The procedure will take about 5 minutes to complete. The appendix is both for Windows users and Linux/Unix users.

Note:
* There's no need to update the licensor key for the free evaluation. The evaluation version of JChain contains a dummy licensor key which doesn't examine licensors' computer profiles. Don't try to update the dummy licensor key using the updater.
* The key updates are logged in the "chainkey.log". Check it out to make sure that the key is updated as specified. If you're using cron daemon, you'll receive report on the updates by mail (see Appendix B for further information).















Logs


 
The JChain management panel writes 2 log files: "jchain_mgmt.log" and "jchain__mgmt_errors.log" which you can check using the management panel itself.

The JSP for the end-users also writes 2 log files: "jsp_jchain.log" and "jsp_jchain__errors.log".

In addition, JChain core library writes 3 kinds of logs:
  • General log ("chainkey.log"): all log entries will be recorded into this file.
  • Error log ("chainkey_error.log"): for error messages only.
  • Transaction log ("chainkey_transactionXXXX.log"): for recording transactions such as key generation.
Each of those 3 kinds of log files is described in the following:



General log ("chainkey.log")

The purpose of this file is to store all the recent log entries. The size of this file may grow rapidly, but a limit of 1MB is set to its size. When the size of the file reaches the limit, the last 100KB of entries in the file is retained and the other older entries will be automatically deleted making the space of 900KB.

Use this log to analyze the entire flow of events.

Error log ("chainkey_error.log")

The purpose of this file is to store all the recent error log messages. The limit of 1MB is set to the size of the file just like "chainkey.log". When the size reaches the limit, the last 100KB of older entries in the file is retained and the other entries will be automatically deleted making the space of 900KB.

Use this log to detect and analyze errors. Some error log entries have their details encrypted against reverse engineering. Only ChainKey can decrypt them. Please send us the relevant log entries for trouble shooting.

The following is an example of an entry:

A sample log entry


2002/9/11,14:48:33.914, origin ID = 1057,
	[Summary]	Error: Failed to load a file
	[Details]	354566e03bd5a5e5280ce916dd7503d4776098fd441517a49be3a18e7d415c46
f174b8eb688ebd578d27a4fc334999fcfc4ab2b73b50c84d31d5794398bd7689cec3f1624029a30d
d0b69b3d8af129a055710483d1bbb5786492f74b526a882fd08d7fc0dd776084569b6f1484b23ff2
43a2a999e6ea7c04c653e63f4d22a15dfa12cdee7c29546a809f6c798abe9b1dccaa2e2e06ce7444
1bc25763206a11defdc54ae05aa9a7743f63040eb8b4ae6cd0fd92f776c9d5fb3dcbfeed1c363480
7a3892bf6f201ccda274d85ac24f81b7b536a2a8cfb57f862fad4e4006cd6ee9cecb5d87ab61589c
ae9fb406ccef63963fcbfeb7eec71bf45bc8e93eb8ad8f5df823539eee3768ec26a2e3288a949bbf
f649703e0a69c64d9a3ef43205998d6130b43a6544680337841e3550113ab5b1f366c1bd6e45e8bb
...

Transaction log ("chainkey_transactionXXXX.log")

The purpose of transaction log files is to store the records of all the transactions since the installation of JChain. Therefore, JChain creates another transaction log file, when the current log file reaches the maximum size (1MB).

The transaction log files starts from
"chainkey_transaction0001.log"
and the suffix is incremented each time a new file is created, until it reachesthe maximum of 9999:
"chainkey_transaction9999.log".

A log entry of key generation usually takes less than 1KB, so more than 1000 key generation could be logged in one transaction file.

Note:
Do not remove the current (i.e. last) transaction file from the ChainKey root, or JChain will create a transaction file with the same name.

The following are 2 sample log entries created by key generation. The first one shows CSV formated records of request/user information, and the second one shows that a key was generated for a customer (the path of the key file is shown as the second item of the details) :

Sample log entries


 2002/10/4,8:56:31.181, origin ID = 1217,
	[Summary]	Transaction: Request object read
	[Details]	Permanent,Mr.,John,Williams,S,Wonderful Business Ltd.,Senior Sof
tware Engineer,12345 Some town,,Some city,Some state,Some country,123-4567,123-4
56-7890,123-456-7890,john@wonderful,john@wonderful,xxxx,This is a sample field

2002/10/4,8:57:9.286, origin ID = 1226,
	[Summary]	Transaction: Key generated
	[Details]	for Mr. John Williams,C:\ChainKey\JChainSA_m_1.5.0\key_Fri_Oct_04_
08-56-18_MDT_2002














Batch Files


 

Complementary tools for licensors and end-users

The "licensee_module" and "licensor_tools" directories contain complementary batch files. As long as customers use the wizard of JChain only, there's no need to use those batch files in the "licensee_module". Also, as long as you use the JChain management panel only, there's no need to use those batch files in the "licensor_tools". They are prepared for exceptional cases where someone can't use those standard interface of JChain.

The batch files are for Windows, but Linux/Unix/Mac users can easily utilize them for their platforms.













User Database


 

JChain licensor server creates and maintains a user database. The management panel has tools to access and utilize the database.
  • To query and process record in the user database, use [MENU] > P1, P2, P3, or P4 of the panel.
  • For advanced operations, use [MENU] > Q1 of the panel.
For further details, please check out the manamgement panel itself.


(a sample screen shot)

Note for Linux/Unix Users


 

Aliases for licensors
Set the aliases in your (i.e. licensor's) environment for convinience. In the following example, alias "cklicensor" works just like the batch file named "cklicensor.bat" on Windows OS.

Sample .bashrc entries


export CLASSPATH=$HOME/JChainWeb_1.5/licensor_tools:$CLASSPATH

alias cklicensee='java com.chainkey.jchain.CkLicensee "promptonly" 2> chainkey_error.tmp'
alias cklicensor='java com.chainkey.jchain.CkLicensor 2> chainkey_error.tmp'
alias updatekey='java com.chainkey.jchain.CkLicensor "startupdater" 2.0 23.0'


Sample .cshrc entries


setenv CLASSPATH $HOME/JChainWeb_1.5/licensor_tools:$CLASSPATH

alias cklicensee "java com.chainkey.jchain.CkLicensee promptonly 2> chainkey_error.tmp"
alias cklicensor "java com.chainkey.jchain.CkLicensor 2> chainkey_error.tmp"
alias updatekey "java com.chainkey.jchain.CkLicensor startupdater 2.0 23.0"










© 2003 ChainKey, Inc. All rights reserved.