XML Documentation Filter
Consider this code:
public class DS1307 { ////// Gets a value indicating whether clock is in halt state. /// ///public bool IsClockHalted { get { // TODO return false; } } } true if clock is in halt state; otherwise,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"?>MyLib Gets a value indicating whether clock is in halt state. true if clock is in halt state; otherwise,false .
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. /// ///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; } } /// true if clock is in halt state; otherwise,false ./// 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.