Installation

You will find here some informations on how to get, build and use our project.

Getting the sources and building

We maintain several branches: the one named llvm-3.4 is the latest official (i.e., non-dev) version released by the LLVM team, i.e., the version 3.4 released on January 6th, 2014; the one named clang-425.0.24 is the latest open-sourced version provided by Apple, and it relies on LLVM 3.2. Older branches are also available: llvm-3.3

At the moment, all our obfuscation transforms have been ported in all branches.

To get the latest version of the LLVM branch, you can use the following commands:

$ git clone -b llvm-3.4 https://github.com/obfuscator-llvm/obfuscator.git
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE:String=Release ../obfuscator/
$ make -j5

Older branches can be accordingly be cloned.

To get the latest version of the Apple branch, you can use the following commands:

$ git clone -b clang-425.0.24 https://github.com/obfuscator-llvm/obfuscator.git
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE:String=Release ../obfuscator/
$ make -j5

When the build is finished, you should have all the binaries in build/bin. Note that this source tree contain LLVM and Clang.

How to use it

The simplest way to use Obfuscator-LLVM, is to pass a flag to the LLVM backend from Clang. The current available flags are :

1. -fla for the [control flow flattening](Control Flow Flattening) pass
2. -sub for the [instruction substitution](Instructions Substitution) pass
3. -bcf for the [bogus control flow](Bogus Control Flow) pass

Imagine that you have a code file named test.c and that you want to use the substitution pass; just call clang like that :

$ path_to_the/build/bin/clang test.c -o test -mllvm -sub

Of course, you can call more than one pass at a time (e.g flattening and substitutions) :

$ path_to_the/build/bin/clang test.c -o test -mllvm -sub -mllvm -fla

For each pass, there is two others flags to control what you want to obfuscate. The 'per' flags (-perFLA, -perSUB, -perBCF), allow you to tell the pass to obfuscate only a certain percentage of functions in our code, e.g :

$ path_to_the/build/bin/clang test.c -o test -mllvm -sub -perSUB=34

this will obfuscate all functions in your code with a probability of 34%.

The second flag allow you to tell the pass to obfuscate only a list of function (-funcFLA, -funcSUB, -funcBCF). If you have a file with 3 functions in it (foo(), bar(), main()) and that you want to obfuscate only the foo() and bar() function, you can call clang like that :

$ path_to_the/build/bin/clang test.c -o test -mllvm -fla -funcFLA="foo,bar"

will only obfuscate the foo() and bar() routines.

If you have a project using the 'autotools' and you want to compile it with obfuscation, you can do that :

$ CC=path_to_the/build/bin/clang
$ CFLAGS+="-mllvm -fla" or CXXFLAGS+="-mllvm -fla" (or any other obfuscation-related flags)
$ ./configure
$ make

If you have questions, don't hesitate to [contact](How to Contribute) us.

Integration into Xcode

To use o-llvm within Xcode, you have to write a Xcode plugin.

This tutorial is based on this one. It was tested with Xcode 5.1.1.

---

$ cd /Applications/Xcode.app/Contents/PlugIns/Xcode3Core.ideplugin/Contents/SharedSupport/Developer/Library/Xcode/Plug-ins/
$ sudo cp -r Clang\ LLVM\ 1.0.xcplugin/ Obfuscator.xcplugin
$ cd Obfuscator.xcplugin/Contents/
$ sudo plutil -convert xml1 Info.plist
$ sudo vim Info.plist

Change:

<string>com.apple.compilers.clang</string> -> <string>com.apple.compilers.obfuscator</string>
<string>Clang LLVM 1.0 Compiler Xcode Plug-in</string> -> <string>Obfuscator Xcode Plug-in</string>

Then:

$ sudo plutil -convert binary1 Info.plist
$ cd Resources/
$ sudo mv Clang\ LLVM\ 1.0.xcspec Obfuscator.xcspec
$ sudo vim Obfuscator.xcspec

Change:

Identifier = "com.apple.compilers.llvm.clang.1_0"; -> Identifier = "com.apple.compilers.llvm.obfuscator.3_4";
Name = "Apple LLVM 5.1"; -> Name = "Obfuscator 3.4";
Description = "Apple LLVM 5.1 compiler"; -> Description = "Obfuscator 3.4";
Vendor = Apple; -> Vendor = HEIG-VD;
Version = "5.0"; -> Version = "3.4";
ExecPath = "clang"; -> ExecPath = "/path/to/obfuscator_bin/clang";

Then:

$ cd English.lproj/
$ sudo mv Apple\ LLVM\ 5.1.strings "Obfuscator 3.4.strings"
$ sudo vim Obfuscator\ 3.4.strings 

Change:

"Name" = "Apple LLVM 5.0"; -> "Name" = "Obfuscator 3.4";
"Description" = "Apple LLVM 5.0 Compiler"; -> "Description" = "Obfuscator 3.4";
"Version" = "5.0"; -> "Version" = "3.4";
"Vendor" = "Apple"; -> "Vendor" = "HEIG-VD";

---

Now, you can open Xcode and set the new compiler in your project settings:

And you can add your obfuscation flags to the CXXFLAGS or CFLAGS like that: