Quickstart


Introducing Crema™

Crema is the Java obfuscator - the program that makes your compiled Java software less vulnerable to decompilation and reverse engineering. To that end, Crema removes all non-essential symbolic information from your .class files, and optionally replaces it with fake symbolic information designed to confuse decompilers.

Crema also includes two features that are specifically targeted at the Mocha™ decompiler: it can include a small "bomb" in your .class files that will make Mocha crash but is harmless in any other respect. Or it can include a customizable message that will be printed by Mocha. Such a message could inform a user of the license violation s/he is about to commit.

Using Crema

Before you can use Crema, you should install it and verify that you can run it.

Step 1 - Selecting the .class files

Determine which .class files you want to obfuscate. In general, obfuscate all the classes that make up your project (applet, application, package, etc.). With Crema, you obfuscate them all together.

If your project uses library packages (other than the standard packages) you can include them in the obfuscation, or leave them as they are. Unless the license agreement for the library contains explicit instructions, the choice is up to you.

Step 2 - Running Crema

Now run Crema, specifying the -v parameter and the names of the .class files selected in the previous step (you can use * and ? wildcards). For instance:

java Crema -v *.class

Crema will print something similar to the following

CREMA - The Java Obfuscator - Version 1.0
Copyright (c) 1996  Hanpeter van Vliet

Loading Node.class
Loading Edge.class
Loading GraphPanel.class
Loading Graph.class

Obfuscating Node
Obfuscating Edge
Obfuscating GraphPanel
Obfuscating Graph

Saving Node as $1.crema
Saving Edge as $2.crema
Saving GraphPanel as $3.crema
Saving Graph as Graph.crema

The .crema files are the obfuscated version of your project. Move to your web site, rename to .class, and presto! (Crema can also produce .class files directly; see output parameters for more information).

Step 3 (optional) - Excluding class and member names

There are three kinds of symbolic names in your project that should not be obfuscated, or your project will stop working. Two categories (public items and method overrides) are recognized automatically be Crema and do not require user intervention. The third category, classes referenced by name, is recognized by Crema but not handled automatically:

If your project uses Class.forName(), the classes that may be referenced by that statement should not be renamed, or the call will fail. Similarly, if you use Class.getName() you will get different answers for classes that have been obfuscated. Crema will automatically detect and report the use of these methods with a message similar to the following:

Obfuscating SortItem
  Method void run() calls Class.forName()
  Be sure to exclude (with -xc) the classes that may be referenced here!

You must manually determine which classes can be referenced here, and exclude them with the -xc parameter when you re-run Crema. In practice you will want to create a parameter file for this purpose.

Step 4 (optional) - Verifying and tuning the obfuscation

If you want to see how effective Crema is on your .class files, just feed them to Mocha and see what happens. Most likely, Mocha will crash immediately with a NullPointerException. Crema exploits a bug in Mocha to make that happen. Cute, but it may not be effective against other decompilers.

To see what the result would be if Mocha did not crash, rerun Crema with the -nobomb switch. (This switch is not recommended in general, just to satisfy your curiosity). Then run Mocha on the result.

You can play with the obfuscation parameters to tune the effectiveness of Crema. Once you have established the optimum set of parameters for your purpose, you will want to record them in a parameter file for later use.


<< Copyright © 1996 Hanpeter van Vliet >>