Dotfuscator User's Guide
The Settings Tab

The Settings tab allows you to configure global options, project properties, build settings and events, code signing, reporting, feature map strings for declarative obfuscation, and user-defined assembly load paths. You can choose the feature you wish to edit by selecting the appropriate node in the navigation pane on the left side of the tab.

Global Options

The global options editor allows you to set the global options for the project.

You can selectively enable or disable Dotfuscator’s features, such as renaming, from this tab. Additionally, you may also modify the following options:

Project Properties

The properties editor allows you to view and add user-defined name-value pairs as Project Properties and to view External Properties that have been defined from the command line. See Property List and Properties for a full explanation. To add a Project Property, click the New button on the project properties toolbar.

This brings up the New Project Property dialog. Type in a name and a value in the fields provided. Click on the OK button, and the property will be set.

You can use the Edit and Delete toolbar buttons in a similar manner to modify or remove Project Properties. You can also delete a property by selecting it and pressing the Delete key.

Build Settings

The build settings editor is where the project's destination directory, and optional temporary directory, are established.

When you create a new project, the output directory is set by default to ${configdir}\Dotfuscated. The ${configdir} is a built-in project property that is expanded to the folder that contains your project file.

If you want to choose a different destination directory or establish a temporary directory, enter the path to the directory in the appropriate text field.

The Temporary Directory is optional and is used to store temporary files during processing. By default Dotfuscator will use your Windows temporary directory.  If you wish to specify this directory, enter the path to the directory in this field or click Browse to choose its location graphically. 

The Destination Directory is required and specifies where the output from the build will reside.  Enter the path to the directory in this field or click Browse to choose its location graphically. 

Build Events

The Build Events property page is where you specify Build Events for your Dotfuscator project.

For each event you can specify an external program that runs when the event occurs.  You can also specify a working directory and command line options for the program, and whether Dotfuscator should halt the build (fail) if the specified program returns a non-zero error code.

For the post-build event, you can specify under what conditions it will run (e.g. all the time, only if the build succeeds, or only if the build fails). You can also specify whether you want the post build event to run only once for the project, or run once for each output module.

Signing

Strong Naming

The signing editor allows you to configure Dotfuscator to automatically sign or resign your strongly named assemblies. See Dotfuscating Strong Named Assemblies for more information.

Strong named assemblies are digitally signed. This allows the runtime to determine if an assembly has been altered after signing. The signature is an SHA1 hash signed with the private key of an RSA public/private key pair. Both the signature and the public key are embedded in the assembly’s metadata.

Since Dotfuscator modifies the assembly, it is essential that signing occur after running the assembly through Dotfuscator.

Dotfuscator handles this step as part of the obfuscation process.

Authenticode Digital Signing

The Authenticode Digital Signing option allows you to attach an Authenticode digital signature to your application.  Similar to a security certificate, this signature certifies that the application you are obfuscating and instrumenting is your intellectual property, and allows users to ensure that the resulting binaries were provided by you alone and have not been modified.  This feature adds another level of security to safeguard your application.  To attach an Authenticode signature to your output assemblies, check the Sign Output Assemblies checkbox and then click the Browse... button to locate your Key File, or enter its path in the text box.  Once the Key File field is properly populated, click the Set Password... button to set the password for your Key File.

The Timestamp URL field provides the ability for you to specify the URL of an Authenticode timestamp service. This URL will be accessed during Dotfuscator's signing process, and will provide additional data which will allow your assemblies' Authenticode signatures to remain valid after your code-signing certificate has expired. This element is optional. If omitted, this additional data will not be included, and your assemblies' Authenticode signatures will become invalid once your code-signing certificate expires.

 Renaming Reports

The renaming report provides a summary of all the elements renamed by Dotfuscator during a specific run, including a statistics section. The Renaming Report File (Map Output File) section allows you to specify the location to save a renaming map file. You may leave the default value, or enter your preferred path. If you know the name and path of the mapping file you want to use, you can type it directly into the text box. Alternatively, you can browse your file system for the intended file location. The Browse button on the right of the text box brings up the Select Map Output File window that provides a familiar navigational dialog. 

You also have the option of overwriting the output file each time you build the application without generating a backup of the existing copy of the output. 

Dotfuscator has a default transform that can generate a readable HTML formatted version of the report in addition to the default .XML format. If you do check the Output As HTML box, the Custom Transform (Leave blank for default) field is activated.  As the field name states, leave this blank for the default custom transform or click Browse to select the location of your choice.

Removal Report

The removal report provides a summary of all the elements removed by Dotfuscator during a specific run, including a statistics section. The Removal Report File section allows you to specify the location to save the report. Two approaches are available. If you know the name and path of the file you want to use, you can type it directly into the text box. Alternatively, you can browse your file system for the intended file location. The "…" (ellipsis) button on the right of the text box brings up the Select Removal Report File window that provides a familiar navigational dialog. 

You also have the option of overwriting the output file each time you build the application without generating a backup of the existing copy of the output.  The removal report can also be written out as a readable, HTML formatted document, in addition to the XML formatted version. This report provides a quick cross reference that allows you to quickly navigate through all types, fields, and methods to see at a glance which were removed. Checking the Output as HTML checkbox tells Dotfuscator to write this report using the same name and path information as the XML version. If the default HTML report doesn't meet your reporting requirements, you can provide your own XSL document that Dotfuscator uses to transform the XML version. If you do check the Output As HTML box, the Custom Transform (Leave blank for default) field is activated.  As the field name states, leave this blank for the default custom transform or click Browse to select the location of your choice.

Smart Obfuscation Report 

The smart obfuscation report provides a summary of all the elements that could not be renamed or removed based on rules provided by the smart obfuscation feature. If items are excluded by smart obfuscation but no destination for the report is specified, the report will appear in a Smart Obfuscation Report tab next to the Build Output tab at the bottom of Dotfuscator's window. The Smart Obfuscation Report File field allows you to specify the location to save the report. Two approaches are available. If you know the name and path of the mapping file you want to use, you can type it directly into the text box. Alternatively, you can browse your file system for the intended file location. The Browse button on the right of the text box brings up the Select Smart Obfuscation Report File window that provides a familiar navigational dialog. 

You have the option of overwriting the output file each time you build the application without generating a backup of the existing copy of the output.  You may also optionally configure the verbosity of the report. Allowed values for the verbosity attribute are All, Warnings Only, and None.  The default value is All.

Feature Map Strings

The feature map editor is for Declarative Obfuscation. Declarative Obfuscation is implemented via attribute decoration within the source code while it is being written.  The attributes that are used to control Declarative Obfuscation are System.Reflection.ObfuscateAssemblyAttribute and System.Reflection.ObufscationAttribute. System.Reflection.ObfuscateAssemblyAttribute controls the obfuscation of the assembly as a whole. System.Reflection.ObufscationAttribute controls the obfuscation of individual types and their members.  Feature Map Strings enable you to declare, within the source code, what should and should not be obfuscated by using attributes. For a complete description of Dotfuscator’s support for Declarative Obfuscation, see Declarative Obfuscation via Custom Attributes. That section describes the Feature Map and lists the native feature strings that Dotfuscator understands.

From the toolbar, you can add, edit, and remove feature map strings. The Add button brings up a dialog that allows you to map feature strings to supported Dotfuscator features.

The name that entered in the Feature Name: field is the name of the string. The selected Mapping Strings denote the configuration the attribute decorated with that feature will produce:

When a feature is selected, the Edit and Delete buttons are activated.  Selecting Edit brings up a dialog that allows you to edit the map feature strings to supported Dotfuscator features. You can also delete a feature map string by selecting it and pressing the Delete key.

User Defined Assembly Load Path

Using this editor, you can edit your project’s user defined assembly load paths. From the toolbar, you can add or remove directories, edit existing directories, or change the order in which they are searched. When you click Add, this window displays:

Two approaches are available for specifying the assembly load path. If you know the name and path you want to use, you can type it directly into the text box. Alternatively, you can browse your file system for the intended file location. The Browse button on the right of the text box brings up the Browse for Folder window that provides a familiar navigational dialog.  When the path is specified, click OK.  The path now displays in the User Defined Assembly Load Path window:

Check the Search First checkbox to have Dotfuscator search the load path before applying its standard search. When unchecked, Dotfuscator will search the loadpath only after applying its standard search.

 

 


© 2016 PreEmptive Solutions, LLC. All Rights Reserved.

www.preemptive.com