Declarative Obfuscation using Custom Attributes

Article
06/18/2008

The .NET Framework version 2.0 provides two new custom attributes designed to make it easy to automatically obfuscate assemblies without having to set up configuration files. This section outlines how you can use these attributes with Dotfuscator. It is assumed that you are familiar with custom attributes and how to apply them in your development language.

System.Reflection.ObfuscateAssemblyAttribute

This attribute is used at the assembly level to tell Dotfuscator how to obfuscate the assembly as a whole. Setting the AssemblyIsPrivate property to false tells Dotfuscator to run the assembly in library mode. If you set it to true, Dotfuscator will not run the assembly in library mode and will rename as much as possible, including public types and members.

System.Reflection.ObfuscationAttribute

This attribute is used on types and their members and tells Dotfuscator how to obfuscate the item.

Feature Property

This string property has a default value of "all". This property is provided so that you can configure multiple obfuscation transforms independently by tagging an item with multiple ObfuscationAttributes, each with a different feature string.

Dotfuscator maps the "default" and "all" feature strings to "renaming".

Here is a list of other feature strings that Dotfuscator understands.

Feature String	Action
renaming	attribute configures renaming
controlflow	attribute configures control flow obfuscation.
stringencryption	attribute configures string encryption
trigger	attribute configures pruning by marking the annotated item as an entry point
conditionalinclude	attribute configures pruning by conditionally including the annotated item

If necessary, you can map other feature strings to "renaming" using the "Feature Map Strings" property sheet on the Setup Tab.

Dotfuscator ignores attributes with feature strings that it does not understand.

Exclude Property

This Boolean property has a default value of True. When True, it indicates that the tagged item should be excluded from the transforms implied by the Feature property. When False, it indicates that the tagged item should be included.

The current version of Dotfuscator supports one value of the Exclude property for any given transform. Dotfuscator will ignore rules that have unsupported Exclude values. The following list summarizes.

Feature String	Supported Exclude Value
renaming	True
controlflow	True
stringencryption	False
trigger	False
conditionalinclude	False

ApplyToMembers Property

This Boolean property has a default value of True. When the attribute is applied to an assembly or a type, a True value indicates that the operation should be applied to all the members (including nested types) of selected types as well. If false, the operation is applied to types only and not their members (or nested types).

Enabling or Disabling Declarative Obfuscation

Dotfuscator allows you to switch Declarative Obfuscation on or off for all input assemblies. If not enabled, Dotfuscator will ignore obfuscation related custom attributes. You can also switch it off for specific assemblies.

Stripping Declarative Obfuscation Attributes

Dotfuscator can strip out the obfuscation attributes when processing is complete, so your output assemblies will not contain clues about how it was obfuscated. Both of the declarative obfuscation attributes include a Boolean "StripAfterObfuscation" property whose default value is true

Dotfuscator also has configuration settings that interact with the value of the StripAfterObfuscation property at obfuscation time.

The settings that effect declarative obfuscation attribute stripping and how they interact are summarized in the below table.

Dotfuscator is Honoring Attributes	Dotfuscator is Stripping Attributes	Attribute's StripAfterObfuscation Property	Result
Yes	Yes	True or False	Strip Attribute
Yes	No	True	Strip Attribute
Yes	No	False	Keep Attribute
No	Yes	True or False	Strip Attribute
No	No	True or False	Keep Attribute

Using Feature Map Strings

Dotfuscator allows you to map values contained in an Obfuscation Attribute's Feature property to feature strings that Dotfuscator understands.

For example, you can annotate your application with obfuscation attributes that reference a feature called "testmode". Dotfuscator by default will not understand this feature string; therefore it will ignore the attributes. If later on you want Dotfuscator to use these attributes to configure renaming and controlflow obfuscation, you can map the feature string "testmode" to Dotfuscator's built in "renaming" and "controlflow" strings.

Share via