Tutorial - JChain SA Minimal SDK Documentation

This page describes step-by-step instructions about everything on using JChain.

[Note] For quick evaluation of JChain, you may omit reading this tutorial and take the steps in "30min_quick_evaluation_steps.txt". This file should be in the same directory of the readme.txt.
(Request free evaluation, if you still don't have the latest version.)

Contents

Outline of Integration and Licensing with JChain
STEP I. Determining Options
STEP II. Getting a Licensor Key
STEP III. Embedding JChain in Your Product
STEP IV. Configuring JChain
STEP V. Releasing Your Product
STEP VI. Managing End-User Licenses
STEP VII. Managing Your Licensor Key
How to Use Key Updater
How to Use Logs
Aliases for Linux/Unix/Mac

Outline of Integration and Licensing with JChain

STEP I. Determining Options
(Evaluation users may skip this step) Tell us how you want your JChain. You have several options to customize JChain. You'll receive a license key for the copy of either standard or customized JChain.
STEP II. Getting a Licensor Key
(Evaluation users may skip this step. The evaluation version already contains a dummy licensor key.) You will receive a licensor key with your copy of JChain. Once you receive your licensor key, let JChain import the key by following a wizard.
STEP III. Embedding JChain in Your Product (Integration with JChain)
Put necessary JChain files/folders into your product. Add some lines in your source code and use functionalities of JChain.
STEP IV. Configuring JChain
Configure the properties of JChain, through editing some property files.
STEP V. Releasing Your Product
Now that the integration is done, you can release your product which is protected by JChain.
STEP VI. Managing End-User Licenses
Get request files from customers. The request files are generated by the wizard for end-users. Generate license keys based on those request files (key generator). Send the keys back to your customers. Let your customers import the keys using the wizard for end-users. * JChain Web can fully automatize this step using http connection with a license server.
STEP VII. Managing Your Licensor Key
What to do to keep using JChain.
END

STEP I. Determining Options

You have several options to strengthen your protection. Obfuscation makes it hard to analyze your software. Bytecode encryption and tamper proofing make it tougher against cracking. You can use either our tool "Java Code Protector" or our services.
END

STEP II. Getting a Licensor Key

Step 1. Run an evaluation version of JChain
Download an evaluation version of JChain (see the "Order" page). Install the evaluation version. See "STEP IV. Configuring JChain" for how to install JChain.
Step 2. Run the wizard for licensor key management
Use a shell or DOS window, and change directory to the "licensor_tools" under the installation directory. The default name of the installation directory is "JChainSA_m_1.6". Start a JChain licensor by executing a script file, and a menu will appear (screen shot). Linux/Unix/Mac: "cklicensor.sh" Windows: "cklicensor.bat" Enter 1, and the wizard for licensor key management will appear(screen shot). Press "Next". Choose "request another licensor key..." and press "Next"(screen shot). Select the license type you wish and press "Next" (screen shot). Enter your registration data (screen shot) Please fill it out carefully with accurate information. The registration information will not be disclosed to any third party. The following fields will be especially important for you (see the screen shots below): Product name and vendor name of the software to be protected : The product name and corporate name you entered will be displayed, while your customer run your software. Only one product can be protected with a licensor key of SA Minimal edition. The screen shot below shows an example (product name = "Sample App ABC 2", vendor name = "Sample Comapany ABC, Inc."). Unit price of your product: You may enter 1 to avoid providing this information. The price may be either actual or planned, exact or rough. Annual sales of your product: The value can be either actual or expected, exact or rough. It is the unit price times the number of license keys you can issue with this license of JChain. If the keys run short, you can order more licensor keys (and it's cheap). Afer filling out all the required fields, press "Next". A file will be generated ("request file" for a licensor key), and the path of the file will be displayed (screen shot). It may be convinient to copy the path to use in the next "Step 3". Press "Next" and then "Finish" to close the wizard.
Step 3. Send the request file to us
Send us the request file generated in the previous Step 2: sales@chainkey.com (It may be convinient to paste the copied path, when specifying an attachment.)
Step 4. Take in the licensor key we send
Start the wizard of JChain (i.e. Execute the cklicensor.sh/bat and enter "1" at the menu). Choose "Take in a licensor key" from the main menu of the wizard. Specify the licensor key file you get from us, ChainKey, and press "OK". Wait for a while, until the wizard tell you that the key is taken in.
END

STEP III. Embedding JChain in Your Product (Integration with JChain)

Step 1. Put necessary JChain resources into your product
Put "licensee_module" in your product The "JChainSA_m_1.6" directory contains a directory named "licensee_module". Copy the entire "licensee_module" directory into any directory of your product. The destination directory, where you put "licensor_module", is often referred to as "ChainKey root" (or "JChain in your product" as opposed to "JChain for the licensor" in the licensor's computer). [Note] the ChainKey root must be kept uncompressed (i.e. not in a jar file) in end-user's environment. This is because the files such as license keys must be stored and updated in the ChainKey root directory. Make sure the ChainKey root and jc.jar in it are in the classpath, both in your development environment and in your customers' (or end users') environment.
Step 2. Let your software call the primary methods of JChain
Licensee class provides the facade API of the JChain module embeded in your product. The primary methods of JChain are the minimal set of methods required to license/protect your product: Licensee() constructs an instance of the Licensee class. getLicenseStatus() checks the status of current end-user's computer. prompt() starts a wizard for current end-user to manage their license (e.g. checking the status of current key, requesting a license key, taking in a license key, or learning how to order a license key.) Here is a sample source code which shows you a simplest way to use JChain: SimplestProduct.java For lease/trial licensing , you may want to check the expiration date while your software is running. To do this, just create a new instance of Licensee and call the getRemainingDays() method. Insert lines of code which controls your program depending on the remaining days. [Notes] Your source code can be protected against cracking: ChainKey's another product "Java Code Protector" can make your program obfuscated, encrypted, and tamper-resistant. Exactly speaking, the prompt() method and graphical environments are not necessary to use JChain. The prompt() method can be replaced by your own method. To learn how to do so, Step 3 will give you some hints.
Step 3. Fine tune JChain
All the methods of Licensee class except the primary methods can be referred to as the secondary methods. They serve for finer control over license management and copy protection. The following samples are examples of such fine tuning: SimpleProduct.java: this sample shows you, among others, how to avoid using the default GUI provided by JChain. SimpleModularProduct.java: this is an example of modular licensing (each feature in the program has separate license status). Beyond the use of the seconday methods, you can also use your own license parameters and complement the functionalities of JChain. To do so: Edit "jchain_custom.properties" before issueing license keys, to set parameters in the keys Use "getCustomParameters()" method to use parameters set in the keys.
END

STEP IV. Configuring JChain

To install an evaluation version, all you need is to:

extract the archive of JChain
make sure that your cryptographic library (e.g. sunjce_provider.jar, bcprov-jdk1x-xxx.jar, ...) is in the classpath (see Requirements)
make sure that the J2EE library (namely, j2ee.jar) is in the classpath (see Requirements)
take the Step 1-4 of this section (just to set some environmental parameters).

Also, to use script files (.sh/.bat) provided by JChain, edit the paths in those files in advance (e.g. the path of the cryptographic library in your environment).

The rest of this section describes the configuration of JChain through property files.

Step 1. Edit jchain_licensor_env.properties
A file named "jchain_licensor_env.properties" is located in the "licensor_tools" directory. Edit this file and configure JChain for your environment. For details, see the descriptions in the property file itself.
Step 2. Edit jchain_licensor.properties
A file named "jchain_licensor.properties" is located in the "licensor_tools" directory. Edit this file and configure basic properties of the license management of your product. For details, see the descriptions in the property file itself.
Step 3. Edit jchain_licensee_policy.properties
A file named "jchain_licensee_policy.properties" is located in the "licensor_tools" directory. With this file, configure properties including: contact information for your customers (end-users) policies for checking end-users' computers license types avaialble for your customers mandatory and optional items for user registration. To make the modification effective, restart the JChain licensor. For details, see the descriptions in the property file itself.
Step 4. Edit jchain_local.properties
A file named "jchain_local.properties" is located both in the "licensor_tools" and "licensee_module" directories. This file must be configured for each computer on which JChain runs. With this file, configure the local properties including the messages, language, and cryptographic library to be used. If you use proxy and/or authentication for using internet, edit the following entries in this property file: network.username network.password proxy.host proxy.port For example, network.username=kenta network.password=H29Fds proxy.host=proxy.mydomain.com proxy.port=8080 For further details, see the descriptions in the property file itself.
Step 5. Edit jchain_custom.properties
A file named "jchain_custom.properties" is located in the "licensor_tools" directory. Edit this file just before using the JChain Key Generator, and you can put your own license parameters in the generated license keys. On end-users' side, JChain can extract those parameters using the getCustomParameters() method.
Step 6. Edit/Create jchain_messages_xx.properties
English is the default language for JChain GUI. If no message properies are found, JChain uses the default English messages built-in the source code. To customize an English message, edit the corresponding entry in the jchain_messages_en.properties. [How to use another language] If you want to use another language for your customers, create a new message file and edit the jchain_local.properties (see Step 3): Copy a jchain_messages_en.properties to jchain_messages_xx.txt. Use any appropriate suffix . (e.g. "de" for German, "fr" for French, "cn" for Chinese ...) Edit the values in jchain_messages_xx.txt with the new language. Execute the following command to get the message property file: native2ascii jchain_messages_xx.txt jchain_messages_xx.properties copy "jchain_messages_xx.properties" into the "licensee_module" directory in your product. edit the value of "enduser.locale" in the "jchain_local.properties" and put in (e.g. "de" for German) Here's a screen shot of a wizard with Japanese messages.
Step 7. 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 (screen shot). Please edit this file and replace the image with your own logo. The image size must be less than 200x150.
END

STEP V. Releasing Your Product

Setting up the environment
Make sure that the ChainKey root ("licensee_moduel") and jc.jar in the product will be in the classpath, when your customer uses your product.
Compiling your program
Compile your program that now contains JChain "licensee_module". As mentioned already, don't make the "licensee_module" compressed in end users' environment. Also, don't put jc.jar in another jar file in end users' environment, since it might confuse JChain.
Testing/adjusting JChain before releasing
For simple and quick testing, follow the steps in "30min_quick_evaluation_steps.txt" in the "JChainSA_m_1.6" directory. You can also test how licensing parameters work on a variety of computers, using the simple tool, cklicensee.sh/.bat. To examine the details of JChain's behavior, check out the "chainkey.log" (see "How to Use 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 information 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. See API for more.) 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. Here's a few suggestions for testing: Try a normal procedure from the beginning to the end Modify a valid key file and run cklicensee.sh/.bat Copy your product with a valid key to another (unauthorized) computer and run cklicensee.sh/.bat Modify the file system and run cklicensee.sh/.bat to see how the difference in profile increases.
Whether to provide a trial version
You can make your product available either as a trial version or a commercial version. If your customers can use a trial version, they can request a key for the commercial version using the wizard of the trial version. If your customers can't use any trial versions, they will have to request a key using the wizard of the commercial version, after they purchase the product.
Generate and put in Lock.class and Chain.ini
1) Run cklicensor.sh/.bat in the "JChainSA_m_1.6/licensor_tools/" directory. A CLI menu will appear. 2) Enter 2 ("Prepare a policy file for my product"), and a file named "Lock.class" will be generated. This file contains the information on your licensing policy determined by jchain_licensee_policy.properties. 3) Enter 3 ("Prepare a dummy key for my product"), and a file named "Chain.ini" will be generated. This is a kind of trial license key. JChain needs it, irrespective of providing a trial version or not. 4) Those 2 files (Lock.class and Chain.ini) are saved in the "licensor_tools" directory. Copy them into the "licensee_module" directory of your product.
END

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, or lease extension.

Note: We assume the graphical wizard provided by JChain in the following, but it's not necessary
as described earlier (see Step 3. of "STEP III. Embedding JChain in Your Product").

Step 1. Get request files from your customers.
1) Your product calls the prompt method. The license management wizard will start (screen shot). 2) The status of end-user's license will be shown (screen shot). 3) Let the end-user select "Request a key", "Request another key", or "Request reissue/lease extension of the current key" depending on what he/she wants. (screen shot). 4) When requesting a new key, the end-user will be asked to select the license type to request (screen shot). You can specify the available license types using a property file (See Step 1 of "STEP IV. Configuring JChain"). 5) If user-registration is required, the end-user will be asked to fill out a form (screen shot). Otherwise, this page will not be shown. You can specify the necessity of user registration by a property file (See Step 1 of "STEP IV. Configuring JChain"). 6) Then, JChain will generate a "request file" (for license key) using the profile of the end-user's computer (screen shot) 7) The end-user will be asked to send the request file to you (screen shot). You can specify the contact e-mail address by a property file (See Step 1 of "STEP IV. Configuring JChain"). Also, if requesting the reissue or lease extension, he/she will be asked to send the current key file to you (the path of the file will be shown as in the screen shot). 8) You'll receive an e-mail from the end-user with the file(s) attached.
Step 2. Generate license keys based on those profiles (key generator).
Save the received request files in the directory that is specified as "profile.directory" in the jchain_licensor.properties. This step is not necessary, but will make it easier for you to handle requests. Because this is the default directory JChain searches for request files. Run cklicensor.sh/.bat. A CLI menu will appear. Enter 4 to launch the key generator (screen shot). To issue a new key Select a request file to process. Then, the details of the requested license and user registration data will be shown in the central text area (screen shot). Confirm the request and press the button at the bottom. To reissue, extend lease (subscription), or modify a license key Select a request file to process, and the user's current key file (the wizard for end-users asks your customers to send both). Then, the details of requested service, user ID data, and user's current license will be shown in the central text area (screen shot). Confirm the request and press the button at the bottom. All generated key will be stored in the "key.directory" specified in the jchain_licensor.properties. The path of the key file will be shown at the bottom of the dialog (screen shot). Also, all key generation will be recorded in chainkey_transactionXXXX.log (For details, see "How to Use Logs"). It is recommended to back up the issued key, in case your customers either lose or damage the key and ask you to reissue the key. [Note] 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 ChainKey root will be the default of both the profile directory and the key directory, unless you specify them in the jchain_licensor.properties.
Step 3. Send the keys back to your customers.
Reply to your customers' e-mail with the generated keys attached, asking them to "take in" the key using the wizard.
Step 4. Let your customers take in the keys (license management wizard).
1) The end-user saves the received key file to somewhere in a hard disk. 2) Call the prompt method in your product. The license management wizard will start. 3) The status of end-user's license will be shown (screen shot). 3) Let the end-user select "Take in a key" (screen shot). 4) Then a file chooser dialog will be shown. The end-user specifies the key file which is sent from you. 5) JChain will try to take in the file and authorize the end-user (screen shot). 6) The result of "take-in" attempt will be shown. The current license status will be shown on the same page (screen shot). The user can check out the details of modular licensing by choosing "Check out current license status" from the Main Menu (screen shot).
END

STEP VII. Managing Your Licensor Key

If you need to use the JChain licensor on more computers (multiple computers), or if you run out the number of keys you can issue (or "issualb e keys") with your license, please ask us for more license. See "Purchasing JChain" and "STEP II. Getting a Licensor Key" for more. For re-issue and lease extensions of your licensor key, send us your current licensor key along with the request file generated using the wizard ("STEP II. Getting a Licensor Key"). By re-issue or lease extension, you can not change the vendor name and product name you registered. Those names will be displayed to end-users (screen shot). To change them, please ask us for the modification of your license.
END

How to Use Key Updater

JChain comes with a daemon called "key updater", which constantly checks changes in the computer profile and adaptively updates license keys. In the event the update fails, though which should be quite rare, users of JChain can easily request re-issue of their license keys, and vendors can easily re-issue license keys.

While your software is running
You don't have to do anything while a protected software is running, since JChain automatically starts a key updater after authorization. Even if your application discards the reference to the used Licensee 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 the Web edition users can let licensor server do this automatically), that's all right, too. The probability of such reissue under ordinary circumstances should be quite low (A model is discussed in a white paper. ). 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.sa.licensee.Licensee "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.sa.licensee.Licensee "startupdater" 1.0 23.5 2) To update the key just once and quit java com.chainkey.jchain.sa.licensee.Licensee "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 to work properly. Do not run another key updater when a key updater is already running on the same computer. The key updates are logged in the "chainkey.log". If you're using cron daemon, you'll receive reports by mail (see Appendix B for further information).
Maintanance of licensor keys
Basically the same as the license keys goes for the licensor/developer keys (see the previous section). To use the daemon, register the following command to the scheduled task of your computer: java com.chainkey.jchain.sa.licensor.LicenseManager "startupdater" arg1 arg2 The only difference is to use the "...licensor.LicenseManager" class, not the "...licensee.Licensee" class. The arguments and usage are the same as that for the licensee (see the previous section.) This is what's inside the batch file "licensorkey_updater.bat" in the ChainKey root directory. See Appendix B. for the procedure to register the licensor Key Updater. It usually takes about 5 minutes to complete. Note: With the evaluation version of JChain, you can't use the key updaer for licensor keys, and there's no need to do so. The evaluation version of JChain contains a dummy licensor key which doesn't examine licensors' computer profiles. See Notes in the previous section.
END

How to Use Logs

JChain puts out 3 kinds of logs in the ChainKey root directory:

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 kind of log 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.6\key_Fri_Oct_04_ 08-56-18_MDT_2002
END

Aliases for Linux/Unix/Mac

Aliases for licensors
It might be convinient to set some aliases in your environment. Here's a few examples: Sample .bashrc entries # The path of the cryptographic library to use export CRYPTO=$HOME/bouncycastle/bcprov-jdk14-123.jar export CLASSPATH=$HOME/JChainSA_m_1.6:$CRYPTO:$CLASSPATH alias cklicensee='java com.chainkey.jchain.sa.licensee.Licensee promptonly' alias cklicensor='java com.chainkey.jchain.sa.licensor.LicenseManager showmenu' alias updatekey='java com.chainkey.jchain.sa.licensor.LicenseManager "startupdater" 2.0 23.0' Sample .cshrc entries # The path of the cryptographic library to use setenv CRYPTO $HOME/bouncycastle/bcprov-jdk14-123.jar setenv CLASSPATH $HOME/JChainSA_m_1.6:$CRYPTO:$CLASSPATH alias ckicensee "java com.chainkey.jchain.sa.licensee.Licensee promptonly" alias cklicensor "java com.chainkey.jchain.sa.licensor.LicenseManager showmenu" alias updatekey "java com.chainkey.jchain.sa.licensor.LicenseManager startupdater 2.0 23.0"
END