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.

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 four checkboxes used to select or deselect the Enhanced Overload Induction, Keep Namespace, Keep Hierarchy, and Keep Managed Resource Names 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.

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 occur 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 config 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:

Keep Namespace 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:

Keep Hierarchy Option

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

Keep Managed Resource Names Option

Dotfuscator will automatically rename managed resources that are associated with renamed classes so that they will load correctly at runtime. You should select Keep Managed Resource names if your application loads managed resources by constructing resource names programmatically.

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:

To configure a renaming prefix, 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.

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. You can set this mode in the Renaming Options Tab.

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 the Rules Editor 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 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. 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 enable a built-in rule in your config by checking its checkbox.

The exact definitions of each of these rules can be found in your installation location's Common subdirectory. A typical example is C:\Program Files (x86)\PreEmptive Protection Dotfuscator Professional A.B.C\Common. The rule definitions are found in the XML file with a name beginning with dotfuscatorReferenceRule.