XML Documentation Filter

What Is It?

XML documentation filter is an automatic sanitizer that works on XML documentation files produced by various .NET compilers such as C#, Visual Basic, F# etc.

How It Works?

Consider this code:

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
        {
            // TODO
            return false;
        }
    }
}

The highlighted lines are code documentation comments. They allow to provide a quick documentation for a class, property or method.

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

Isn't that beautiful? Without a doubt, code documentation is a nice and useful feature.

If you write a class library then it’s always a good idea to provide the code documentation:

With XML documentation enabled, you get two main files in the output folder — an assembly file and a corresponding documentation file (MyLib.XML):

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 the public property IsClockHalted of the class DS1307 from MyLib assembly. That’s exactly what you might expect. File contains minimal and sufficient amount of information.

A Security Problem

Here is a common situation when some private members are added to the class (added members are 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
        {
            // Ask DS1307 chip with a given address via I2C bus.
            byte data = I2CBus.Transfer(Address, 0x00);
            // If bit 7 is set then clock is halted.
            return (data & 0x80) != 0;
        }
    }
 
    /// <summary>
    /// An I2C bus instance.
    /// </summary>
    private II2CBus I2CBus;
 
    /// <summary>
    /// Device address at I2C bus.
    /// </summary>
    private byte Address;
}

Let's rebuild the project and take a look at the newly generated 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 (lines marked with yellow). This is a very bad outcome from security standpoint.

Private documentation tends to describe the insights and sacred knowledge about the components' internals. So it is highly desirable to keep that kind of information in secret.

Note that in reality XML documentation files are much larger than our benign example. They are often distributed together with productized assemblies of considerable size. So you can just imagine the volume of intellectual property leakage those files can bring.

The Solution

XML documentation filter is built into Eazfuscator.NET and is applied automatically during obfuscation.

If you rebuild the aforementioned project with Eazfuscator.NET in Release configuration and take a look at MyLib.XML, you will see the following result:

<?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>

Right, all private documentation is gone. The only documented member now is a public property — exactly what’s expected without any security compromises.

Eazfuscator.NET automatically sanitizes intellectual property leaks in XML documentation files making them safe for distribution.

▶ Explore other features
▶ Give it a try