Any java
command line that starts the
application must contain the
following options:
Example:
%JAVA_HOME%/bin/java.exe -noverify -Xms64M -Xmx256M
-javaagent:lib/PackAgent.jar
-XX:+DisableAttachMechanism
-Djava.library.path=./lib -Dappl.starter="xxx.yyy.zzz.MainClass"
-classpath ... xxx.yyy.zzz.MainClass [args]
For jar archives, the
command line must contain the same options except for the
application starter that must be '-Dappl.starter="JarFileName.jar"',
where "JarFileName"
is the name of the jar archive of the application, e.g., %JAVA_HOME%/bin/java.exe -noverify -Xms64M -Xmx256M -javaagent:lib/PackAgent.jar -XX:+DisableAttachMechanism -Djava.library.path=./lib -Dappl.starter="JarFileName.jar" -jar JarFileName.jar
|
FlatCode Java Obfuscator
Guide - Obfuscation
Brief
Description
Go to Renaming
|
|
|
||||
| The FlatCode JOB installation package is sealed within the flatcodejob_XX_setup.exe file. Double
click this file and follow the installation
instructions.
To uninstall, double click the 'uninstall' file in the installation directory. |
|||||
|
|
To start obfuscation, open the root
directory of your project, create
there the 'src'
subdirectory, and copy there all of the source material
of your project keeping the hierarchy of
the target output package or jar archive like
in the example below D:\Java\Java Projects\Current Project | +- - - - - - Project Files +- - - - - - Library +- - - - - - Resources +- - - - - - Docs +- - - - - - Other +- - - - - - src | + - - - - - Source Pack Also, collect all necessary
library class packs and jar files
necessary for compilation somewhere in your
application's directory.
|
||||
|
|
The FlatCode JOB
working session consists of the following
stages. First the obfuscator creates in the src directory a text file named Source_args.txt, which contains paths to all java files of the obfuscated application, compiles them, analyses and modifies the compiled classes, and stores them in the Uniform directory of the root directory. It also creates auxiliary CB.class, CB_application_name.dll, and PackAgent.jar files and stores them in the lib subdirectory of the folder where the obfuscated package or jar archive must be stored. The obfuscation directory may be set or selected by the user in the root directory of the project. If the user does not set or choose the obfuscation directory, a default directory named Obfuscated will automatically be created by the program in the root directory. As an example, a possible structure of the directory tree of an obfuscated application is presented below  Prior
to obfuscation, FlatCode
JOB executes all operations for
hiding the procedure of execution of flattened
methods.
|
||||
| Start installed FlatCode JOB.
Using
the control buttons 1 (up the tree) and 2 (drive
selection), open the root directory of your project in the directory tree and select the src subdirectory.  Press the 'Target' button to transfer the path to this src directory in the target's field. Highlight the directory/jar files containing library classes necessary for compilation, press the 'Application' item of the menu bar and then the 'Set classpath' menu item.
A 'Classpath' table will appear in the 'General Reports' tab showing the selected directories and/or jar files. The two buttons on the right side of the reports panel are for removing from the table a highlighted row(s) or adding to the table an item/s highlighted in the directory tree, respectively. If necessary, check/edit the entries in the 'Classpath' table.
The first row of the class table is empty and is intended for the path to the folder that must contain two asm library files asm-6.2.jar and asm-tree-6.2.jar necessary to run the obfuscated application. If this row is left empty these files will be copied to the root directory of the project. Otherwise, select a folder for these files in the directory tree and drag and drop it exactly inside the first row. If you want to create a new folder, then select a leaf in the directory tree and press shift + F10 (or right click in the directory tree) and a context menu will appear with four options
It is possible to rename a folder or create a folder and rename it. To set a folder as the house for the obfuscated project (directory where the obfuscated package/jar archive have to be placed) select it and choose the Obfuscation Directory item in this context menu. The default obfuscation directory will be named Obfuscated and located in the root directory of the project. Note that the flatcode java obfuscator attaches to the obfuscation directory a subfolder lib containing the following auxiliary files: CB.class, CB_application_name.dll, and PackAgent.jar. These files are used by the obfuscated application at runtime. The
Clean Directory option
in the context menu is intended for
deleting all entries in the selected
directory.
After these preliminary procedures, press the 'Compile' button. This will start the java source code compilation. The compiled class files are stored in the 'Uniform' subdirectory (see above).
If
the compilation succeeded start the bytecode
analyzer. The corresponding notification
appears in the 'Reports' pane of the 'General Reports' tab. Open 'Application' menu and press 'Analyze bytecode' item. |
|||||
|
|
To perform obfuscation without
renaming, press successively 'Confirm rename options'
(1),
'Confirm renaming in string constants' (2), and 'Accept renaming profile' (3) buttons.
Now the 'Options' item of the
Obfuscator's menu bar is active.
 NOTE: Check the 'Profile with HPROF agent' menu item if you are intended to run and test the obfuscated code as a sub process within the obfuscator (see section 'Sub process'). The possible combinations of these options are presented in the table below.  |
||||
|
|
Select option(s) and press the 'Start
obfuscation' button.
For
multi-class java programs, 'Progress'
bar may appear showing the obfuscation advancement. When obfuscation ends, a new Obfuscated Methods tab will appear in the main panel. To view obfuscated
methods, activate the General Reports
tab and navigate to the class you want to see in
the directory tree.
Activate again the Obfuscated Methods tab, select a class file in the directory tree and double click on it. The list of methods of this class will appear in the table.
 |
||||
|
|
If the 'Select
methods' option is checked, the 'Accept
selected methods' button is activated
and the Methods tabbed pane appears. Activate the General Reports pane and navigate to the class you want to see in the directory tree.Then change for the Methods pane and double-click the class under interest. The list of methods of the selected class will appear in the Methods pane.
Deselect the methods of this class that should not be obfuscated and press the 'Accept selected methods'
button. If needed continue this procedure.
By default the FlatCode
tries to obfuscate all
methods except for deselected ones. It is also possible to deselect/select a group of methods by right-clicking on the Methods pane and choosing an item in the pop-up menu.
When the procedure of method selection is completed press the 'Start obfuscation' button and begin the obfuscation as in the All methods option. RESTRICTIONS1. by pattern Select this option and press 'Start obfuscation' button. In the following input dialog, type in (or paste) the starting portions of some class/package names of the application. Press 'OK' button. Then all classes beginning with these patterns will not be obfuscated.  2. by type Select the other restriction option and click on 'Start obfuscation' button. In this case, the following dialog appears  which allows to skip obfuscation in classes starting with the patterns contained in the text fields provided that the corresponding check boxes were selected. Press 'OK' button. Press now the 'Start renaming' and 'Set Decryption tools' button successively. FlatCode JOB finishes the obfuscation process
and the creation of tools to
manage the flow control sequence at
runtime.
WARNING: Do not edit/modify or delete the obfuscated package or jar archive in the obfuscation subdirectory as well as any file in the attached lib subdirectory!
|
||||
|
|
The
jar archiving function of FlatCode
JOB is mainly intended for
replacement of class files in the original
jar archive with the corresponding
obfuscated versions.
Additionally, you can create a jar file
from scratches preliminarily preparing
all archiving files.
After pressing the 'Accept renaming profile'
button (3),
click on the 'Options' menu and then check
the 'Jar archive -> Create' menu item.
 Check all other menu items needed and pass the obfuscation stage. The new 'Jar archive' tab will appear. There are three options to set the Manifest file: 1. Let the obfuscator to set a default Manifest. 2. Let the obfuscator to create an editable Manifest. 3. Apply the Manifest prepared by the user beforehand and stored it in the root directory of the project. If no Manifest found in the application's root directory, the following message appears  If the Default button is pressed the following manifest draft appears in the Manifest panel of the Jar Archive tab  The user is able to further edit and accept this manifest. If the Edit button is pressed then the obfuscator searches main classes of the project and suggest the user to select the relevant option  Select and press the 'OK' button. Activate the Jar Archive tab and check/edit the proposed Manifest file  Later the obfuscator saves the contents of this pane in the project's root directory. A copy of the Manifest is also stored in the obfuscation directory. If the obfuscator found a ready Manifest file in the root directory of the project then this manifest file appears in the Manifest pane. Activate the 'General Reports' panel and select all items that must be included in the jar archive in the directory tree. If you are just going to replace the original class files with their obfuscated versions then select only the obfuscated classes/packages in the 'obfuscation' directory.
 Activate the 'Jar Archive' pane and press the 'Add' button on the right. Check the archiving files. Do not include in the list the relevant Manifest.mf file. NOTE: It is possible to insert into the 'Jar Archive' panel any file/folder by drag-and-drop from the directory tree or by selecting a file/folder in the directory tree and pressing the 'Add' button.
 Click now the 'Set Decryption tools' menu button. An input dialog will appear to set the path to the jar archive to create. Edit the path as needed and click 'OK'.
 Another input dialog will appear suggesting to use as a template a jar archive which is already exist. In such a case, the obfuscator copies all entries of the original jar archive to the new archive except for class and manifest files. The previous class files are replaced with their obfuscated analogues that are set in the 'Jar Archive' panel and the old manifest is replaced with the new one.
Otherwise if you intend to create a new jar archive and have already prepared all necessary files/folders and added them to the 'Jar Archive' table, empty the 'input' field for the original jar archive and press the 'OK' button. WARNING: To create a valid jar archive from the classes obfuscated by Flatcode JOB always generate them by this obfuscator.
|
||||
|
|
The results
of obfuscation and renaming are
presented in the 'ObfuscLog.txt'
and
'RenameLog.txt
files of the Log
subdirectory
which is at the
same level as
the
Obfuscation
and Unifrom
folders.
|
||||
| To
launch the obfuscator double click
the 'flatcodejob_XX.bat'
file in the root directory of the Flatcode
JOB. |
|||||
|
|
After
obfuscation, the program shows
the above input dialog
suggesting the user to select
the appropriate main class for
launching the current
application. Select an option
and click 'OK'. The Obfuscator
generates a default batch file in
the root
directory for
launching either a packed or an
archived application. The
default batch file may be
further edited by the user
following some general
requirements for these files
presented below.
|
||||
|
|
Pressing the 'Rerun
obfuscation' button returns the obfuscator to the 'Plain
obfuscation' stage from where you can repeat
obfuscation with the same or other options.
 Alternatively, you can restart the obfuscator by pressing the 'Restart obfuscator' button and begin the obfuscation procedure for the same or another application (the 'Compilation and code analysis' stage)  The 'Run sub process' button launches the obfuscated application as a child process within the parent obfuscator's JVM. To activate this button, preliminarily select the 'Profile with HPROF agent' obfuscation option (see 'Plain obfuscation' stage).  Note that, upon starting, the sub process dynamically loads a simple 'HPROF' agent for "in-house" profiling the obfuscated program (https://docs.oracle.com/javase/8/docs/technotes/samples/hprof.html). When obfuscation is completed press the 'Run sub process' button. The following reminder appears to add any necessary additional data to the application package.  Check the application package and press 'OK'. Specify all information requested  Click 'OK' to execute the program. Test the obfuscated application. Profiler and error information is usually presented in the obfuscation directory of the application and can be helpful for validation of the obfuscated code. As an example, below is a fragment from a crash dump file that may be used for detection of obfuscation defects.  The shifted region refers to the application and shows the classes and methods where the error(s) may occur. To detect the cause of the error, rerun the obfuscation without flattening of some (or all) these methods. When the error was located, correct it by refactoring the method or excluding its obfuscation. |
||||