Oxfuscator

From RemObjects Wiki
Jump to: navigation, search

Contents

Concepts

Oxfuscator - is an assembly obfuscation tool for .NET, integrated into the Visual Studio IDE and the MSBuild environment, which allows to make obfuscation be a part of the regular compile cycle.

This tool is based on open-source project - Obfuscar which uses Mono’s Cecil library reader/writer for .NET assemblies. Obfuscar is a command line application. And Oxfuscator is a next generation – tool which embeds Obfuscar functionality into diffrent .NET IDE's (Visual Studio for now, MonoDevelop in future) which makes obfuscation more easy to apply.

How to use

Let's look at Oxfuscator in Visual Studio. It goes as a standalone project type (like Embarcadero Prism or C# projects). You can found it in “Add | New Project” dialog.

Oxfuscator-1.png

This project doesn’t contain any code, but can has references to assemblies should to be obfuscated (look at “Assemblies to Obfuscate” item: this node works like the “References” node in language projects (You can reference any assemblies, registered with the .NET framework, browsed from disk and other language projects from the same solution as well), and You can use it to configure the assemblies, Oxfuscator will work on. Adding references goes in common way – right-click on “Assemblies to Obfuscate” item (or project item itself) and select “Add Reference…” from context menu.

Once you add assemblies, build Oxfuscator project to obfuscate them. The Oxfuscator is integrated with MsBuild so you don’t take care of prebuilding referenced projects. It runs only after all the projects, it depends on, have been built.

Oxfuscator-2.png

Customization

As a result of Oxfuscator’s successful build you will get new assemblies with the same functionality as old ones. But all shared names will be obfuscated, according to the rules you defined. Obfuscation customization goes through Oxfuscator project’s property pages (You can get to it with “Project | Project Properties…” main menu item). There are three property pages.

  • Exclusion
  • Obfuscation
  • Build

Two of them are configuration independed (“Exclusion” and “Obfuscation”) and “Build” property page is assigned to project configuration (you can have different values on this page for different configurations such as “Debug”, “Release” etc.).

Exclusion Property Page

Most projects have to interact with external libraries and so certain classes and class members should to be excluded from obfuscation to keep things working. There are two ways to do this. It’s possible to decorate classes or class members with the [System.Reflection.Obfuscation (Exclude := true)] (you can omit Exclude := true instruction as “Exclude” have TRUE as a default value, but it makes your code clearer to understand) attribute, if you have access to the code. Or you can use “Exclusion” property page to exclude needed classes, class members and even namespaces.

Oxfuscator-3.png

If item checked – it will be obfuscated, otherwise – it’s not. Be advice, unselecting namespace item makes all it classes excluded from obfuscation despite of selecting internal stuff. But classes and class members are independed (if class is unselected, but some class members are selected – class name will not be obfuscated, but not it members).

Obfuscation Property Page

This page allows you to make some additional obfuscation’s customization.

Oxfuscator-4.png

  • Marked Only. This option, when is selected, force Oxfuscator to ignore “Exclusion page” items and take care of only “marked” classes and class members – items which is decorated with [System.Reflection.Obfuscation] attribute.
  • Rename Properties. Turn this option ON, if you want to rename properties. Otherwise, they will not be obfuscated despite of “Exclusion page” customization.
  • Rename Events. Turn this option ON, if you want to rename events. Otherwise, they will not be obfuscated despite of “Exclusion page” customization.
  • Key File. If assemblies selected to obfuscate are signed, you should provide .snk file to make obfuscation successful.
  • Extra Framework Folders. Oxfuscator requires all assembly references to be loadable. Specify paths to folders to be sure all references will be resolved.

Build Property Page

“Build Page” is configuration dependable, so all options you have there can be varied by configuration (“Debug, “Release”, etc.). For example, you can specify one options for your product release (for example, turn on “Use Unreadable Names”) and another – while on beta testing (for example, turn off “Use Unreadable Names”, because it makes call stack useless).

Oxfuscator-5.png

  • Output Path. Specify destination folder for obfuscated assemblies there.
  • Log File Name. On successful build, Oxfuscator generates file which contains mapping between initial classes and class members and obfuscated ones. You can look in it “who became who”. Specify file name for such log file with this option.
  • Reuse Names. If TRUE, Oxfuscator will reuse names when possible. So you can get, for example, type named A.A or so. Set this to FALSE if you will use XML serialization.
  • Use Unreadable Names. If TRUE, Oxfuscator will use Unicode characters, which are legal for naming, but don't usually display in reflectors.
  • Hide Strings. If set to TRUE, Oxfuscator will hide all string constants by replacing the string load (LDSTR opcode) by calls to methods which return the string from a buffer. Of course, it costs some CPU time, but makes reverse engineering more complicated.