PreEmptive Protection - Dotfuscator 4.31
User Guide

The Renaming Editor

The Renaming editor displays three configuration tabs: the Exclude tab, which is used to graphically set custom exclusion rules, and the Options tab, which is used to configure other options related to renaming; the Built-in Rules tab, which is used to perform common renaming exclusions without having to write custom rules.

Note: For new projects, the default setting for the Renaming transform is Enabled.

The Rename Options Tab

The Rename Options tab is used to set renaming options and identify map files to be used for incremental obfuscation.

The Renaming Option section contains three checkboxes used to select or deselect the Enhanced Overload Induction, Keep Namespace, and Keep Hierarchy options.

You can select your preferred Renaming Scheme from the dropdown list. The predefined renaming schemes are described in Renaming Schemes.

Checking the Randomize name assignment checkbox will assign the new names in a non-linear order. So instead of assigning Lower Alpha names in the order {a, b, c, d,...}, you would get something more like {u, p, k, f,...}. This option will work with any Renaming Scheme.

Checking the Compatibility with XML serializer checkbox adds additional rules to the renamer. All classes and members will be renamed in a way that allows XML Serialization. See XML Serialization and Renaming.

Checking the Introduce explicit method overrides when renaming checkbox allows overriding methods to have different names from those of the methods they override.

You can select a rename prefix by checking the Rename Prefix checkbox. The text that you enter in the textbox is added to the beginning of every obfuscated type name. If you do not enter any text, Dotfuscator selects a prefix for each input module, based on the module name. See Renaming Prefixes for more information about renaming prefixes.

The Map Input File section allows you to specify a map file from a previous run so that the naming scheme is retained across successive Dotfuscator runs, a process known as Incremental Obfuscation. Specific details of this feature are presented in the Incremental Obfuscation section. Two approaches are available. If you know the name and path of the mapping file you want to use, you can type it directly into the edit box. Alternatively, you can browse your file system for the intended file location. The Browse button on the right of the edit box brings up the Select Map Input File window that provides a familiar navigational dialog.

For ease of navigation, this screen has a note marked with an asterisk (*) at the bottom reminding you that the Map Output File is configured on the Renaming Reports Tab located in the Settings Tab.

Enhanced Overload-Induction Method Renaming

Dotfuscator extends Overload-Induction™ by allowing a method’s return type or a field's type to be used as a criterion in determining method or field uniqueness. This feature allows up to 15% more redundancy in method and field renames. In addition, since overloading on method return type or field type is not allowed in source languages such as C# and VB, this further hinders decompilers.

This feature also relies on compile-time analysis of your application. Therefore, remote method calls cannot use this feature because remoting throws an ambiguous match exception when calling a method on a remote object that differs only by the return type from another method of the type. Therefore, when using remoting, you have two options. First, do not use enhanced overload induction; normal overload induction will still occurs and is perfectly safe. Second, exclude remotely called classes from renaming. Because of the risks involved in using this option with remoting, this feature is turned off by default.

For similar reasons, Enhanced Overload Induction is automatically suppressed on all types marked as serializable. If this is not the desired behavior, then the default can be changed by adding the "enhancedOIOnSerializables" option to the renaming section of the configuration file (see renaming options), or by checking the Include serializable types in Enhanced Overload Induction box on the Renaming Options tab in the user interface.

Class Renaming Options

Full Class Renaming

The default methodology renames the class and namespace name to a new, smaller name. The idea behind this is quite simple. Our example becomes:

Original Name New Name
Preemptive.Application.Main a
Preemptive.Application.LoadData b
Preemptive.Tools.BinaryTree c
Preemptive.Tools.LinkedList d

Note: All classes are now in the <global> namespace.

Keepnamespace Option

This methodology is excellent as a way to hide the names of your classes while maintaining namespace hierarchy. You give up some size reduction and obfuscation potential, but preserve your namespace names. This is useful for libraries that may be linked to obfuscated code, or for applications that use already obfuscated code. An example of this type of renaming is:

Original Name New Name
Preemptive.Application.Main Preemptive.Application.a
Preemptive.Application.LoadData Preemptive.Application.b
Preemptive.Tools.BinaryTree Preemptive.Tools.a
Preemptive.Tools.LinkedList Preemptive.Tools.b

Note: Keepnamespace and Keephierarchy are mutually exclusive options.

Keephierarchy Option

This option tells Dotfuscator to preserve the namespace hierarchy, while renaming the namespace and class names. For example:

Original Name New Name
Preemptive.Application.Main a.a.a
Preemptive.Application.LoadData a.a.b
Preemptive.Tools.BinaryTree a.b.a
Preemptive.Tools.LinkedList a.b.b

Note: KeepNamespace and KeepHierarchy are mutually exclusive options.

Renaming Prefixes

In some cases it is desirable to have unique top level type names across assemblies, even if those type names are not visible outside their defining assemblies. This is done by running all assemblies through Dotfuscator at the same time. As this approach is not always feasible, Dotfuscator provides a way to enforce uniqueness even across runs, using a renaming prefix.

Renaming prefixes are appended to top level renamed type names. You can specify your own renaming prefix that will be used for all assemblies in a given Dotfuscator run, or you can allow Dotfuscator to pick a prefix for you, based on the type's module name.

One interesting application of this feature is namespace induction. By defining a custom renaming prefix that ends with a ".", (e.g. "MY_PREFIX."), you can place your obfuscated types in a custom defined, common namespace.

Examples:

Original Name Prefix Type Renaming New Name
Application.Main [default] default MyApplicationa
Application.LoadData myprefix default myprefixa
Tools.BinaryTree myprefix keephierarchy a.myprefixa
Tools.LinkedList myprefix keepnamespace Tools.myprefixa
Tools.Proxy mynamespace. keepnamespace Tools.mynamespace.a

There are three ways you can configure renaming prefixes for your project:

  • Using the GUI, check the Rename Prefix checkbox on the Rename Options subtab. If you want to manually specify the prefix, type it in the text box; otherwise leave it blank to have Dotfuscator generate the prefix.
  • On the command line, use the /prefix:[on > off] option. To specify a custom prefix from the command line, use the /p option to define a property named "prefix".

Prefix On:

Dotfuscator /p=prefix=MY_PREFIX /pref:on [other options...]
  • Using a text or XML editor, manually add an option called "prefix" to the renaming section. To define a custom prefix, add a "prefix" property in the propertylist section, with your custom string.

Define a Custom Prefix:

  <propertylist>
     <!-- defining prefix here tells the renamer to use the value as the
        renaming prefix, if renaming prefix is enabled -->
     <property name="prefix" value="MY_PREFIX"/>
  </propertylist>
  <renaming>
     <!-- this turns on the renaming prefix feature -->
     <option>prefix</option>
  ...
  </renaming>

XML Serialization and Renaming

Dotfuscator allows you to globally switch the renaming algorithm to rename classes and members in a way that is compliant with the XML Serializer. If you intend for fully obfuscated classes to be serialized by your application, then run the renamer in this mode; this mode is not required if you are excluding serializable classes from renaming.

Here is a list of rules the renamer follows when running in this mode:

  • Enhanced Overload Induction is turned off.
  • Public instance properties and fields within all types are given names that are unique up and down the inheritance hierarchy.
  • Property metadata is preserved on properties decorated with any attribute in the System.Xml.Serialization namespace.
  • On public types that implement the System.Collections.ICollection interface, the Add method is excluded from renaming and Property metadata is preserved on the Item property.
  • On public types that implement the System.Collections.IEnumerable interface, the Add and GetEnumerator methods are excluded from renaming.

See renaming options for the configuration option that sets this mode. From the user interface, you can set this mode in the Renaming Options Tab.

Introduce Explicit Method Overrides When Renaming

This functionality lets Dotfuscator rename more methods by allowing it to introduce explicit (i.e. non-syntactic) method overrides. In other words, overridden methods can have different names than the methods they override. For example, ordinarily, if a method overrides Object.ToString(), Dotfuscator would not be able to rename it without breaking the override relationship, since typically the Object class is not in an input assembly and therefore its ToString() would not be renamed. With this setting, Dotfuscator can rename the overriding method and introduce metadata that tells the CLR that the method is meant to override Object.ToString().

Original Name New Name
System.Object.ToString() ToString() [class not in input assembly]
Preemptive.MyClass.ToString() a()

Please refer to the .NET Framework documentation for a full description of the regular expression syntax.

The Rename Exclude Tab

The Rename Exclude Tab gives you complete granular control over all parts of your program that you may wish to exclude from the renaming process.

You may exclude specific items from renaming by browsing the tree view of your application and checking the items you want to exclude. In addition, you may visually create your own custom rules for selecting multiple items for exclusion.

To help you fine-tune your exclusion rules, you can preview their effects at any time. The application tree view shades all items selected for exclusion. You can preview the cumulative effects of all rules, or preview a specific rule that you select.

See the section on Using the Graphical Rules Editing Interface for detailed information about working with Inclusion and Exclusion Rules.

See the section below on Renaming Exclusion Rules for a detailed discussion of renaming exclusion rules.

Renaming Exclusions

The exclude list section provides a dynamic way to fine tune the renaming of the input assemblies. The user specifies a list of rules that are applied at runtime. If a rule selects a given class, method, or field, then that item is not renamed.

These rules are applied in addition to rules implied by global options such as library.

Rules are logically OR-ed together.

Regular Expressions (REs) may be used to select namespaces, types, methods or fields. The optional regex attribute is used for this purpose. The default value of regex is false. If regex is true then the value of the name attribute is interpreted as a regular expression; if it is false, the name is interpreted literally. This is important since regular expressions assign special meaning to certain characters, such as the period.

Here are some examples of simple regular expressions:

.*                  Matches anything
MyLibrar.           Matches MyLibrary, MyLibrari, etc.
My[\.]Test[\.]I.*   Matches My.Test.Int1,My.Test.Internal, etc.
Get.*               Matches GetInt, GetValue, etc.
Get*                Matches Ge,Get,Gett,Gettt, etc.

The Rename Built-In Rules Tab

Dotfuscator’s renaming Built-In Rules tab displays renaming exclusion rules defined in %ProgramData%\PreEmptive Solutions\Common\dotfuscatorReferenceRule_v1.4.xml. These rules are standard exclusions that apply to specific application types or technologies. Each rule has a description that displays on the form when the rule is selected. You can apply a built-in rule to your project by checking its checkbox.

Dotfuscator Version 4.31.0.6091. Copyright © 2017 PreEmptive Solutions, LLC