XML Documentation Filter

Consider this code: 

    public class DS1307
    {
        /// 
        /// Gets a value indicating whether clock is in halt state.
        /// 
        /// true if clock is in halt state; otherwise, false.
        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:

IntelliSense dropdown window with content provided by XML documentation

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:

Visual Studio project settings for enabling XML documentation file generation

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

Assembly and generated XML documentation file

Let's take a look on its content: 

    <?xml version="1.0"?>
    
        
            MyLib
        
        
            
                
                    Gets a value indicating whether clock is in halt state.
                
                true if clock is in halt state; otherwise, false.
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

Please consider a common situation when some private members are added to your class. The added members are marked with yellow: 

    public class DS1307
    {
        /// 
        /// Gets a value indicating whether clock is in halt state.
        /// 
        /// true if clock is in halt state; otherwise, false.
        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;
            }
        }
 
        /// 
        /// An I2C bus instance.
        /// 
        private II2CBus I2CBus;
 
        /// 
        /// Device address at I2C bus.
        /// 
        private byte Address;
    }

Let's rebuild the project and take a look at the newly generated MyLib.XML file: 

    <?xml version="1.0"?>
    
        
            MyLib
        
        
            
                
                    An I2C bus instance.
                
            
            
                
                    Device address at I2C bus.
                
            
            
                
                    Gets a value indicating whether clock is in halt state.
                
                true if clock is in halt state; otherwise, false.

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

This is extremely bad from security point of view. Private documentation tends to describe the insights and sacred knowledge about the component's internals. So it is highly desirable to keep that kind of information in secret.

Please note that XML documentation files are often distributed together with product assemblies. So you can imagine the volume of intellectual property leaks they can bring.

The Solution

The XML Documentation Filter feature is built into Eazfuscator.NET and is applied automatically during the 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: 

    <?xml version="1.0"?>
    
        
            MyLib
        
        
            
                
                    Gets a value indicating whether clock is in halt state.
                
                true if clock is in halt state; otherwise, false.

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

Explore other features ▶