Recipe13.12.Providing Guidance to Obfuscators

Recipe 13.12. Providing Guidance to Obfuscators

Problem

You need to configure Dotfuscator (or another type of compatible obfuscator utility) to operate independently on a number of assemblies, but you do not want to manually have to create a configuration file for each unique assembly configuration.

Solution

Use the ObfuscateAssembly and/or Obfuscation attributes in the System.Reflection namespace. The ObfuscateAssembly attribute can be used to indicate how to obfuscate the entire assembly:

 [assembly: ObfuscateAssembly(true)]

Use the Obfuscation attribute on an assembly, on a type, or on the members of a type to gain a fine-grained control over what is obfuscated and what is not:

 // Obfuscate this class and all of its members. [Obfuscation(ApplyToMembers = true, Exclude = false)] public class ObfuscatedCls() {…}

You can use this attribute at the assembly level, but you lose the ability to indicate whether or not this assembly is public or private, which affects how the obfuscator will handle the types and members of those types in the assembly. It is better to use the ObfuscateAssembly attribute at the assembly level and indicate whether or not this is a public or private assembly in its constructor. The Obfuscation attribute can then be used to tweak how the obfuscator utility will handle individual types and members of the assembly.

When using these attributes, you will typically want to add the ObfuscateAssembly attribute to each assembly that will be obfuscated. Next, you will want to add any Obfuscation attributes to indicate which types and/or members will be excluded from obfuscation.

Discussion

The true value that is passed in to the ObfuscateAssembly attribute's constructor indicates that this assembly is a private assembly, one that will be used by a single application only. Setting this option to TRue indicates to the Dotfuscator utility to do the following:

Everything is renamed except for methods that override methods that exist outside this assembly.
Property and event metadata is removed.
Pruning rules for the professional version:
Included classes, methods, and fields are not removed.
Methods that act as entry points to your .exe or .dll are not removed.
Classes, members, and fields that will not be renamed will also not be removed.
Unreachable classes, fields, and methods are removed.

Setting this value to false indicates to the Dotfuscator utility to do the following:

Public outer and nested class names are not modified.
Public, protected, and internal protected member names of public classes are not modified.
No virtual methods are modified.
No property and event metadata is modified.
Pruning rules for the professional version:
Public classes are never removed.
Public, protected, and internal protected fields of public classes are not removed.
Public, protected, and internal protected methods of public classes are not removed.
Entry points and their called methods are not removed.

You can force the ObfuscateAssembly attribute to not be removed after obfuscation occurs by setting a named parameter StripAfterObfuscation to false (by default it is set to TRue):

 [assembly: ObfuscateAssembly(true, StripAfterObfuscation=false)]

Typically you want to set this parameter to false only when this attribute is applied to a .dll that will be obfuscated as part of an application that uses this .dll.

The ApplyToMembers named parameter on the Obfuscation attribute indicates whether or not this attribute is also applied to the members within this type. The following code will obfuscate the ObfuscatedCls class and all of its members.

 [Obfuscation(ApplyToMembers = true, Exclude = false)] public class ObfuscatedCls() {…}

However, you can place this same attribute on a member of the ObfuscatedCls class with the Exclude named parameter set to true to override the outer Obfuscation attribute.

You should be aware that by applying these attributes you are only providing configuration information to the obfuscator utility. These attributes will not actually obfuscate your assembly.

If you are using Dotfuscator, you need to allow it to use these attributes by setting the Honor Obfuscation Attributes button to enabled.