Retrologic Systems Retrologic Systems Retrologic Systems
RetroGuard for Java Obfuscation
  RetroGuard  |  CAPTCHA  |  Contracting  |  Resellers  |  Contact

RetroGuard FAQ

1. Why obfuscate Java code?

2. How does obfuscation change the Java classes?

3. Can obfuscation be reversed?

4. What versions of Java is RetroGuard compatible with?

5. How much does RetroGuard cost?

6. Why is RetroGuard a command line tool?

7. Why does RetroGuard act only on JAR files?

8. What is the RetroGuard script file?

9. Can RetroGuard handle RMI and Serializable classes?

10. Does RetroGuard introduce corruption to the obfuscated Java classes?

11. After obfuscation, why does the log file report that some names are left unchanged?

12. Are there situations where obfuscated code can behave differently than the original?

13. How can these problems be solved?

14. Can I use byte-code encryption as well as obfuscation?

1. Why obfuscate Java code?
Java bytecode (*.class files) contains all of the information, apart from comments, that is in Java source (*.java) files. Using a tool called a 'decompiler' a hostile competitor can easily reverse engineer your Java classes.

To counter this threat, it is possible to 'obfuscate' your class files before distributing your software.

2. How does obfuscation change the Java classes?
The obfuscation process strips all unnecessary information (line numbers, local variable names and source file names used by debuggers) from the classes. Also, class, interface, field and method identifiers are renamed to make them meaningless.

3. Can obfuscation be reversed?
No. Obfuscation is an information-lossy (one way) process.

4. What versions of Java is RetroGuard compatible with?
RetroGuard is written in Java and runs on Java SE 6 and earlier versions back to JDK-1.1. It will obfuscate all valid Java bytecode.

5. How much does RetroGuard cost?
RetroGuard is released under several licensing options: for commercial users, RetroGuard Pro is available under a commercial license at a cost of $139 per year; for academic and not-for-profit users, RetroGuard Lite is available under a non-commercial license; for open-source tools developers, the RetroGuard Library is available in source format under the GNU General Public License.

6. Why is RetroGuard a command line tool?
RetroGuard is designed to be seamlessly integrated into your build process. This cannot be done in a reliable and repeatable fashion if the obfuscation tool depends on a graphical user interface for operation.

7. Why does RetroGuard act only on JAR files?
To determine which classes are to be obfuscated, most obfuscators start at a single entry point (usually the 'main' method of an application, or the 'Applet'-derived class for an applet), and construct a tree of all classes accessible from that point. Unfortunately, this method is quite limiting and works only in simple cases. If your Java code has multiple entry points (several applications, applets, or JavaBeans, or if your code is intended to be used as a Java library) then this method is just not flexible enough.

Instead, RetroGuard obfuscates all classes and interfaces within a JAR file. JAR files are the industry standard mechanism for packaging Java classes for distribution - it is easy to package your classes as a jar using the 'jar' utility distributed with the Java Development Kit from Sun Microsystems. Any number of entry points to the JAR can be specified using a RetroGuard script file. This allows the obfuscation process to be completely flexible.

8. What is the RetroGuard script file?
Certain names have be reserved from obfuscation because they are intended to be accessed from outside. These reserved names can include the 'main' method and class of applications, any classes derived from 'Applet', as well as JavaBean classes. For the writers of Java libraries this list of reserved names can become quite extensive due the the large number of entry points into the code. The RetroGuard script file is a listing of these reserved names.

Also, by default, all unnecessary class attributes are trimmed fom each class during obfuscation. In the unlikely event that you want to retain any of these attributes, this can be done through the script file.

9. Can RetroGuard handle RMI and Serializable classes?
Yes. Using the script line '.option RMI' RetroGuard-v2 will preserve all the necessary class, method, and field names so that RMI and serializable classes will operate normally after obfuscation. It is even possible for an unobfuscated server to communicate with an obfuscated client.

10. Does RetroGuard introduce corruption to the obfuscated Java classes?
No. RetroGuard outputs only valid and fully verifiable Java bytecode (as described in 'The Java Virtual Machine Specification' by Tim Lindholm and Frank Yellin).

In contrast, several obfuscators attempt to prevent decompilation by introducing illegal or corrupt entries to the class files. The component of a Java virtual machine which checks for corruption is called the verifier - by default, all downloaded applets are checked by the verifier before being run. In currently available virtual machines, the verification procedure is not as strict as that specified in 'The JVM Specification'. However, future virtual machines may have much stricter verifiers, and Java code obfuscated using corruption will simply fail. Using an obfuscator that corrupts in a way which happens not to be caught by current VMs is therefore unsafe - it is a risk that software developers cannot afford to take.

11. After obfuscation, why does the log file report that some names are left unchanged?
Due to inheritance constraints, some identifiers cannot be modified. For example, if a class implements the interface 'java.util.Enumeration', the methods inherited from that interface ('hasMoreElements' and 'nextElement') cannot be changed.

12. Are there situations where obfuscated code can behave differently than the original?
Yes. There are certain methods (in the classes 'java.lang.Class' and 'java.lang.ClassLoader') in the JDK which refer to classes, methods or fields using a 'String' name. If these JDK methods are used to refer to identifiers inside your JAR, your code may behave incorrectly after obfuscation because the 'String' name may have been changed.

13. How can these problems be solved?
RetroGuard adds a warning to the log file if these reflection methods are used in the obfuscated JAR file. If the reflection methods act only on classes, methods and fields outside of the JAR, there will be no problem. If, however, the reflection methods act on identifiers within the JAR, these identifiers must be specified in the RetroGuard script file so that obfuscation does not change them.

For the special case of 'Class.forName(...)' and 'MyClass.class' constructs, RetroGuard-v2 can take care of updating their constant string arguments automatically, using the script line '.option MapClassString'.

14. Can I use byte-code encryption as well as obfuscation?
Byte-code encryption is a method of encrypting classfiles for distribution and then using a custom classloader to decrypt them at run-time. This might appear to be a secure way to distribute Java software, but the idea is fundamentally flawed.

All such encryption methods can be easily broken by using an instrumented Java virtual machine that overrides 'ClassLoader.defineClass' to print out the decrypted classes. This is discussed in detail, with clear examples, in an excellent article by Vladimir Roubtsov, "Cracking Java byte-code encryption: Why Java obfuscation schemes based on byte-code encryption won't work".

And so, we believe the use of byte-code encryption provides only a false sense of security and is not recommended.

Site News
(click for more...)
RetroGuard Newsletter
Your email address will be kept strictly confidential and never provided to third parties. Unsubscribe using the email address beneath each mailing.
Copyright © 1998-2010 Retrologic Systems. retroguard | captcha | contracting | resellers | site map | contact
All rights reserved. site terms | privacy policy