on Eazfuscator.NET | Features

XML Documentation Filter

XML Documentation Filter is a feature that arrived in Eazfuscator 2.8.

Ok, let me start the show. I know that every .NET developer saw such comments for a code entity at least once in his life:

public class DS1307
{
    /// <summary>
    /// Gets a value indicating whether clock is in halt state.
    /// </summary>
    /// <value>true</c> if clock is in halt state; otherwise, <c>false</c>.</value>
    public bool IsClockHalted
    {
        get
        {
            byte data = I2CBus.Transfer(Address, 0x00);
            return (data & 0x80) != 0;
        }
    }
}

That kind of comments allows to provide a quick documentation for a class, property or method.

Code documentation is used by Visual Studio to show IntelliSense hints:

So, as you can see, code documentation is a nice and useful feature.

If you write a class library then it’s always a good idea to provide code documentation. Visual Studio gives such ability by enabling XML Documentation generation for your project:

Whenever you build your project with XML documentation enabled you will get two main files in the output folder – assembly file and corresponding XML documentation file:

As you can see, there is MyLib.XML file in the output folder. Let’s take a look on its content:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MyLib</name>
    </assembly>
    <members>
        <member name="P:MyLib.DS1307.IsClockHalted">
            <summary>
            Gets a value indicating whether clock is in halt state.
            </summary>
            <value><c>true</c> if clock is in halt state; otherwise, <c>false</c>.</value>
        </member>
    </members>
</doc>

MyLib.XML file contains documentation for IsClockHalted public property of DS1307 class from MyLib assembly. That’s exactly what you might expect. File contains minimal and sufficient amount of information.

A Security Problem

Let’s add some private members to our class (marked with yellow):

public class DS1307
{
    /// <summary>
    /// Gets a value indicating whether clock is in halt state.
    /// </summary>
    /// <value><c>true</c> if clock is in halt state; otherwise, <c>false</c>.</value>
    public bool IsClockHalted
    {
        get
        {
            byte data = I2CBus.Transfer(Address, 0x00);
            return (data & 0x80) != 0;
        }
    }

    /// <summary>
    /// An I2C bus instance.
    /// </summary>
    private II2CBus I2CBus;

    /// <summary>
    /// Device address at I2C bus.
    /// </summary>
    private byte Address;
}

Rebuild the project and here is the corresponding content of MyLib.XML file:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MyLib</name>
    </assembly>
    <members>
        <member name="F:MyLib.DS1307.I2CBus">
            <summary>
            An I2C bus instance.
            </summary>
        </member>
        <member name="F:MyLib.DS1307.Address">
            <summary>
            Device address at I2C bus.
            </summary>
        </member>
        <member name="P:MyLib.DS1307.IsClockHalted">
            <summary>
            Gets a value indicating whether clock is in halt state.
            </summary>
            <value><c>true</c> if clock is in halt state; otherwise, <c>false</c>.</value>
        </member>
    </members>
</doc>

As you can see, the documentation for private class members was generated and stored in MyLib.XML (marked with yellow).

Let’s stop at this point and analyze the consequences of this in terms of obfuscation. Obfuscation is the process of hiding information about inner structure of the system from the prying eyes of reverse-engineer.

And now we have information about private assembly items right in MyLib.XML file... This is shocking from security point of view.

It is worth to mention that XML documentation files are often distributed together with product assemblies, so you can estimate an amount of possible intellectual property leakage that can be brought by XML documentation files.

Solution

XML Documentation Filter built in Eazfuscator.NET comes to the rescue.

Let’s protect MyLib project with Eazfuscator.NET by dropping the project from Solution Explorer of Visual Studio in the green zone of Eazfuscator.NET Assistant:

Then rebuild the project in Release configuration with Visual Studio and take a look on MyLib.XML file content:

<?xml version="1.0"?>  
<doc>  
  <assembly>
    <name>MyLib</name>
  </assembly>
  <members>
    <member name="P:MyLib.DS1307.IsClockHalted">
      <summary>
        Gets a value indicating whether clock is in halt state.
      </summary>
      <value>
        <c>true</c> if clock is in halt state; otherwise, <c>false</c>.</value>
    </member>
  </members>
</doc>

Voila. What we see is that all private documentation is gone. The only documented item is a public property in terms of inter-assembly visibility. Exactly what’s expected without security compromises.

That was just a simple sample, but I assure you that XML Documentation Filter gives a considerable effect on bigger assemblies. XML documentation for non-public assembly items is automatically pruned so that essential knowledge about component internals does not leak to the rest of the world.

How It Works

As many things in Eazfuscator.NET, XML Documentation Filter works behind the scene to ease your life. No special options should be given to Eazfuscator.NET. All required actions are automatically performed on obfuscation stage:

  1. XML documentation file location is extracted from the project file (.csproj, .vbproj)

  2. If step 1 fails then Eazfuscator.NET tries to find a corresponding XML documentation file by heuristic search

  3. XML documentation file is then processed according to obfuscation information to prune non-public items

Conclusion

XML Documentation Filter is a step toward better obfuscation results. This feature is essential for component developers and publishers, by whom XML documentation files are published on every release.

comments powered by Disqus