irrFuscator Manual

Content:
1. Overview
2. How to use the command line tool
3. Registering irrFuscator
4. Integration into FlexBuilder or Ant
5. Problems with obfuscated code
6. Using irrFuscator comment directives
7. Further information

---

1. Overview

The ActionScript 3 Byte Code (abc) in .swf files still contains a lot of symbols revealing how your program works and what it does, so it is very easy to reverse engineer or steal your code. irrFuscator reads in a directory of .as and .mxml files, processes them and puts them out into a target directory. Simply recompile the directory with the obfuscated files and your .swf files are a lot safer.

irrFuscator is available for the command line but also comes with a convenient GUI frontend. To start the fontend, start the program
irrfuscator_gui.exe
For the command line tool, start irrfuscator.exe

---

2. How to use the command line tool

irrFuscator includes a command line tool for obfuscating your projects. The file is irrfuscator.exe is located in the installation folder. Usage:
      or:    
Will obfuscate a single SWF file or a whole Flex Actionscript 3 project. In SWF mode, 'source.swf' is a SWF file which will be obfuscated and written to 'target.swf'.

In source mode, 'sourceDirectory' contains .as and .mxml sources which will be obfuscated and written into the 'targetDirectory'.

The content of the target directory will NOT be erased before writing code into it, so you might want to do this before to be sure no other obufscated code from a previous obfuscation is still located there.

Additional options:

--stripcomments	Remove comments from source
--stripwhitespace	Remove white space (spaces, tabs, line breaks) from source
--notdeterministic	Will not generate deterministic obfuscated symbols, meaning that the same input code will not always generate the same obfuscated output.
--ignore:<symbol>	Will tell the obfuscator to ignore a specific symbol during obfuscation. --ignore::foobar will not obsucate any appearing symbol 'foobar'. This option can be specified multiple times to ignore more than one symbol.
--ignorelist:<file>	Will tell the obfuscator to ignore a list of symbols during obfuscating. --ignorelist::list.txt will not obfuscate any symbol in the file list.txt. The text file must contain one symbol per line.
--ignorepkg:<dir>	Will tell the obfuscator to ignore a package or directory during obfuscating. --ignorepkg::util will not obfuscate any symbol or file in or below a directory named 'util'. Is ignored in SWF mode.
--nobackups	When overwriting a file in the target directory, no backup of the original file is created anymore. Is ignored in SWF mode.
--copyallfiles	Also copies files to the target directory which are not obfuscated. These are usually sound files and images. Is ignored in SWF mode.
--encryptstrings	Encrypts strings in the actionscript code by adding a function named 'irrcrpt' to the code. Will create a file irrcrpt.as in the target directy which needs to be compiled into the project additionally. Ignored in SWF mode.
--obfuscateconsts	Will obfuscate the symbol names of constants. Note: Could cause problems when using dynamic classes.
--obfuscatevars	Will obfuscate all variables. Warning: This is very likely to introduce bugs in your code because in the flex SDK, a lot of classes like XML readers and URLVariables are dynamic. Be sure to include all symbols you are using with such classes in the ignore list when using this option.
--swc:<file>	If your project uses a SWC library to compile, let irrfuscator know about it using this option. Symbols used from the SWC will not be obfuscated then.
--notargetfilerem	If irrfuscator finds .as and .mxml files in the target directory it will rename them (add a .bak extension) to move them out of the way. This option disables this feature. Ignored in SWF mode.
--writesymboltable	Writes a text file named 'irrfuscator_symbols.txt' to the target directoy which contains the original and new symbol names

Example 1:
Will read game.swf file and write the obfuscated version to game_secure.swf.

Example 2:
Will read the files (*.as, *.mxml) in C:\\src and obfuscate them to C:\out

Example 3: Same as above, but with some additional options.

---

3. Registering irrFuscator

irrFuscator will work for free for 7 days, after this you will have to buy a license if you want to continue using the software.
To buy a license, simply visit the irrfuscator webpage at
www.ambiera.com/irrfuscator
and follow the steps described there.

---

4. Integration into FlexBuilder or Ant

irrFuscator is working completely independent of any other tool but it can also be used together with Flex Builder of course.
Here is an example on how to setup an ant task with irrfuscator in Flex Builder to obfuscate the source:

<target name="obfuscate">
	<mkdir dir="${BUILD_DIR}/src"/>
	<exec executable="${APP_ROOT}/place/where/you/placed/irrfuscator.exe">
	  <arg value="${APP_ROOT}/src"/>
	  <arg value="${BUILD_DIR}/src"/>
	  <arg value="--nobackups"/>
	</exec>
</target>

You only need to adapt the path names to your personal settings.
Note that your Flex Builder needs to have ant installed for this. (The standalone version doesn't include ant, the plugin version does). If your Flex Builder doesn't have ant, do the following:

• Launch Flex Builder
• Go to Help > Software Updates > Find and Install
• Search for new features to install, click next
• Select "Eclipse.org update site", click finish
• Select "Eclipse Java Development Tools", click next and download
• When finished, click "Install all" to install Java Development Tools
• Restart Eclipse

If you only want to obfuscate the .SWF file after compilation instead, you only need to make irrfuscator run afterwards as post build step.

---

5. Problems with obfuscated code

There are two types of problems which could occur:

5.3 Your obfuscated code doesn't run correctly any more

Actionscript 3 still is a dynamic language altough it has a lot of static typed features now. When a dynamic symbol was obfuscated, it may cause the program not to work correctly anymore. The usual way to make the program work again is putting all dynamic symbols into the ignore list.
Example: The URLVariables object or the attributes in XMLNodes are dynamic. When accessing an XML attribute in this way for example:

var node:XMLNode = // some node..;
node.attributes.FooBar

then 'FooBar' is dynamic and should not be obfuscated. To let irrFuscator know that it should not obfuscate any symbol with the name 'FooBar', put FooBar into the sybmol ignore list.

It also helps to try to switch off the option 'obfuscate constants' and 'obfuscate all vars'.

5.2 Your obfuscated code doesn't compile anymore

After you obfuscated some code and it doesn't compile any more, what can you do?
This is usually caused by a symbol which wasn't obfuscated correctly. Take a look at the place in the source which caused the problem and put the errornous symbol name into the ignore list, this usually helps.

---

6. Using irrFuscator comment directives

The professional edition of irrFuscator supports the following comment directives:

• IRRFUSCATOR_ignorebegin: All symbols which are declared following this directive will not be obfuscated.
• IRRFUSCATOR_ignoreend: Stops the IRRFUSCATOR_ignorebegin directive, all following symbols will be obfuscated again.

• IRRFUSCATOR_noStringEncryptBegin: All strings which are used following this directive will not be encrypted, when using the --encryptstrings option.
• IRRFUSCATOR_noStringEncryptEnd: Stops the IRRFUSCATOR_noStringEncryptBegin directive, all following strings will be encrypted again.

Irrfuscator directives are written directly into comments of ActionScript 3 source, like for example here:

// IRRFUSCATOR_ignorebegin
    public function foobar():void { }
// IRRFUSCATOR_ignoreend

The symbol 'foobar' will now no longer be obfuscated.
In this way, it is also for example easily possible to exclude a whole class and all of its methods from obfuscation:

// IRRFUSCATOR_ignorebegin
public class MainClass 
{
  public function MainClass() 
  {
    // ...
  }	
	
  public function foobar()
  {
    // ..
  }
}	
// IRRFUSCATOR_ignoreend

All appearences of the class MainClass now won't be obfuscated, as well as any calls to its members. Note that of course, the bodies of the functions will still be modified, when they for example call functions of other classes, which are obfuscated.

---

7. Further information

For further information, please see the website at www.ambiera.com There is also a web forum available for user discussions.