Demeanor for .NET Enterprise Edition Version 5.0 - Release Notes

These release notes provide the most current information about the installation, features, documentation, and known issues for Demeanor for .NET Enterprise Edition Edition and Demeanor for .NET Network edition.

  1. Introduction
  2. Installing Demeanor for .NET
  3. Running Demeanor for .NET
  4. Known Issues
  5. Tips and techniques
  6. Version history


1 Introduction

These release notes provide important information that you should read before installing and using Demeanor for .NET.

 

Demeanor for .NET is an obfuscation utility for .NET assemblies. It is designed to obfuscate as much information in a .NET assembly as possible while allowing the code to run as the developer intended. Demeanor for .NET is extremely configurable so that you can disable obfuscations at a type, method, field, property or event level should the need arise. Demeanor can obfuscate symbols using a number of different techniques allowing you some flexibility with regard to the obfuscated names produced.

 

Wise Owl provides two versions of Demeanor for .NET - the Enterprise Edition and the Network Edition.

 

Demeanor for .NET, Enterprise Edition is the commercial version of our obfuscator that contains all the features of the Personal Edition plus numerous additional features to defeat reverse engineering. The Enterprise Edition renames all possible identifiers in a set of assemblies to meaningless, trivial names using a .NET-specialized algorithm that produces the maximum possible name overloading. By maximizing the name overloading, the Enterprise Edition produces assemblies that are more difficult to reverse engineer and that are significantly smaller than those obfuscated by the Personal Edition. In addition, the Enterprise Edition contains many additional features that protect your assemblies against reverse engineering such as entire application obfuscation, string encryption, metadata obfuscation and removal, incremental obfuscation, unused code and data detection, automatic satellite assembly obfuscation, and more.

 

Demeanor for .NET Network Edition has the same features as the Enterprise Edition but allows Demeanor for .NET to be installed on any number of computers within a corporate network. A network license server restricts the number of concurrent uses of Demeanor for .NET to the limit of network licenses purchased.

 

New and non-breaking changed functionality in this release is indicated in the document using green text.

Breaking changes to previously existing functionality is indicated in the document using red text.


2 Installing Demeanor for .NET

2.1 Software Requirements

Demeanor for .NET requires the following:

Demeanor for .NET can obfuscate assemblies built for .NET 1.0, 1.1, 2.0, 3.0, 3.5 and 4.0.

 

2.2 Recommended Hardware

See the Visual Studio .NET hardware requirements.

 

2.3 Installing Demeanor for .NET

Before installing Demeanor for .NET, you should already have installed the .NET runtime. As Demeanor for .NET is a tool for .NET developers, we do not include a redistributable copy of the .NET runtime.

Demeanor for .NET contains a product activation feature. The first time you run Demeanor for .NET, it displays a window requesting that you activate your specific license for Demeanor for .NET. Activating a license on a system associates that license to that specific machine. You can activate the license immediately if your system has an Internet connection, otherwise you can activate your license by phone of e-mail. You can decline to activate the license and Demeanor for .NET will run using an unactivated license as long as you are within the two week grace period for activation. After the two week grace period, you must activate the license on a particular system in order to use Demeanor for .NET.

 

2.4 Removing Demeanor for .NET

To remove Demeanor for .NET, open Control Panel, double-click Add/Remove Programs, and then click the entry for the version of Demeanor that you have installed, then click Remove.

 

2.5 Running Demeanor for .NET

Demeanor for .NET is a command line utility. The only required command line parameter is the file name of the assembly to obfuscate. The obfuscated version of the assembly, by default, will be placed in a subdirectory of the current working directory named 'Demeanor'.

 

2.6 Beta and trial versions of Demeanor for .NET

Beta and trial versions of Demeanor for .NET will stop working once their evaluation period has expired. Licensed copies of Demeanor for .NET contain no time bomb. Note that Demeanor for .NET is licensed only to a specific developer within an organization. Licenses are not transferable. You need one license for each developer that uses Demeanor for .NET.



 

3 Running Demeanor for .NET

Demeanor for .NET is a command line utility. Run it as follows:

Demeanor <options> <assemblyName>

where the options are listed below and assemblyName is the path to the assembly you wish to obfuscate. The following options are available in both the personal and enterprise editions.

Command line options Description
/all

Obfuscate as many symbols as possible ignoring the visibility of the type.

Normally top-level types with public visibility cannot be obfuscated because a developer defines such a type with public visibility to allow code in a different assembly to bind to the type. The runtime performs this binding using the type name so changing the name would cause this binding to fail. However, some assemblies, typically .EXE assemblies, expect no external assemblies to bind to their public types. (In fact, Visual Studio.NET prevents such a use of an .EXE assembly though it can be done using the compilers at the command line.) Technically, a developer should define all types contained in such an .EXE assembly with internal visibility but they often do not. You typically use the /all option when obfuscating an .EXE assembly to force all types contained in the assembly to be obfuscated regardless of the type's visibility.

/cc This option requests Demeanor for .NET to change the accessibility of obfuscated methods and fields to compiler-controlled (a.k.a. privatescope) accessibility. Using compiler-controlled accessibility strengthens the obfuscation of your assembly in three ways.

First, compiler-controlled accessibility is another lossy transformation. The original accessibility of the member is discarded. A decompiler will have to perform a global data flow analysis over the entire assembly in order to determine the proper accessibility of the obfuscated member.

Second, this accessibility does not exist in high-level languages such as C# and VB.NET. A decompiler will have to synthesize (i.e. make up) a new accessibility for such fields and methods. Without a global data flow analysis, a decompiler will have to assume public or internal accessibility for such members.

Third, the runtime never uses the names of such members. Therefore Demeanor for .NET can assign all compiler-controlled members exactly the same name. The more members using the same name, the smaller the metadata tables, and, therefore, the smaller the resulting assembly.

/exclude:<name>[,name>] This option forces Demeanor for .NET to not obfuscate the specified type or member. Demeanor expects you to specify the type or member name using the ILASM and ILDASM syntax for types and members. For example, when <name> is a top-level type, it should be in the form Namespace.Type. When name is a nested class, it should be in the form Namespace.ContainingType/NestedType and Namespace.ContainingType/NestedType/DoubleNestedType. You can also specify that Demeanor for .NET should not obfuscate a particular member of a type by stating the full name of the member, e.g. Namespace.Type/NestedType::Field and Namespace.Type::Method. Embedded space characters are preserved and are interpreted as part of the type or member name. You can specify multiple names using a comma-separated list. Alternatively, you can specify multiple exclude command line options, each excluding a single name. (Short form /x:)
/help Display usage information to the console (short form /?).
/insitu Forces Demeanor to obfuscate the metadata in situ and leave the rest of the portable-executable (PE) file untouched.

Demeanor normally produces an obfuscated assembly that it has optimized in a number of ways. Demeanor rearranges the code and data structures in the PE file more efficiently than those present in the original assembly. This results, on average, in an assembly that is 8% - 12% smaller than the original, which also downloads faster, loads into memory more quickly, and executes using a more efficient working set.

However, when there is unmanaged code and datain an assembly as well as managed code and data, the unmanaged code and data may require that it loads and executes at the original memory location. In this case, Demeanor must not rearrange the memory layout of the assembly. Compilers that produce assemblies containing unmanaged and managed code (for example, Microsoft's Managed C++) normally flag the assembly to indicate that it contains unmanaged code. Demeanor automatically enables the 'in situ' option when it determines it is obfuscating an assembly that contains both managed and unmanaged code. So, typically, you should never need to specify this option.

However, you can use the ILASM compiler to create an assembly that contains unmanaged code without setting the appropriate flag. In this rare situation, you may need to specify the 'in situ' option.

/keycontainer:<string> Specify a strong name key container.

You can specify the name of the container holding the public and private strong name key pair using this option. Demeanor uses this key container to resign the assembly after obfuscating it. When you specify both the /keycontainer and /keyfile options, Demeanor will use the /keyfile option. Obfuscation modifies an assembly. When the original assembly has a strong name, this modification invalidates any strong name signature in the assembly causing the runtime to treat the assembly as altered. You must resign the obfuscated assembly to update it with the correct strong name signature.

/keyfile:<file> Specify a strong name key file.

You can specify the name of the file holding the public and private strong name key pair using this option. Demeanor uses this key file to resign the assembly after obfuscating it. When you specify both the /keycontainer and /keyfile options, Demeanor will use the /keyfile option. Obfuscation modifies an assembly. When the original assembly has a strong name, this modification invalidates any strong name signature in the assembly causing the runtime to treat the assembly as altered. You must resign the obfuscated assembly to update it with the correct strong name signature.

/out:<directory> Directory in which to place the obfuscated assembly. Demeanor for .NET will create the directory when necessary. The directory cannot be the same as the directory containing the input assembly. When you omit this option, the directory name defaults to 'Demeanor' and the utility creates this subdirectory in the current working directory.
/names:alpha This option forces Demeanor for .NET to use alphabetic Latin characters as the obfuscated names. The first 26 obfuscated names in a scope will be called 'a' through 'z'. The Second 26 names in the same scope will be called 'A' through 'Z'. Then it continues on to produce 'aa', 'Aa', 'aA', 'AA', 'ab', etc. This option produces assemblies with the least number of bytes used for obfuscated names. (This is the default setting.)
/names:numeric This option forces Demeanor for .NET to use digits for the obfuscated names. The first obfuscated name in a particular scope will be '_1', then '_2', and so on.
/names:Unicode This option forces Demeanor for .NET to use high Unicode code points for obfuscated names. In particular, Demeanor for .NET creates names using code points from the Canadian Aboriginal Syllabic character set. Without a font for that character set installed, all such names display as a box.
/nologo Suppress the logo display.

/noenumerations

/noevents

/nofields

/nomethods

/noparameters

/noproperties

/notypes

/noresources

/forceparameters

These diagnostic options allow you to disable all obfuscation of the specified category of types or members. This is useful for diagnosing problems you might encounter when using an obfuscated assembly. For example, if an assembly doesn't work when completely obfuscated but works correctly when you specify the nofields option, it's likely that some logic is late-binding or using Reflection to one or more fields.

Method parameters are normally obfuscated only when the method itself is obfuscated. You can force all parameter names to be obfuscated, for obfuscated and unobfuscated methods, by specifying the /forceparameters command line option. You can prevent all parameters from being obfuscated using the normal /noparameters switch. Note that specifying /noparameters forces the /forceparameters switch off and vice-verse. In other words, only one of these two switches is used and it will be the last one specified on the command line.

/report[:<filename>]

The report option requests Demeanor to create an XML-based obfuscation report file in the output directory. The report lists all types, fields, methods, properties and events in the obfuscated assembly. For each entry, the XML document identifies the original type/member name and metadata values and maps the type/member to its new obfuscated name and metadata values. The default file name is "<assemblyName>Report.xml" in the output directory. (Short form /r[:<filename>]).

The value for a NestedType Name element has changed in this release. Previously, it was the full type name, for example, "a+b+c". Now the value of a NestedType Name element is the simple name of the nested type, for example, "c". The prior qualification was redundant because the element defining the nested type "c" resides in the definition of nested type "b", which itself, resides in the top-level type definition for "a".

/verbose Display obfuscation statistics to the console (short form /v). This option displays the number of types, field, methods, properties and events contained in each module of the assembly as well as the number obfuscated.
/xr:<regex> This option forces Demeanor for .NET to not obfuscate all types and members that match the specified regular expression. The regular expression should match type and member names specified using ILASM and ILDASM syntax. See the /x command line option for examples. The regular expression syntax accepted is described in the .NET Framework SDK documentation at: .NET Framework / Programming with the .NET Framework / Working with Base Types / Manipulating Strings / .NET Framework Regular Expressions (ms-help://MS.VSCC/MS.MSDNVS/cpguide/html/cpconcomregularexpressions.htm).
Enterprise & Network Edition Additional Options Enterprise Edition and Network Edition Command Line Options
/a:<assemblyName>

This option adds an assembly to the set of assemblies obfuscated when you specify the /application command line option. The assemblyName parameter is the display name of the assembly; it is not the file name. For example, you would specify /a:"MyAssembly, Version= 1.0.0.0, Culture= neutral, PublcKeyToken= 0123456789abcdef" not /a:MyAssembly.dll.

An application that dynamically loads one or more private assemblies (for example, "plug-in" assemblies) based on a configuration file, presence in a well-known directory, or some other dynamic resolution scenario might want to use this obfuscation option. Such an application typically does not have a static reference to all possible plug-in assemblies compiled into the application. Therefore, the /application option wouldn't normally obfuscate such assemblies. You can specify the /a command line option one or more times to instruct Demeanor to obfuscate one or more additional assemblies as part of the whole application obfuscation.

/application

This option requests obfuscation of an entire application. Demeanor begins by loading the assembly that you specify on the command line; typically this is an .EXE assembly. Demeanor obfuscates the application plus all dependent private assemblies that are statically referenced by the specified application, plus their statically referenced dependent private assemblies, and so on. Demeanor uses the .NET Framework assembly resolution rules when locating referenced private assemblies. Demeanor will only obfuscate a referenced assembly when it can be loaded from the application's private assembly path. (In other words, Demeanor doesn't process any shared assembly that the application might reference.)

Demeanor recursively processes private assemblies. For example, when the application assembly listed on the command line references private assembly A, and assembly A references private assembly B, Demeanor for .NET will obfuscate all types and members, public and private, in assembly B. Demeanor then updates the references in A so they correctly reference the obfuscated types and members of B. Demeanor then obfuscates the public and private types and members of A, and similarly updates the references in the application assembly so they correctly reference the obfuscated types and members of A. Demeanor then obfuscates the public and private types in the application.

Demeanor places all obfuscated assemblies in the output directory.

/config:<configFile>

This option requests Demeanor for .NET to read one of its previously written report files and use the information in the file when performing the current obfuscation.

Presently, you use this option to request incremental obfuscation on one or more assemblies. Incremental obfuscation causes Demeanor to assign the same obfuscated names to types and members during multiple obfuscation runs. This allows you to obfuscate a new version of an assembly and having previously existing types and members to be assigned to the same obfuscated names as an earlier version. Client applications that reference the obfuscated types and members will continue to work as the types and members in the new assembly have the same names as before.

When Demeanor assigns an obfuscated name to a type or member, it first checks to see if an obfuscated name for the type/member is present in the specified configuration file. When present, Demeanor assign that obfuscated name, when possible, to the type or member. When not present, Demeanor assigns a new obfuscated name to the type or member. When the prior name isn't acceptable during the current obfuscation run, Demeanor displays a warning message on the console and assigns a new, unique obfuscated name to the type or member. Short form (/c:)

/encryptstrings

This option requests Demeanor for .NET to encrypt the literal strings present in the obfuscated assemblies. The presence of clear-text literals in an assembly can provide significant information to someone attempting to reverse engineer an assembly. For example, she could search for a significant literal string, for example "Invalid password", find the method that references the literal and have a good idea on which method to concentrate.

Demeanor for .NET also injects the appropriate decryption code into all methods that reference a string literal. This additional code increases the size of your methods and causes them to run slightly more slowly. (Short form /es)

/flow:<level>

This option requests Demeanor for .NET to obfuscate the control flow of the methods in the obfuscated assemblies. The <level> parameter can be 'None', 'Minimum', 'Moderate' and 'Maximum'. The default value is 'None'. Increasing the level of control flow obfuscation produces more difficult to understand methods. However Demeanor injects additional instructions into your methods to obfuscate the code. These additional instructions increase the size of your methods and causes the methods to run more slowly. (Short form /f:<level>)

/noserializable

When you specify this option, Demeanor does not obfuscate the name of all types to which you have application the [Serializable] attribute. Additionally, Demeanor does not obfuscate the name of any of the fields in such types. However, Demeanor will continue to obfuscate the name of any methods in such types, as appropriate.

When you serialize a type, the .NET runtime writes the name of the type and the names of each of the serialized fields to the output stream. When you obfuscate such types, the output stream contains the obfuscated type and field names. When you want an unobfuscated build and an obfuscated build of your assembly, for example, a Debug and a Release build, to be able to exchange serialized types, it is necessary to use consistent names in the serialized data stream. While you can achieve this using incremental obfuscation and configuration files, this option makes the process much easier. (Short form /noserial)

/hinderreflection[+|-]

By default, Demeanor injects additional metadata into an obfuscated assembly that hinders the ability of Reflection based tools to decompile the assembly. The /hinderreflection- option prevents Demeanor from injecting this additional metadata.

/prefix:<value>

The /prefix:<value> option allows you to specify a namespace prefix that Demeanor will prepend to each obfuscated top-level type name. For example, when you specify the -prefix:WiseOwl command line option, the top-level obfuscated type names will be, by default, WiseOwl.a, WiseOwl.b, WiseOwl.c and so on.

/satelliteassemblies[:<culture>[,<culture>]*]

The satelliteassemblies option request Demeanor to update the names of managed resources in culture-specific satellite resource assemblies. You can specify the exact culture-specific satellite assemblies to update using this command line option multiple times or by listing a comma-separated list of cultures on a single command line option.
(Short form /sa:[<culture>[,<culture>]*])

/suppressildasm[+|-]

By default, Demeanor injects additional metadata into an obfuscated assembly that suppresses decompilation of the assembly by ILDasm. The /suppressildasm- option prevents Demeanor from injecting this additional metadata, which allows decompilation by ILDasm.

/xa:<assemblyName>

This option excludes an assembly from the set of assemblies obfuscated when you specify the /application command line option. The assemblyName parameter is the display name of the assembly; it is not the file name. For example, you would specify /a:"MyAssembly, Version=1.0.0.0, Culture=neutral, PublcKeyToken=0123456789abcdef" not /a:MyAssembly.dll.


4 Known Issues

4.1 None

There are no known issues with the latest version of Demeanor for .NET. However, we continually upgrade our product so check back occasionally to review the latest release notes.


 5 Tips and techniques

5.1 The ResourceManager, Reflection and managed resources

Some parts of the .NET Framework Class Libraries use Reflection to determine the name of a type at runtime. They then use the name is various ways to locate other data. When such code uses a type that has been obfuscated, it may not be able to find the other data it needs when the code locates the other data by comparing names.

For example, the Visual Studio.NET Form Designer generates the following code in the InitializeComponent method.

System.Resources.ResourceManager resources = new System.Resources.ResourceManager (typeof(MainForm));

This ResourceManager constructor usage tells the resource manager to infer the assembly, the base name, and a namespace for .resources files from the constructor's Type argument. The ResourceManager assumes you will be using satellite assemblies and want to use the default ResourceSet class. Given a full type name such as MyCompany.MyProduct.MainForm, the ResourceManager will look for a .resources file (in the main assembly and satellite assemblies) named "MyCompany.MyProduct.MainForm.[culture name.]resources" in the assembly that defines MainForm. However, once Demeanor obfuscates the name of the type, for example, to 'Aa', the resource manager will look for a .resources file (in the main assembly and satellite assemblies) named "Aa.[culture name.]resources" in the assembly that defines MainForm.

Demeanor looks for managed resources in an obfuscated assembly that have the same name as an obfuscated class name with the addition of the ".resources" suffix. When it finds such a resource, Demeanor changes the name of the resource to be the obfuscated class name plus a ".[culture name.]resources" suffix. This means that the ResourceManager's previously described behavior continues to work correctly on an obfuscated class and its resource.

Demeanor, by default, does not try and update the names of resources in culture-specific satellite assemblies. Unfortunately for Demeanor (but fortunately for you as a developer), there is no information in a primary assembly that describes what, if any, satellite assemblies exist that are associated with the primary assembly. This is good for you as a developer because it allows you to create additional satellite resource assemblies, deploy them into the appropriate culture-specific subdirectory of the primary assembly's directory, and the Runtime will automatically use the new satellite assembly as required -- all without any need to recompile or redeploy the primary assembly.

However, you can request that Demeanor update all culture-specific satellite resource assemblies by using the -satelliteassemblies command line option. For example, the following command line requests Demeanor obfuscate the specified assembly, then find all installed culture-specific satellite resource assemblies and update the names of their resources.

Demeanor -sa MyAssembly.exe

In the above example, Demeanor would update the French satellite resource assembly (fr\MyAssembly.resources.dll) and the German satellite resource assembly (de\MyAssembly.resources.dll) if they are present (specified relative to the location of the MyAssembly.exe file) and place the obfuscated satellite resource assemblies in the same subdirectory relative to the Demeanor output directory. In this example, the output directory defaults to "Demeanor" so the three obfuscated assemblies would be placed in "Demeanor\MyAssembly.exe", "Demeanor\fr\MyAssembly.resources.dll" and "Demeanor\de\MyAssembly.dll".

Because there is no information in an assembly that describes which cultures the assembly supports, when you specify the -satelliteassemblies command line option without any cultures, Demeanor searches for all 202 possible culture-specific satellite resource assemblies. When you additionally request entire application obfuscation using the -app command line option, Demeanor search for each of the 202 possible culture-specific satellite resource assemblies for each assembly in the entire application. There are, by default, four locations in which a satellite resource assembly can be placed. This is a lot of searching for assemblies that frequently are not present. However, it does make Demeanor easy to use and it automatically finds and obfuscates new culture-specific resource assemblies as you create them.

However, if you have a fixed, known set of cultures that you support, you can have Demeanor more efficiently look for and obfuscate only the satellite resource assemblies for the specific cultures. For example, the following two command lines are effectively identical and each requests Demeanor to obfuscate the specified assembly plus its French and German satellite resource assemblies.

Demeanor -sa:fr -sa:de MyAssembly.exe
Demeanor -sa:fr,de MyAssembly.exe

You can theorectically have a resource that has a name that matches an obfuscated class name without there being any implied relationship between the resource and the class. In this case, you may want to disable Demeanor's automatic renaming of the resource. You can globally disable this automatic resource renaming using the -noresources command line option. Alternatively, you can specify the name of the resource as an item to exclude using either the /x or /xr command line options.

 

5.2 Examples of regular expression exclusions

You can specify the /xr (exclude using regular expression) switch as often as needed on the command line to specify multiple exclusion patterns.

The following regular expression excludes the type "Namespace.Type" as well as the members of the type:

/xr:Namespace\.Type(::.+)?

The following regular expression does not exclude the type itself but does exclude all members of the type "Namespace.Type".

/xr:Namespace\.Type::.+

This regular expression excludes the type itself but does not exclude all members of the type "Namespace.Type". Of course, in this case, it's easier just to use the exclude (-x) command line switch.

/xr:Namespace\.Type$

Demeanor supports the regular expression syntax used by the classes in the System.Text.RegularExpressions namespace.

5.3 Examples of entire application obfuscation

Demeanor for .NET, Enterprise Edition feature.

You can specify the /app command line option to request Demeanor to obfuscate the assembly specified on the command line (called the root assembly) plus all of its dependent assemblies. Demeanor searches the root assembly's private path and only obfuscates the dependent assemblies that reside on the private path. Typically, this means Demeanor obfuscates the root assembly plus any dependent assemblies located in the same directory as the root assembly.

For example, consider the case where assembly Client.exe requires private assembly MyLib.dll and both files reside in the same directory.

The following command line obfuscates the public and internal symbols in MyLib.dll, changes Client.exe to reference the public types in MyLib.dll using their new obfuscated names, then obfuscates the internal types of Client.exe leaving its public types unchanged.

Demeanor -app Client.exe

Normally, Demeanor will not obfuscate the public types of an assembly unless it can also modify all references to those public types to use the new, obfuscated type names. This means the public types of the root assembly never get obfuscated by default, as there may exist other assemblies that reference the public types in the root assembly. Typically, you will not have any references to the public types in an .exe assembly so you can modify the above example to obfuscate all types in both assemblies using the following command line. The -all option requests Demeanor to obfuscate the public types of the specified root assembly.

Demeanor -app -all Client.exe

Some applications dynamically reference assemblies. For example, an application could read a configuration file and dynamically load one or more optional "plug-in" assemblies. During entire application obfuscation, Demeanor creates a list of all assemblies statically referenced by the root assembly. Demeanor then recursively adds to the list all assemblies referenced by assemblies in the list that are present in the private path. In other words, Demeanor creates a list of all statically referenced assemblies used directly or indirectly by the root assembly and obfuscates the ones present in the private path. You can add additional dynamically referenced assemblies to this list to have them obfuscated as part of the entire application obfuscation processing.

Here is one example where this is useful. Your application dynamically loads "plug-in" assemblies. Your application statically references an interface assembly. The plug-in assembly also statically references the interface assembly. the application never statically references any types in the plug-in assembly. Entire application obfuscation of your client will obfuscate the client and the interface assembly. However the plug-in assembly references types in the interface assembly that have been obfsucated. You need the plug-in assembly to be updated to use the new obfuscated type names and for the plug-in assembly itself to be obfuscated. Use the -a command line option to add the plug-in assembly to the set of assemblies processed by entire application obfuscation. For example, to include the assembly Plugin.dll, use its display name like this:

Demeanor -app -all -a:"Plugin, Version=1.0.0.0, Culture=neutral, PublicKeyToken= 0123456789abcdef" Client.exe

Demeanor always needs to load all assemblies referenced directly or indirectly from every assembly that it obfuscates. However, when Demeanor loads assemblies, it places the assembly into one of two categories: assemblies to be obfuscated and assemblies used for reference only. Demeanor always places the assembly that you specify on the command line into the "to be obfuscated" category. In addition, Demeanor also places all assemblies that you specify with the /a command line option into the "to be obfuscated" category. Additionally, when Demeanor asks the runtime to load an assembly and the assembly loads from the same directory as the assembly that you specify on the command line (or one of its subdirectories), Demeanor adds the assembly to the "to be obfuscated" category.

Demeanor assumes that assemblies that load from the private path are part of the application, therefore should be obfuscated during entire application obfuscation. Conversely, Demeanor places all assemblies that load from outside of the private path, for example, from the Global Assembly Cache, or elsewhere due to a codebase assembly redirect, into the "for reference only" category and doesn't obfuscate them. Usually, this is exactly the behavior you want. Demeanor obfuscates your application assemblies but doesn't change mscorlib, System.Windows.Forms, or similar assemblies.

Occasionally, you may have an assembly in the private path but not want Demeanor to obfuscate it. A common example is when your application uses a third-party strong-named assembly that you deploy privately with your application. You cannot include the assembly in entire application obfuscation because obfuscating it invalidates its strong name. In this case, you can specify the /xa command line option. Demeanor will then categorize this assembly as one to be used "for reference only" and therefore not obfuscate it.

Demeanor -app -all -a:"Plugin, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0123456789abcdef"
                   -xa:"ThirdParty, Version=2.3.0.0, Culture=neutral, PublicKeyToken=0123456789abcdef" Client.exe

 

5.4 Examples of string encryption obfuscation

Demeanor for .NET, Enterprise Edition feature.

The first technique used by someone attempting to reverse engineer your application is to look at the string literals of the program, find an interesting string, locate the code that uses the string and concentrate on that code. Demeanor allows your to make the search for interesting string literals more difficult by encrypting the string literals in the obfuscated assemblies. You can specify the /es command line option to request Demeanor to encrypt the literal strings in the obfuscated assemblies.

Demeanor -es -app -all Client.exe

 

5.5 Examples of incremental obfuscation

Demeanor for .NET, Enterprise Edition feature.

Specify a report file from a prior Demeanor obfuscation run as the input to a subsequent obfuscation run and Demeanor will assign types and members the same obfuscated name as they had in the prior run.
Demeanor -c:MyAssembly.xml MyAssembly.dll

You can also use this feature to control exactly what names are assigned to each type and member in each assembly in the obfuscation. However, there can be cases where Demeanor cannot assign the requested name to a type or member. Here's exactly how this feature works.


In addition to incremental obfuscation, you can also use this feature to assign any desired name to any type or member, within the above constraints. For example, you can specify the original type/member name as the obfuscated name. In effect, this says "Do not obfuscate this name" and is equivalent to excluding the symbol from obfuscation.

 

5.7 The -noserializable option

Demeanor for .NET, Enterprise Edition feature.

When you use the .NET Runtime's binary serialization functionality, the runtime writes the serialized state of an object to a stream. This information includes the type name of the serialized instance plus the name of each of the serialized fields and their values. .NET determines the type name and the field names at runtime, therefore when serializing an obfuscated type, the names saved to the stream are the obfuscated names. Some developers want to serialize a non-obfuscated type instance and deserialize the data into an obfuscated version of the same type, or vice-versa. Normally this doesn't work because the serialized type name and serialized field names aren't identical in the obfuscated and unobfuscated code. It's easy to work around this issue with the field names. You simply implement the ISerializable interface on the type and you have full control over the serialized field names. However, this still leaves the type name itself as a problem.

You can exclude a type name from obfuscation but, when you have numerous serializable types, this can become tedious. The -noserializable option requests Demeanor to never obfuscate the name of any type with the [Serializable] attribute. In addition, Demeanor will not obfuscate any serializable field of a serializable type. Demeanor obfuscates all other members of a serializable type normally. For example, given the follow class:

[Serializable]
internal class MyClass {
  private string m_MyField;
  
  [NonSerialized] private int m_NotSerialized;
  
  public string MyField {
    get { return m_MyField; }
  }
  
  public void Method1 (string s) { ... }
  private int Method2 (string s) { ... }
}

When you specify the -noserializable option and obfuscate this class, Demeanor translates it to the following:

[Serializable]
internal class MyClass {
  private string m_MyField;

  [NonSerialized] private int a;
  
  public string a() { ... }
  
  public void b(string) { ... }
  private int c(string) { ... }
}

However, when you do not specify the -noserializable option and obfuscate this class, Demeanor translates it to this instead:

[Serializable]
internal class a {
  private string a;

  [NonSerialized] private int b;
 
  public string a() { ... }
  
  public void b(string ) { ... }
  private int c(string ) { ... }
}

 

5.8 Obfuscating smart device applications that use the .NET Compact Framework

When Demeanor obfuscates an assembly/application, Demeanor establishes a runtime environment exactly like the assembly/applicaiton would have when it loads/runs normally. Demeanor then determines the dependent assemblies used by the application, and asks the .NET Framework to load each one. Demeanor operates this way for two reasons. First, Demeanor must read each dependent assembly in order to understand every data type used directly or indirectly by an assembly that Demeanor obfuscates. Second, it must ask the .NET Runtime to load the assembly, rather than load a particular file, because the .NET Runtime occasionally loads a different assembly than the one your application requests. Obfuscators that work based on file names fail to handle this assembly redirection properly, which also means they cannot obfuscate your applications correctly.

When obfuscating a Win32 application, the runtime typically finds these dependent assemblies without problem. Your dependent private assemblies reside in the same directory as the application itself, so the runtime can find them. System assemblies such as mscorlib and System.Windows.Forms reside in the Global Assembly Cache (GAC) therefore the runtime can also find those assemblies. However, when you build a smart device .NET application, the compiler compiles against special versions of many of the standard .NET Runtime assemblies. These assemblies have a different strong name than the Win32 .NET Framework assemblies. When Demeanor asks the .NET Runtime to load these assemblies, the .NET Runtime cannot find the assemblies as they aren't present in the GAC, which is understandable as they normally aren't used by applications running on Windows.

On a development machine, these .NET Compact Framework assemblies normally reside in a Visual Studio installation directory, for example C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE. This allows you to compile against these assemblies but they aren't normally considered when the .NET Runtime needs to load one of the assemblies. For Demeanor to obfuscate a smart device application, you must create an application configuration file that informs the .NET runtime of the location of each of the assemblies in the Windows CE directory. Then, when Demeanor obfuscates your application and it asks the .NET Runtime to load the dependent assemblies, the application configuration file will tell the .NET Runtime where to find those assemblies.

Demeanor supplies an application configuration file called "SmartDeviceApp.exe.config" in Demeanor's installation directory. Copy this file to your smart device application's directory and rename the file to agree with the name of your application. For example, when your application is named MyApp.exe you should name the configuration file MyApp.exe.config and it must reside in the same directory as MyApp.exe. By default, this application configuration file redirects references to any of the Compact Framework assemblies to the their default installation directory. If you have installed Visual Studio to a different location than its default location, you'll need to edit the application configuration file so that the href attribute of the codeBase elements point to the proper directory.

5.9 The System.Reflection.ObfusactionAttribute class

Demeanor for .NET, Enterprise Edition feature.

With the addition of the System.Reflection.ObfuscationAttribute type in .NET 2.0 , there is no longer any necessity for Demeanor for .NET's equivalent custom attribute - WiseOwl.ObfuscationAttribute. All features previously supported by the WiseOwl.ObfuscationAttribute are now available on the standard system attribute. Click here to view documentation on the System.Reflection.ObfuscationAttribute.

You have two alternatives when you need to control exactly which types and members that Demeanor for .NET obfuscates. You can specify exclusions via the command line/configuration file. You can also add such specifications directly to your source files by adding the System.Reflection.ObfuscationAttribute to a type or member. To this attribute, add the custom attribute as shown in the following examples. Note: while most examples show the attribute used on a type definition, you can also apply the attribute to a member of a type (field, method, property, event, and nested type).

For example, Demeanor for .NET normally obfuscates the name of an internal top-level type. You can prevent this default behavior by applying an instance of the System.Reflection.ObfusactionAttribute to the type. The System.Reflection.ObfusactionAttribute instance contains a property named Exclude that has a default value of true. Therefore applying the attribute to a type or member without setting this property causes Demeanor for .NET to exclude the type or member from obfuscation.

[System.Reflection.ObfuscationAttribute ()]
internal class MyClass {
  .
  .
  .
}

Exclude property

As one example, Demeanor will not, by default, obfuscate the name of an public top-level type. You can, however, request that Demeanor obfuscate such a type name by adding a System.Reflection.ObfuscationAttribute with its Exclude property set to false.

[System.Reflection.ObfuscationAttribute (Exclude=false)]
public class MyClass {
  .
  .
  .
}

ApplyToMembers property

By default, the System.Reflection.ObfuscationAttribute attribute applies only to the type or member that you decorate with the attribute. When you decorate a type with the attribute, you can set the ApplyToMembers property to true to specify that the Exclude property setting should apply not only to the type, but also to all members (fields, methods, properties and events) of the type. The following example requests that Demeanor not obfuscate the type and all of its fields, methods, properties and events.

[System.Reflection.ObfuscationAttribute (Exclude=true, ApplyToMembers=true)]
public class MyClass {
  .
  .
  .
}

StripAfterObfuscation property

Demeanor for .NET normally strips all System.Reflection.ObfuscationAttribute instances from an obfuscated assembly as they are not normally needed at runtime. However, you can request that Demeanor not remove a particular ObfuscationAttribute by setting the StripAfterObfuscation property to false. The default value is true.

[ObfuscationAttribute (Exclude=false, StripAfterObfuscation=false)]
internal void MyMethod CalculateRate {double interestRate) {
}

Features

The System.Reflection.ObfuscationAttribute has a string property called Feature. An obfuscator can parse the Feature string to allow you to enable custom features of that obfuscator. Demeanor for .NET supports the following features: ObfuscatedName, PreserveLiteralFields, PreserveLiteralValues, and PreserveParameters.

ObfuscatedName feature

You can specify the string to use as the obfuscated name of the type. Note that when you specify the obfuscated name, it is your responsibility to insure that the specified name will be unique within the appropriate scope.

[System.Reflection.ObfuscationAttribute (Exclude=false, Feature="ObfuscatedName=Foo")]
public class MyClass {
  .
  .
  .
}

PreserveLiteralFields feature

When Demeanor obfuscates an enumerated type, it normally deletes all enumerated names and values from the enumeration declaration. For example,

internal enum Color {
  Red = 1,
  Green = 3,
  Blue = 5,
}

becomes

internal enum a {
}

This increases the difficulty of reverse engineering the code. However, when your code uses the System.Enum static methods to convert an enumerated value into a string, or parse a string into an enumerated value, or check if a value is defined, previously you had to exclude the enumerated type from obfuscation so Demeanor did not remove the fields of the enumeration. You can use the System.Reflection.ObfuscationAttribute to enable obfuscation for an enumerated type, but also specify that Demeanor for .NET should preserve the enumerated value names. The default setting of the PreserveLiteralFields feature is false but specifying the feature changes the setting to true. For example,

[System.Reflection.ObfuscationAttribute (Exclude=false, Feature="PreserveLiteralFields")]
internal enum Color {
    Red = 1,
    Green = 3,
    Blue = 5,
}

after obfuscation becomes

internal enum a {
    Red = 1,
    Green = 3,
    Blue = 5,
}

You can explicitly specify the true/false setting of the feature:

[System.Reflection.ObfuscationAttribute (Exclude=false, Feature="PreserveLiteralFields=true")]
internal enum Color {
  Red = 1,
  Green = 3,
  Blue = 5,
}

PreserveLiteralValues feature

When Demeanor obfuscates an enumerated type, it normally deletes all enumerated names and values from the enumeration declaration. For example,

internal enum Color {
  Red = 1,
  Green = 3,
  Blue = 5,
}

becomes

internal enum a {
}

This increases the difficulty of reverse engineering the code. However, this can cause your code to fail unexpectedly when your code uses the System.Enum static methods to check if a value is defined. These static methods inspect the definition of the enumeration to determine if the enumerated type defines the value. Previously, to enable such validation code to work, you had to exclude the enumerated type from obfuscation so Demeanor did not remove the fields and values of the enumeration. However, you can use the System.Reflection.ObfuscationAttribute to enable obfuscation for an enumerated type, and obfuscate the names of the symbols, but also specify that Demeanor for .NET should preserve the associated enumerated values. The default setting of the PreserveLiteralValues feature is false but specifying the feature changes the setting to true. For example,

[System.Reflection.ObfuscationAttribute (Exclude=false, Feature="PreserveLiteralValues")]
internal enum Color {
  Red = 1,
  Green = 3,
  Blue = 5,
}

after obfuscation becomes

internal enum a {
    a = 1,
    b = 3,
    c = 5,
}

You can explicitly specify the true/false setting of the feature:

[System.Reflection.ObfuscationAttribute (Exclude=false, Feature="PreserveLiteralValues=true")]
internal enum Color {
  Red = 1,
  Green = 3,
  Blue = 5,
}

When you specify both PreserveLiteralFields and PreserveLiteralValues, Demeanor for .NET uses the PreserveLiteralFields setting.

PreserveParameters feature

When Demeanor for .NET obfuscates a method, by default, Demeanor also obfuscates the names of the parameters to that method. In very unusual scenarios, you may wish to obfuscate the name of the method but preserve the names of the parameters to that method. You can set the PreserveParameters feature to true to request that Demeanor for .NET not obfuscate the parameter names. The default setting of the PreserveParameters feature is false but specifying the feature changes the setting to true.

[System.Reflection.ObfuscationAttribute (Exclude=false, Feature="PreserveParameters")]
internal void MyMethod CalculateRate {double interestRate) {
}

You can set multiple features at the same time on an attribute in the expected way:

[ObfuscationAttribute (Exclude=false, Feature="ObfuscatedName=q, PreserveParameters=true")]
internal void MyMethod CalculateRate {double interestRate) {
}

 

5.10 The /prefix:<value> command line option

Demeanor for .NET, Enterprise Edition feature.

Normally Demeanor obfuscates a top-level type name by removing any namespace qualification and replacing the original name with a short meaningless name such as 'a', 'b', 'c' and so on. This technique maximally reduces the size of the obfuscated assembly and removes semantics that expose the original namespace organization of the types. Unfortunately, the Microsoft C# compiler cannot distinguish between two identically named types that reside in different assemblies. (The IL assembler can distinguish such types for those extremely adventurous developers.) For example, if you create a type called 'WiseOwl.Foo' in assembly WiseOwl.dll and another vendor creates a type called 'WiseOwl.Foo' in assembly FlyByNight.dll, a client application cannot reference both assemblies during a single compilation and use either of the two 'WiseOwl.Foo' types.

Normally, you don't run into the situation because developers often use namespaces and generally create unique type names - but there are no guarantees. Similarly, if two vendors each ship an assembly containing a top-level type called 'GreateGizmo' (notice the lack of a namespace qualification), then a client application cannot reference both vendor's assemblies even if the application only needs to use only one of the 'GreatGizmo' types.

Obfuscation exacerbates this problem. By default, an obfuscated assembly contains top-level types named 'a', 'b', 'c' and so on. Two obfuscated assemblies, even from different vendors, may easily have identically named types called "a', 'b', 'c' and so on. The Microsoft C# compiler cannot distinguish two types called 'a' in different assemblies any more than it can type types called GreateGizmo.

 

5.11 Microsoft Visual Studio Integration

Demeanor for .NET, Enterprise Edition feature.

Demeanor for .NET, Enterprise Edition installs integrated project obfuscation support into Microsoft Visual Studio for C#, VB.NET and Managed C++ projects. In the Solution Explorer, right-click on the project for which you wish to enable obfuscation. In the resulting context menu, you'll see an "Obfuscation Properties" menu item.

Obfuscation Properties Context Menu Image

Select "Obfuscation Properties" and Visual Studio displays the Demeanor for .NET, Enterprise Edition Obfuscation Properties property page. In this property page, you can specify all the obfuscation properties available via command line options to the command line tool. Visual Studio stores a project's obfuscation properties separate per configuration. Therefore, when the "Release" configuration is active, any changes you make to the obfuscation properties only affect "Release" builds of the project. Set the "Enable Obfuscation" property to "True" and Visual Studio, after building this project, will call Demeanor for .NET, Enterprise Edition to obfuscate the project output.

Obfuscation Properties Image


 

5.12 MSBuild Obfuscation Task

Demeanor for .NET, Enterprise Edition feature.

Demeanor for .NET, Enterprise Edition installs a build task for the .NET Framework MSBuild utility. Here is a sample project file that invokes the Obfuscation task.

 

<?xml version="1.0" encoding="utf-8" ?>

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003 ">

  <UsingTask TaskName="Wiseowl.Build.Tasks.Obfuscate" AssemblyFile="$(MSBuildExtensionsPath)\Wise Owl, Inc.\Demeanor for .NET, Enterprise Edition\v5.0\WiseOwl.Build.Tasks.dll"/>

  <Target Name="MyTarget">

    <Obfuscate RootAssembly="C:\Src\MiniApp\obj\Release\MiniApp.exe"

      All="false"

      CompilerControlled="false"

      EncryptStrings="true"

      EntireApplication="false"

      ForceParameters="false"

      Insitu="false"

      NoEnumerations="false"

      NoEvents="false"

      NoFields="false"

      NoLogo="false"

      NoMethods="false"

      NoParameters="false"

      NoProperties="false"

      NoResources="false"

      NoSerializable="false"

      NoTypes="false"

      OverloadOnStatic="false"

      Verbose="true"

      Names="Alpha"

      Exclude="SomeClass"

      ExcludeRegEx="BadClass*"

      Prefix="WiseOwl"

      Flow="Minimum"

      HinderReflection="true"

      SuppressIldasm="true"

      KeyFile="C:\SomeDir\PublicPrivate.snk"

      KeyContainer="KeyContainerName"

      AdditionalAssemblies="MyAssembly, Version= 1.0.0.0, Culture= neutral, PublcKeyToken= 0123456789abcdef"

      ExcludedAssemblies="OtherAssembly, Version= 1.0.0.0, Culture= neutral, PublcKeyToken= 0123456789abcdef"

      Config="MyConfig.xml"

      Report="MyReport.xml" />

  </Target>

</Project>

 

6.0 Version history.

5.0.4054.0

Fix 'Unexpected TYPESPEC coded index' error. The problematic TYPESPEC is now permitted.

5.0.4055.0

Network Edition: Fix problem with network license server reaper thread failing to reclaim expired licenses occasionally.

5.0.4123.0

Enhance Demeanor to robustly operate on assemblies obfuscated by tools that produce invalid assemblies. You can run PEVerify on such assemblies and will see errors such as [MD]: Error (Structural): Table=0x00000001, Col=0x00000000, Row=0x00000159, has coded rid out of range.

5.0.4364.0

Further enhance Demeanor to robustly operate on assemblies obfuscated by tools that produce invalid assemblies.

Fix a bug where Demeanor only honored the assembly resigning option when the -verbose option was also requested. Demeanor now will resign assemblies, if requested, without -verbose enabled.

5.0.4366.0

Added more anti-Reflection features to Demeanor obfuscated assemblies.

5.0.4410.0

Added the /hinderreflection and /suppressildasm command line options.

5.0.4459.0

Update the schema parsed by the StackDecode utility to support the /hinderreflection and /suppressildasm command line options.

5.0.4573.0

Update the licensing component to support additional licensing features.

5.0.4774.0

Added Visual Studio 2012 integration.


Did you find this information useful? Please send your suggestions and comments about the documentation to support@wiseowl.com.