Users Manual

Java Code Protector v1.4.1

Multi-layer encryption, obfuscation, and tamper proofing
- Java developers' must have

PLEASE READ THE LICENSE AGREEMENT (license_agreement.htm) CAREFULLY BEFORE USING THE SOFTWARE.
BY USING THE SOFTWARE, YOU AGREE TO THE TERMS OF THE AGREEMENT.

Overview and features
Requirements
Definitions
Restrictions of the current version
Installation and uninstallation
Usage
For the first time only - preparation of a project directory
FAQ on this section
How do I import a license key?
How do I disable the wizard while evaluation?
How do I reflect updates in original source codes?
Invalid license key?
Can I reuse a project directory?

Protecting code
Using the Protector
Options

Using resultant archive
Managing multiple editions
Managing multiple projects
Samples
Release notes
Contact/Support
Acknowledgement

Overview and features

Java Code Protector ("Protector") is a tool to protect Java programs from reverse engineering and cracking. The Protector protects programs by making their source code obfuscated, their bytecode multi-layer-encrypted (see below), and their files tamper resistant. Each of these features are described in the following.

ChainKey, Inc. has provided services to protect customer's Java programs. Partly because of requests from users, we decided to make this service into an affordable tool, and that led us to the Protector. Our motivation is to provide more complete protection than what you would get from obfuscators only. When you think about the license management of Java applications you will realize that a program can be easily cracked if it's only obfuscated. That is because software pirates can decompile and replace crucial conditional statements. But what if your bytecode is also multi-layer encrypted and tamper-resistant? They couldn't find source codes unless they decrypted many encryption walls. Even if they decrypted all the encryption walls, they couldn't simply modify statements because tamper-detection "landmines" are embedded throughout the program. In short, cracking Java programs shouldn't be so easy, when they are protected by our unique technology. That is why we believe that the Protector is a must have for all Java vendors.
(Click here to visit our web site for more detailed explanation with figures)

Here's brief descriptions of the main 3 features:

Multi-layer encryption
All bytecodes of your program will be encrypted. Encrypted programs preserve the purity of Java (no native library is used for the encryption.) The strength of the protection depends on the number of encryption layers^*1. Software crackers would have to analyze the souce code of a layer to decrypt the next layer. So, decrypting all of those layers, one by one, would take a considerable amount of time. This is how multi-layered-encryption adds to the strength of protection. Adding many layers affect the performance in the build phase of your development, but it only adds a relatively small amount of overhead to the start-up of protected programs. (To see how smoothly protected programs work, ask us for sample programs.)

*1: A number of encrypted ClassLoaders work as layers or walls of protection. One of our original technologies.
(See also -layers option)
Tamper proofing
The integrity of classes in your program will be checked at arbitrary many points in your program. The detection routines are embedded in your program like "landmines" against crackers.The manner how this works is configurable by several parameters.

The first time tamper is detected, it displays a warning and exits JVM. The second time, a stronger warning is displayed and exists JVM. The third time, it tries to destroy the protected program itself to disable further cracking attempts.
(See also strong tamper checking and ordinary tamper checking that the Protector offers.)
Obfuscation
Package names, class/interface names, method names, and field names are automatically obfuscated, except for names that must be preserved , such as names used in the API of your program.

You can do without third party obfuscators. But if you wish, you can apply a source-code-obfuscator from a third party, before using the Protector (combinations of the Protector and a third party obfuscator).

For further details, please visit the product web page or contact us. You can also try the Protector with a free evaluation license. A half day would be more than enough to try the basic functions of the Protector.

Also, check out the restrictions of the current version, to make sure that the current version meets your needs.

Requirements

Minimum 64MB RAM (128MB recommended)

Linux, Solaris, Mac OS X, or Windows 98/2000/NT/XP

JDK 1.3.0_01 or later
Note: suppor for Java5 or later is still incomplete

JCE 1.2.2 (required for users of JDK 1.3.x only)

Apache Ant 1.4 or later
Free download: http://ant.apache.org/ (if you can't download it, please contact us.)
One of the following cryptographic providers (recommended: SunJCE):
SunJCE
     Free download: http://java.sun.com/products/jce/index-122.html
     Library: sunjce_provider.jar
Bouncy Castle (use signed JAR file of a provider)
     Free download: http://www.bouncycastle.org/latest_releases.html
     Library: one of bcprov-jdk13-xxx.jar, bcprov-jdk14-xxx.jar,...
Cryptix
     Free download: http://www.cryptix.org/

Definitions

The following terms will be used throughout this documentation. These concepts are frequently used and keys to understand the usage of the Protector:

An API class : a class or interface you provide your customers as a part of the API of your software^*1, or any class which should be accessible for your customers. Even if you don't provide any explicit API to your customers, your program must have at least one public class for your customers to use your program. Such class is called an "API class" in this manual.

An API method : a method of an API class you provide your customers as a part of the API of your software^*1. Any program should have at least one API class and one API method (for example, its main method). *1: Names of API classes and API methods will be preserved throughout the protection, in order to keep the API of your product unchanged. In other words, protection by the Protector does not affect your API document.

Restrictions of the current version

Protection of Servlets are not supported yet. However, business logic can be protected, if you separate them from Servlets. In other words, separate your program into two: a set of Servlets + a set of the other classes, then the latter can be protected by this tool.

Your product may contain Applets, but Applets are not supported as an API class yet. In other words, your customers can't call your Applets by themselves, but your program may contain and use Applets internally.<

In API classes, results of using public, package, or protected fields are not guaranteed (only private fields are supported). To use the current version of the Protector, modify your API classes and replace those accessible fields with corresponding getter/setter methods.
There is no such restrictions with non-API classes which should make up the most of your program. So, in general, the modifications should be easy.
Inner classes of an API class must be used only within the API class (i.e. its enclosing API class). There's no restrictions on inner classes of non-API classes.
Any API class must have a constructor with no arguments. If your class doesn't have any, add one (here's a complementary tool). A dummy is enough, and implementation details doesn't matter, as long as it passes compilation. The constructor may be public, package, or protected, but not private. If you have a number of classes that needs such constructors, here's a complementary tool. You will be given an opportunity to use this tool in the preparation of a project directory , and you don't have to use the tool in advance.
API classes may not have any constructors with the special form of arguments:
(Object, Class, Class, Class, Class, Class, Class, Class, Class, Class, Class )
(i.e. One Object argument and ten following Class arguments).
This special type of constructors are reserved for the Protector.
(This restriction is removed since v1.3.0)
Results of protection are not guaranteed, when your programs depend extensively on reflections or its own custom ClassLoaders.

Installation and uninstallation

To install Java Code Protector:

Install Apache Ant, if not installed yet. (See http://ant.apache.org/ for instruction)
Extract jcp141.zip and you get a directory named "JavaCodeProtector_1.4.1" ("Installation directory").
Add the installation directory to your classpath.
Add ckcpt.jar, licensee_module, and licensee_module/jc.jar (all in the installation directory) to your classpath.
Make sure that required libraries (namely, apache-ant-xxx/lib/ant.jar and the cryptographic library you use) are in the classpath.

To uninstall, just do the inverse of the above.

Usage - How to use the Protector and protect your code

For the first time only - preparation of a project directory
Protecting code
Using resultant archive

1. For the first time only - preparation of a project directory

Notes

Please take the following steps carefully and without errors, to complete the preparation.

You can evaluate the Protector with samples.

We are on our way to make it easier and safer for developers to complete this section, through further automation. Stay tuned.

Edit properties in "codeprotect.xml" (under the directory "JavaCodeProtector_1.4.1"). Please read the XML file itself for instructions. Only "Environment Variables" and "Basic Options" are mandatory. Here are descriptions of the options.
Execute Ant with the target "prepare1":

ant -buildfile codeprotect.xml prepare1
(Note: Windows users can edit and use anttask_codeprotect.bat to execute this command. The same goes for any of the following commands. Windows 9x users may have to increase the initial memory by editing proerties of the DOS menu, to avoid errors caused by the lack of memory for environment variables.)

This step will create work directories for this protection project. The root of work directory will be indicated by <projectDirectory>

Now, change your current directory to the <projectDirectory> before proceeding.
Copy all libraries necessary for the compilation of your program, into the "<projectDirectory>/lib" directory.
Copy all necessary resources (i.e. all files except Java source codes, such as image files and property files) into the "<projectDirectory>/resources" directory. The resources placed in this directory will be automatically added to the resultant archive, without changing their directory tree structure.
If you have any API class which doesn't have a constructor with no arguments (such as "public myClass(){...}" ), add such a constructor to the class (see "Restrictions of the current version"), as follows. This tool (i.e. the target "complement_constructor") makes it easier for you to modify your source code, for this purpose. Even if your program doesn't have such an API class, you can still execute this target, because it will simply quit, saying there is nothing to change.

Execute Ant with the target "complement_constructor".

ant -buildfile codeprotect.xml complement_constructor

When you execute this for the first time, a wizard for license management may appear. Then, please import a license key and try this step again.

Otherwise, this task will detect all the classes without the above type of constructor, under <projectDirectory>/<src> and insert a default constructor into each of them. The modified source codes usually have compilation errors regarding implementation of the constructor (namely, the arguments of super()).

Please manually remove those compilation errors in <projectDirectory>/<src>, before proceeding to the next step.
Insert the following line into source code under <projectDirectory>/<src>, where you want to embed strong tamper checking routines^*1. You may insert the line at any point in method bodies or in a static initializer of a class:

//!!!CKPTCFIALL Tamper-Checks!!!//

*1: The strong tamper checking routine checks the integrity of all classes in your program at once, whereas ordinary tamper checking checks a certain number of randomly selected files (see -tcsize option). It's not always recommended to use the strong tamper checking, especially when your program is large. The ordinary tamper checking routines will be automatically inserted into various positions according to the options you set.
Edit a command line arguments file ^*1 "<projectDirectory>/javadoc_argument_file_api" and list up all API packages and/or classes of your program. One source filename or package name per line. Here's an example.

Important note: Any of your classes, if refered in one of your API methods, must also be an API class. Such reference can be made in either method arguments or return values. Accordingly, all such API classes must be declared in the above file, by their packages or source files, or the preparetion will fail. Especially, for any API method, any realtime class of its returned object (i.e. the class you can get by retunedObject.getClass()) must be declared as an API class.
Execute Ant with the target "prepare2":

ant -buildfile codeprotect.xml prepare2

This step will create necessary javadoc files under the <projectDirectory>/docs/api and <projectDirectory>/docs/internal directories.
If you need to exclude some entries from the generated API document under the <projectDirectory>/docs/api, take one fo the two methods.
Create a directory under the "<projectDirectory>/docs/external" directory, for each of the external libraries that your program uses, and copy their javadocs under corresponding directories. Here's an example.
Among javadoc generated files, the Protector recognizes only those files with the prefix "index" and the extension ".html" (e.g. "index-all.html", "index-files/index-1.html"...). Edit names of those third party API documents, if necessary, to bring them back to the standard names which javadoc assigns. For example, if a third party provides its API document as "javadoc.htm", rename it to the standard name "index-all.html", so the Protector can find it.
Execute Ant with the target "prepare3":

ant -buildfile codeprotect.xml prepare3

When you execute this for the first time, a wizard for license management may appear. Then, please import a license key and try this step again. Otherwise, the Protector will analyze the third party API documents, if any.
(Note: If you pressed the "Cancel" button by mistake, try this step again, to complete the preparation.)

That's all for the preparation.

FAQ on this section

How do I import a license key?
The first time you use the Protector, a graphical wizard will appear. Please follow the wizard and request a license key (TRIAL license is free). Then, quit the wizard, and send us the request file which the wizard generates. The request file contains data on your registration and computer identification (the data is encrypted and hashed for your privacy).
Please allow us1 business day to send you a license key by e-mail. After receiving a license key, please execute the same Ant task again, and the wizard will appear again. Follow the wizard to import the license key file you get (select "Take in key" at the Main Menu). Once your key is successfully taken in, select "Continue with the current key" at the Main Menu.

How do I disable the wizard while evaluation?
Check "Don't show this wizard again today" checkbox at the bottom of the main menu of wizard, and select "Continue with the current key" option to close the wizard.

How do I reflect updates in original source codes?
To use the Protector after modifying your source codes, you have to replace the contents of <projectDirectory>/src with the latest source codes, and repeat this section from the step V through step XII.

Invalid license key?
Adding or removing big drives such as network drives may affect the computer indentification, and the license wizard might say your license key is "invalid". If this is the case, put your configuration back to the original or request another license key for your new configuration.

Can I reuse a project directory?
Please create a new project directory, or remove the old one, before you start working on a new project. Reusing a project directory may cause unexpected errors.

2. Protecting code

Just execute Ant with the target "main":

ant -buildfile codeprotect.xml main

The Protector will protect your code; It creates a resultant archive after source code obfuscation, bytecode encryption, and embedding tamper resistant routines into your program. The protection is customized by the options you set (Usage > 1 > I ).

To see progress, run the Protector from command line instead of from Ant:
java com.chainkey.tools.CkProtector [options] <project directory> <name of API directory> <name of SRC directory>

OPTIONS

3. Using resultant archive

The Protector will generate an archive file ("resultant archive") by taking the previous step "2. Protecting code ". This is the protected program. Please note that the protected program will be disalbed by tamper-proofing, when any of the following holds:

the program is not in the form of this archive (e.g. when extracted)
the name of archive is modified
modifications in any encrypted class is detected.

The name of the resultant archive can be specified by the -archive option of the Protector. Usage of this archive is straight forward: just regard it as the archive of your original (unprotected) program. In other words, add the archive to the classpath and execute java with an API class, as usual (e.g. simply execute java com.myCompany.myApiClass1 ), except that:

Your copy of the cryptographic library must also be in the classpath (see Requirements).
If you are using JDK 1.3.x, add the jce.jar (e.g. "jce1_2_2.jar"), local_policy.jar, and US_export_policy.jar files into /jre/lib/ext directory, into the classpath, or into any effective "ext" directory of the computer's Java environment.

Managing multiple editions

When you need to protect multiple editions of your program, such as the "Lite" and "Pro" edition, take the following steps:

Prepare src and api directories for each edition
In general, each edition has a distinct pair of source code and API document. Prepare src and api directories for each edition (under the same project directory).

For example, if you are developing 2 editions "Lite" and "Pro", it is recommended to set up following directories:

myProject1/src_all (for the following step ii)
myProject1/api_all (for the following step ii)

myProject1/src_pro (for pro edition)
myProject1/api_pro (for pro edition)

myProject1/src_lite (for lite edition)
myProject1/api_lite (for lite edition)

Protect the "everything" edition
Prepare a (virtual) edition which contains all and full-featured source codes of your program (e.g. use "src_all" and "api_all" directories as its src and api directories ). Prepare a project and protect this "everything edition" in an ordinary way (as described in "Usage"). Here, make sure that:
- the API document is prepared so that any API entry (package, class/interface, method, or field) in any edition appears in it.
- the Protector is executed without the -reusemap
After execution of the Protector, it is recommended to back up the resultant archive.
Protect another edition
Edit the build file ("codeprotect.xml") and protect another edition in an ordinary way (as described in "Protecting Code"). The difference is that tasks must be executed:
- with the -reusemap and
- without the -layers option
- using src and api directories for this edition (e.g. edit the build file and specify "src_lite" and "api_lite" for corresponding parameters). See the descriptions in the build file for how to specify those directories.
After execution of the Protector, it is recommended to back up the resultant archive for this edition.
Repeat
Repeat the step ii. for all editions of your program.

[ Note ]
Do not remove any file directly under the <projectDirectory> while repeating the procedure.