P_US_Holidays_NewYearsDay_English

DeepSea Obfuscator 2009

Legal Note Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, email addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of TallApplications BV. TallApplications BV may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from TallApplications BV, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Windows NT, 2000, XP, Server 2003, Vista, Server 2008 and 7, .NET Framework, Microsoft Office, Excel, Access and Internet Information Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. All other trademarks are the property of their respective owners. © 2001-2009 TallApplications BV. All rights reserved. DeepSea Obfuscator is a trademark of TallApplications BV.

Contents

Table of Contents

Foreword

Part I Introduction

1 About DeepSea Obfuscator 2009

................................................................................................................................... ................................................................................................................................... ................................................................................................................................... ................................................................................................................................... ................................................................................................................................... ................................................................................................................................... ................................................................................................................................... ................................................................................................................................... ................................................................................................................................... ................................................................................................................................... ...................................................................................................................................

6 7 7 7

2 About This Guide 3 Staying Up To Date

4 Getting More Help Part II Getting started

1 Concepts

2 Your First Obfuscation 3 Your Second Obfuscation 4 Adding obfuscation features

10 12 13 13 14 15

5 Obfuscation projects

6 Reading obfuscated stack traces

7 Where to go from here Part III External configuration

1 Creating and external configuration file

17 18 19

2 Obfuscation preview

3 External configuration file format Part IV Obfuscation Reference

................................................................................................................................... 1 ObfuscationAttribute .......................................................................................................................................................... 22 Attribute properties .......................................................................................................................................................... 22 Rename feature .......................................................................................................................................................... 23 Encrypt strings feature .......................................................................................................................................................... 24 Control flow obfuscation feature .......................................................................................................................................................... 25 Cleanup feature .......................................................................................................................................................... 26 Optimize feature .......................................................................................................................................................... 27 Make internal feature .......................................................................................................................................................... 27 Seal feature .......................................................................................................................................................... 28 Inject feature .......................................................................................................................................................... 29 Change namespace feature .......................................................................................................................................................... 30 Add prefix feature .......................................................................................................................................................... 30 Clean XML documentation .......................................................................................................................................................... 31 Disabling features .......................................................................................................................................................... 31 Common feature arguments ................................................................................................................................... 32 2 ObfuscateAssemblyAttribute ................................................................................................................................... 32 3 Obfuscation in Silverlight or NET 1 1 ................................................................................................................................... 32 4 Smart Protection 22

DeepSea Obfuscator 2009

Part V Tool Integration

1 Visual Studio

35 35 37 38 39 40 42 42 43 43

2 MSBuild

3 NAnt

4 Command line application 5 Directories and file paths

6 De-obfuscation API Part VI Solving problems

1 Reflection 2 Framework

3 Bugs

4 The problem remains, now what? Part VII Evaluation and licensing

1 Evaluation 2 Licensing Index

45 45

Part

Introduction

DeepSea Obfuscator 2009

1 Introduction The DeepSea Obfuscator 2009 User Guide provides an overview of DeepSea Obfuscator 2009 and provides step-by-step instructions for the most commonly used procedures. The following topics are included in this chapter:

Ø About DeepSea Obfuscator 2009 Ø About This Guide

Ø Staying Up To Date Ø Getting More Help 1.1 About DeepSea Obfuscator 2009

DeepSea Obfuscator 2009 protects your your intellectual property by obfuscating your . NET assemblies. Obfuscation makes it (much) harder for unauthorized personnel to obtain your intellectual property. For example compare these before and after views of a simple assembly.

The following is a brief overview of some of DeepSea Obfuscator 2009's features:

Ø Out of the box protection - Just run DeepSea Obfuscator 2009 and your .NET assemblies are protected. Ø Assembly merging – Merge assemblies for easier deployment. Ø Declarative obfuscation - Integrate your obfuscation settings where they are most appropriate: in your source code. Ø Fast - Finally a developer tool that makes optimal use of your multicore CPU for optimal performance. Ø Build tooling friendly - DeepSea Obfuscator 2009 comes with VisualStudio, MSBuild, NAnt and command line integrations. Ø Developer oriented license model - Licensed per user account, install on as many PC's as needed. It is no longer needed to perform obfuscation only on a build server.

Introduction 7

Read more about the concepts and then quickly move on to your first obfuscation !

1.2 About This Guide

This guide is based on DeepSea Obfuscator 2009 version 2.1.5.119. The latest version of this document is included in the DeepSea Obfuscator 2009

installation and available from: www.deepseaobfuscator.com .

If anything in this document is unclear or if an error is found, please let us know. Send your comments and remarks to support@deepseaobfuscator. com . Please include the document name, version and a page number or text excerpt if applicable.

1.3 Staying Up To Date DeepSea Obfuscator 2009 is equipped with an automatic update feature. This feature requires a direct connection to the Internet. On start-up, DeepSea Obfuscator 2009 will check for available updates. If an update is found you will be asked if you want to install the update. You will need to restart the application after the update has been downloaded.

1.4 Getting More Help

To get more help with DeepSea Obfuscator 2009, try the following sources:

Ø For the latest information, visit www.deepseaobfuscator.com . Ø If you have a specific issue not addressed in this document or on the web site, please contact the DeepSea Obfuscator 2009 support team at support@deepseaobfuscator.com .

We're happy to assist you!

Part

Getting started

Getting started 9

2 Getting started This chapter will help you to get started with DeepSea Obfuscator 2009. The concepts of DeepSea Obfuscator 2009 will be explaned and a walkthrough of DeepSea Obfuscator

2009's of your first obfuscation is presented. The following topics are included in this chapter:

Ø Concepts Ø Your First Obfuscation

Ø Your Second Obfuscation Ø Adding obfuscation features Ø Obfuscation projects Ø Reading obfuscated stack traces Ø Where to go from here

2.1 Concepts DeepSea Obfuscator 2009 is typically invoked during the last stages of your build process. It takes compiled and fully linked assemblies and converts them into obfuscated assemblies.

DeepSea Obfuscator 2009 performs a series of conversions on each assembly. These conversions preserve the function implemented in the assembly, but make it much harder to understand and retrieve the original sources. For example compare these before and after views of a simple assembly.

DeepSea Obfuscator 2009

Which conversions are executed is controlled by so called features. The most common feature is "rename". This feature renames all symbols of internal types and members into something that is hard to understand and has no relation what so ever with the original source code. The features that DeepSea Obfuscator 2009 will perform are found in the assemblies themselves by means of obfuscation attributes or in an external configuration file. The . NET framework has specified two attributes (in the System.Reflection namespace) that are used to specify obfuscation features:

o ObfuscationAttribute o ObfuscateAssemblyAttribute

A full description of these attributes and their semantics is given in Obfuscation Reference .

When DeepSea Obfuscator 2009 does not find any obfuscation attributes it will perform a default feature set. This set is configured such that all internal types and members are renamed and typical obfuscation problems (such as resource files, XML serialization etc.) are avoided using Smart Protection rules. 2.2 Your First Obfuscation Now we'll present a step by step instruction for your first obfuscation. We'll use the HelloWorld sample application that is found in the Samples folder. This application has no obfuscation attributes, so the default feature set will be used.

1. First open Windows Explorer in the HelloWorld\bin sample folder. 2. Right click on HelloWorld.exe

Getting started 11

3. Select Obfuscate with DeepSea DeepSea Obfuscator 2009 will now start and perform the obfuscation.

DeepSea Obfuscator 2009

Once it is finished, you can close the application. Now you can startup HelloWorld.exe which is now obfuscated.

2.3 Your Second Obfuscation

The HelloWorld sample used in the previous paragraph is an application that has several public types and members. By default these members are not obfuscated. In this obfuscation we'll present a slightly modified version of the HelloWorld sample ( HelloWorld2 ) that has an obfuscation feature set such that all types and members (even public ones) are obfuscated.

1. Open the HelloWorld2.sln solution in Visual Studio. 2. Open Properties\AssemblyInfo.cs

Notice the following lines:

// Obfuscation settings [assembly: ObfuscateAssembly( true )]

The ObfuscateAssembly attribute is used with a “true" for the “assemblyIsPrivate"

Getting started 13

argument. This informs DeepSea Obfuscator 2009 that the assembly is intended to be fully obfuscated. To obfuscate this assembly, perform the same steps as in the first obfuscation paragraph, but now for HelloWorld2.exe. 2.4 Adding obfuscation features As mentioned above DeepSea Obfuscator 2009 uses features found in obfuscation attributes to control the obfuscation process. These attributes must be embedded in the assembly that is obfuscated. To assist you in creating the correct obfuscation attributes, DeepSea Obfuscator 2009 provides a Code assistant.

To start the Code assistant, startup DeepSea Obfuscator 2009 and select the Code assistant tab. Then select the feature you want to configure, adjust the settings and click on the generated code snippet. This will copy the code snippet to the clipboard.

2.5 Obfuscation projects

When you obfuscate your programs DeepSea Obfuscator 2009 using the GUI, you may want to save your obfuscation settings (such as directories and assemblies). To do so, click on the Start button in the toolbar and click on Save .

DeepSea Obfuscator 2009

DeepSea Obfuscator 2009 will now create a project file ( .dsoproj ) for you which you can open later on. 2.6 Reading obfuscated stack traces If an exception occurs in your obfuscated program, the stack trace contains obfuscated type and method names. To make these stack traces readable, DeepSea Obfuscator 2009 generates a map file ( . dsomap ).

To de-obfuscate a given stack trace, do the following:

Click on the map file to open it. The Stacktrace de-obfuscator dialog appears.

Now paste the obfuscated stack trace in the top part of the dialog. The de-obfuscated stack trace will appear in the bottom part of the dialog.

Getting started 15

2.7 Where to go from here

More information on working with DeepSea Obfuscator 2009 is available in this document and on the website ( www.deepseaobfuscator.com ).

Part

III

External configuration

External configuration 17

3 External configuration

Besides using obfuscation attributes embedded in the source assembly, DeepSea Obfuscator 2009 can be instructed to apply several obfuscation features using an external configuration file. This is the approach of choice in case the sources of the assembly are not available.

The external configuration file is an XML file that is created using the External Configuration tab of DeepSea Obfuscator 2009.

3.1 Creating and external configuration file

To create an external configuration do the following:

1. Start DeepSea Obfuscator 2009 2. Load the assembly or assemblies you want to configure 3. Go to the External Configuration tab 4. Go to the node representing the assembly, namespace, type or member for which you

want to apply a specific configuration 5. Select the desired setting on the right 6. Save the configuration file

DeepSea Obfuscator 2009

3.2 Obfuscation preview

The External Configuration tab shows the decisions DeepSea Obfuscator 2009 will take during obfuscation for the most used obfuscation features. This "obfuscation preview" is also helpful if you're not using an external configuration.

Decisions for the following features are displayed: Rename Cleanup Encrypt strings Make internal Seal

An enable icon indicates that the feature will be included for that node (e.g. closeButton will be renamed). A disabled icon indicates that the feature will be excluded for that node (e.g. Form1 will not be renamed). A missing icon indicates that the feature is not applicable to that node (String encryption is only applicable to methods)

If you hover over one of the icons a tooltip will show additional information, include the reason for the decision that will be taken.

External configuration 19

3.3 External configuration file format

The external configuration file is an XML file that can be editing in the External Configuration tab of DeepSea Obfuscator 2009 or edited manually with any text editor.

Here's a sample configuration file.

The file has the following elements: Element name Description Parent element Attributes configuration Root element of an external configuration file None assembly Refers to an assembly configuration name

The name of the assembly The full name of the type

type

Refers to a type within an assembly Refers to an event within a type Refers to a field within a type

assembly

name

event

type

field

type

name

The name of the field The full name of

type

DeepSea Obfuscator 2009

the field type

method

Refers to a method within a type

type

name

The name of the method

signature

The signature of the method The name of the property The full name of the property type The name of the feature to specify. See ObfuscationAttri bute for details. True|False to exclude or include this element from the

property

Refers to a property within a type

type

name

type

ObfuscationAttri bute

Specifies an obfuscation feature

assembly, type, event, field,

Feature

method, property

Exclude

specified feature. ApplyToMembers True|False to apply the

specified feature to members of the element.

Part

Obfuscation Reference

DeepSea Obfuscator 2009

4 Obfuscation Reference

This chapter will provide a detailed description of the obfuscation features supported by DeepSea Obfuscator 2009 and the attributes used to control them. The following topics are included in this chapter:

Ø ObfuscationAttribute Ø ObfuscateAssemblyAttribute Ø Obfuscation in Silverlight or .NET 1.1 Ø Smart Protection

4.1 ObfuscationAttribute

This attribute is used to control many of the obfuscation features of DeepSea Obfuscator 2009. This attribute can be applied anywhere.

4.1.1 Attribute properties

The Feature property of this attribute is used to specify the intended obfuscation feature and its arguments. This is a string that follows a common format: [/argument1:value1 [/argument2:value2]] The name of the feature is specified first, followed by zero of more arguments. Each argument has a name and a value. Most argument names have a single letter abbreviation.

The Exclude property is used to instruct the obfuscator to exclude (Exclude=true) or include (Exclude=false) the intended feature. This property is ignored for some features.

The ApplyToMembers property is used instruct the obfuscator to apply the feature also (ApplyToMembers=true) or not (ApplyToMembers=false) on members of the element this attribute was applied to. This property is ignored for some features.

The StripAfterObfuscation property is used to instruct the obfuscator to remove the attribute after obfuscation (StripAfterObfuscation=true) or leave the attribute in the obfuscated assembly (StripAfterObfuscation=false). The value of this property does not influence the obfuscation feature. 4.1.2 Rename feature Instruct the obfuscator to include or exclude elements in the rename process. The rename process converts element names to short, random names like 'a' or 'Be'.

Format

Obfuscation(Feature="rename", Exclude=true|false)

Obfuscation Reference 23

Obfuscation(Feature="rename /namespace: [/strict:true|false]", Exclude Obfuscation(Feature="rename /type:", Exclude=true|false)

Abbreviated format

Obfuscation(Feature="rename /n: [/s:true|false]", Exclude=true|false) Obfuscation(Feature="rename /t:", Exclude=true|false) Since “rename" is the default feature for all usages except assembly usage, you can also specify this as: Obfuscation(Exclude=true|false) Obfuscation(Feature="default", Exclude=true|false)

Other attribute properties

Exclude

If true, the element is not renamed. If false, the element is renamed.

ApplyToMembers

If true, this rename rule is also applied to members of the element. If false, this rename rule is not applied to members of the element.

Targets

All (without arguments) Assembly (with /type or /namespace argument)

4.1.3 Encrypt strings feature Instruct the obfuscator to include or exclude elements from the string encryption process. The string encryption process converts readable strings in the code to encoded strings that are decoded at runtime.

Format

Obfuscation(Feature="encrypt-strings", Exclude=true|false) Obfuscation(Feature="encrypt-strings /namespace: [/strict:true|false]", Obfuscation(Feature="encrypt-strings /type:", Exclude=true|false)

DeepSea Obfuscator 2009

Abbreviated format

Obfuscation(Feature="encrypt-strings /n: [/s:true|false]", Exclude=tru Obfuscation(Feature="encrypt-strings /t:", Exclude=true|false)

Example The following attribute will prevent all string encryption in the entire assembly. [assembly:Obfuscation(Feature="encrypt-strings", Exclude=true)]

Other attribute properties

Exclude

If true, strings in the element are not encrypted. If false, strings in the element are encrypted. If true, this encrypt-strings rule is also applied to members of the element. If false, this encrypt-strings rule is not applied to members of the element.

ApplyToMembers

Targets

All (without arguments) Assembly (with /type or /namespace argument)

4.1.4 Control flow obfuscation feature Instruct the obfuscator to modify the code in your assembly such that de-compiling your code becomes much more difficult.

Format

Obfuscation(Feature="control-flow", Exclude=true|false) Obfuscation(Feature="control-flow /namespace: [/strict:true|false]", E Obfuscation(Feature="control-flow /type:", Exclude=true|false)

Abbreviated format

Obfuscation(Feature="control-flow /n: [/s:true|false]", Exclude=true|f

Obfuscation Reference 25

Obfuscation(Feature="control-flow /t:", Exclude=true|false)

Example

The following attribute will prevent all control flow obfuscation in the entire assembly. [assembly:Obfuscation(Feature="control-flow", Exclude=true)]

Other attribute properties

Exclude

If true, code in the assembly is not obfuscated. If false, code in the assembly is obfuscated. If true, this control-flow rule is also applied to members of the element. If false, this control-flow rule is not applied to members of the element.

ApplyToMembers

Targets

All (without arguments) Assembly (with /type or /namespace argument)

4.1.5 Cleanup feature

Instruct the obfuscator to include or exclude elements in the cleanup process. The cleanup process removes all un-referenced types and member.

Format

Obfuscation(Feature="cleanup", Exclude=true|false) Obfuscation(Feature="cleanup /namespace: [/strict:true|false]", Exclud Obfuscation(Feature="cleanup /type:", Exclude=true|false)

Abbreviated format

Obfuscation(Feature="cleanup /n: [/s:true|false]", Exclude=true|false) Obfuscation(Feature="cleanup /t:", Exclude=true|false)

Other attribute properties

DeepSea Obfuscator 2009

Exclude

If true, the element will not be removed. If false, the element can be removed if un-referenced. If true, this cleanup rule is also applied to members of the element. If false, this cleanup rule is not applied to members of the element.

ApplyToMembers

Targets

All (without arguments) Assembly (with /type or /namespace argument)

Remarks Th cleanup feature is implied by the rename feature. This means that everywhere you specify an attribute for the rename feature this implies the same rules for the cleanup feature. 4.1.6 Optimize feature Instruct the obfuscator to include or exclude elements in the optimization process. The optimization process applies various optimization aimed at making your assemblies smaller and faster.

Format

Obfuscation(Feature="optimize", Exclude=true|false) Obfuscation(Feature="optimize /namespace: [/strict:true|false]", Exclu Obfuscation(Feature="optimize /type:", Exclude=true|false)

Abbreviated format

Obfuscation(Feature="optimize /n: [/s:true|false]", Exclude=true|false Obfuscation(Feature="optimize /t:", Exclude=true|false)

Other attribute properties

Exclude

If true, the element will not be optimized. If false, the element can be optimized.

ApplyToMembers

If true, this optimize rule is also applied to members of the element.

Obfuscation Reference 27

If false, this optmize rule is not applied to members of the element.

Targets

All (without arguments) Assembly (with /type or /namespace argument)

4.1.7 Make internal feature Instruct the obfuscater to include or exclude a type or namespace in the make-internal process. This process changes the accessibility of included types to internal.

Format

Obfuscation(Feature="make-internal", Exclude=true|false) Obfuscation(Feature="make-internal /namespace: [/strict:true|false]", Obfuscation(Feature="make-internal /type:", Exclude=true|false)

Abbreviated format

Obfuscation(Feature="make-internal /n: [/s:true|false]", Exclude=true| Obfuscation(Feature="make-internal /t:", Exclude=true|false)

Other attribute properties

Exclude

If true, the element is not name made internal. If false, the element is made internal.

ApplyToMembers

Ignored

Targets Class, Interface, Struct (without arguments) Assembly (with /type or /namespace argument)

4.1.8 Seal feature Instruct the obfuscater to include or exclude a type or namespace in the seal process. This process changes the makes included types seal for improved safety and

DeepSea Obfuscator 2009

performance.

Format

Obfuscation(Feature="seal", Exclude=true|false) Obfuscation(Feature="seal /namespace: [/strict:true|false]", Exclude=t Obfuscation(Feature="seal /type:", Exclude=true|false)

Abbreviated format

Obfuscation(Feature="seal /n: [/s:true|false]", Exclude=true|false) Obfuscation(Feature="seal /t:", Exclude=true|false)

Other attribute properties

Exclude

If true, the element is not name made internal. If false, the element is made internal.

ApplyToMembers

Ignored

Targets Class, Interface, Struct (without arguments) Assembly (with /type or /namespace argument)

4.1.9 Inject feature Instruct the obfuscator to inject (or merge) another assembly into the current assembly.

Format

Obfuscation(Feature="inject /assembly:") Obfuscation(Feature="inject /assembly: /internal:true|false")

Abbreviated format

Obfuscation(Feature="inject /a:") Obfuscation(Feature="inject /a: /i:true|false") The /internal argument is used to make all types in the injected assembly internal (if

Obfuscation Reference 29

true) or leave them as is (if false). If you do not specify the /internal argument, all types are unchanged. You can use the make-internal feature to exclude certain types or namespaces.

Example

The following attribute will inject all types from PrivateAssembly.dll into the current assembly. [assembly:Obfuscation(Feature="inject /a:PrivateAssembly.dll")]

Other attribute properties

Exclude

Ignored

ApplyToMembers

Ignored

Targets

Assembly 4.1.10 Change namespace feature

Instruct the obfuscator to change (leading parts) of the a namespace to another namespace. This is typically used to make OEM derivatives or class libraries.

Format

Obfuscation(Feature="change-namespace

/from: /to:") All namespaces that start with the /from argument will be renamed to the /to argument followed by the remainder of the namespace.

Example

The following attribute will change all namespaces that start with MyCompany to MyOem followed by the remainder of the namespace. Obfuscation(Feature="change-namespace /from:MyCompany /to:MyOem") The result: MyCompany » MyOem MyCompany.Forms » MyOem.Forms MyCompany.UI.Controls » MyOem.UI.Controls Another.MyCompany » Another.MyCompany MyCompany2.Forms » MyCompany2.Forms

DeepSea Obfuscator 2009

Other attribute properties

Exclude

Ignored

ApplyToMembers

Ignored

Targets

Assembly 4.1.11 Add prefix feature Instruct the obfuscator to add a prefix to all renamed namespaces. This is typically used to identify multiple assemblies that contain shared (internal) code.

Format

Obfuscation(Feature="add-prefix /prefix:")

Other attribute properties

Exclude

Ignored

ApplyToMembers

Ignored

Targets

Assembly 4.1.12 Clean XML documentation Instruct the obfuscator to remove all obfuscated symbols from the XML documentation that accompanies the assembly. This feature is enabled by default.

Format

Obfuscation(Feature="clean-xmldoc", Exclude=true|False)

Other attribute properties

Exclude

If true, no obfuscated symbols are removed from the XML documentation. Instead they are updated to reflect the new names of the symbols. If false, obfuscated symbols are removed from the XML documentation. This is the default behavior.

Obfuscation Reference 31

ApplyToMembers

Ignored

Targets

Assembly 4.1.13 Disabling features

All features that are default on can be disabled completely. If disabled the feature will be skipped during obfuscation. This means that even if you do specify an attribute elsewhere to include the feature, that attribute will be ignored.

Format

Obfuscation(Feature="disable-rename") Obfuscation(Feature="disable-encrypt-strings") Obfuscation(Feature="disable-control-flow") Obfuscation(Feature="disable-cleanup") Obfuscation(Feature="disable-optimize") Obfuscation(Feature="disable-make-internal") Obfuscation(Feature="disable-seal")

Targets

Assembly 4.1.14 Common feature arguments

The following feature arguments are commonly used. Argument Description /namespace:

Applies a feature to all type and members in the specified namespace and it's child namespaces. Applies a feature to the specified type and its members. If set to true the feature is only applies to types and members in the exactly specified namespace. The feature is not applies to child namespaces.

/type:

/strict:true|false

DeepSea Obfuscator 2009

4.2 ObfuscateAssemblyAttribute

This attribute is used specify private assemblies. Private assemblies are obfuscation entirely (even elements visible outside the assembly).

Format

ObfuscateAssembly(true)

Target

Assembly

4.3 Obfuscation in Silverlight or .NET 1.1 The two standard obfuscation attributes ( Obfuscation and ObfuscateAssembly ) are introduced in the Microsoft .NET framework version 2.0. However they are not available in Silverlight and .NET 1.1. Since DeepSea Obfuscator 2009 relies heavily on these attributes, DeepSea Obfuscator 2009 comes with replacements for these attribute for use in these frameworks. These replacements are located in the Attributes folder in in DeepSea Obfuscator 2009 program files folder. You can freely use these replacements. 4.4 Smart Protection DeepSea Obfuscator 2009 uses several attributes and elements to prevent common obfuscation problems. This is called Smart Protection. The set of Smart Protection rules is expanded with each release of DeepSea Obfuscator 2009.

The set of rules include:

Application settings

Application settings protection prevents renaming of all properties with an ApplicationScopedSetting or UserScopeSetting attribute (in the System. Configuration namespace)

Serialization

Serialization protection rules prevent renaming of Serializable types and members. It also prevents renaming of private implementations of IEnumerable.GetEnumerator.

Obfuscation Reference 33

LINQ

LINQ protection prevents renaming of LINQ to SQL storage fields and types.

XAML

XAML protection prevents renaming of XAML event handlers, properties and event handlers.

XML Serialization

XML Serialization protection prevents renaming of XML serializable types and properties.

Part

Tool Integration

Tool Integration 35

5 Tool Integration

This chapter will help you to use DeepSea Obfuscator 2009 in combination with various build related developer tools. The following topics are included in this chapter:

Ø Visual Studio Ø MSBuild™ Ø NAnt Ø Command line application

5.1 Visual Studio

DeepSea Obfuscator 2009 supports C# and VB.Net projects in Visual Studio 2005 and 2008.

To obfuscate the output of such a project, select the project and set the Obfuscate setting in the project properties grid. Note that the Obfuscate setting is related to the current project configuration. This means that you can e.g. setup your project to obfuscate only in Release build.

5.2 MSBuild

DeepSea Obfuscator 2009 comes with an MSBuild < DeepSeaObfuscation > task found in DeepSea.MSBuild.dll assembly in the program files folder. This task is typically used in the Visual Studio integration, but can also be used outside Visual Studio.

Task parameters

DeepSea Obfuscator 2009

Attribute Type

Description

Required

Assemblies Items

Array of task items specifying all assemblies that should be obfuscated. Array of task items specifying all assemblies used as reference assembly in on the the obfuscated assemblies.

True

References Items

False

DstDir

directory The output directory.

False

MapDir

directory The directory where the obfuscation map is written to.

False

MapFile

file

File name and folder of the obfuscation map. This setting overwrites the MapDir attribute. File name and folder of an external configuration file. The external configuration is used in additional to obfuscation attributes found in the assemblies. Strong name key used to re-sign strong named assemblies.

False

ConfigFile file

False

KeyFile

file

False

Verify

None, All, IL, MD

Set the assembly verification mode. None: No verification All: Verify both IL and metadata. IL: Verify only IL MD: Verify only metadata.

False

XapExcludes pattern Exclude all assembly parts in a XAP file that match the given pattern from obfuscation. Multiple patterns can be separated by a semi colon ';'. XapIncludes pattern Include all assembly parts in a XAP file that match the given pattern in the obfuscation process. Include overrides Exclude and default behavior. Multiple patterns can be separated by a semi colon ';'. False The following sample will obfuscate the assembly MyComponent.dll to the Out directory relative to the directory that contains MyComponent.dll.

Tool Integration 37

5.3 NAnt

DeepSea Obfuscator 2009 comes with a NAnt < deepsea > task found in DeepSea.NAnt. dll assembly in the program files folder.

Task parameters

Attribute Type

Description

Required

todir

directory The output directory.

False

mapdir

directory The directory where the obfuscation map is written to.

False

mapfile

file

File name and folder of the obfuscation map. This setting overwrites the mapdir attribute. File name and folder of an external configuration file. The external configuration is used in additional to obfuscation attributes found in the assemblies. Strong name key used to re-sign strong named assemblies.

False

configfile file

keyfile

file

False

verify

None, All, IL, MD

Set the assembly verification mode. None: No verification All: Verify both IL and metadata. IL: Verify only IL MD: Verify only metadata.

False

xapexcludes pattern Exclude all assembly parts in a XAP file that match the given pattern from obfuscation. Multiple patterns can be separated by a semi colon ';'. xapincludes pattern Include all assembly parts in a XAP file that match the given pattern in the obfuscation process. Include overrides Exclude and default behavior. Multiple patterns can be separated by a semi colon ';'. False False

Nested elements

Element Required assemblies assembly A fileset specifying all assemblies that should True Type Description

DeepSea Obfuscator 2009

-fileset

be obfuscated.

references assembly -fileset

A fileset specifying all assemblies used as reference assembly in on the the obfuscated assemblies.

False

Sample In the following sample, DeepSea Obfuscator 2009 will obfuscate all assemblies with the dll extension in the ${basedir} directory. The obfuscated assemblies will be written to ${basedir}\Out. The nant.core.dll assembly is referenced.

5.4 Command line application

DeepSea Obfuscator 2009 can be invoked as command line application. This is usually only needed for build environments other then the ones mentioned above. Make sure to start DeepSea.com instead of DeepSea.exe. The following arguments can be used:

Argument

Description

Only show warning and error messages. Do not show informational messages.

/NOGUI

Do not start the graphical application.

/GO

Run the obfuscation right away. Only relevant in the graphical application.

/SN

Specify a keyfile used to re-sign strong name assemblies

/VERIFY

Verify all assemblies

/VERIFY:IL

Verify all assemblies, IL only.

/VERIFY:MD

Verify all assemblies, metadata only.

Tool Integration 39

/XAPEXCLUDE /XAPINCLUDE

Exclude all assembly parts in a XAP file that match the given pattern from obfuscation. Include all assembly parts in a XAP file that match the given pattern in the obfuscation process. Include overrides Exclude and default behavior.

/BASEDIR

Specify the directory used to resolve all relative paths .

/OUTDIR

Specify the directory where the obfuscated assemblies are written to.

/MAPDIR

Specify the directory where the obfuscation map is written to.

/MAPFILE File name and folder of the obfuscation map. This setting overwrites the /MAPDIR argument. /CONFIGFILE File name and folder of an external configuration file. The external configuration is used in additional to obfuscation attributes found in the assemblies. /REF Specify an assembly that is used as reference assembly. Specify one or more assemblies that will be obfuscated.

5.5 Directories and file paths

Obfuscation using DeepSea Obfuscator 2009 involves various file and directory paths. Below you'll find a detailed description how the various path's are used.

Directories

Directory Details Output directory The output directory.

Relative paths are resolved against the effective base directory.

Map directory The directory where the obfuscation map is written to.

Relative paths are resolved against the effective base directory.

Base directory Base directory for all relative path's.

Relative paths are allowed but highly discouraged.

Effective base directory

This is not an external setting, but the result of the following evaluation: 1. If the base directory is set, use the base directory. 2. If a (.dsoproj) project is used, use the directory containing this project. 3. If an input assembly is configured with a full path, use the directory containing this input assembly.

DeepSea Obfuscator 2009

4. If none of the above rules apply, use the current working directory.

Files

File

Details

Input assembly Relative paths are resolved against the effective base directory.

Reference assembly

Relative paths are resolved against the effective base directory.

Output assembly Always saved in the output directory.

Config file

Relative paths are resolved against the effective base directory.

Map file

If specified using a full path, used as specified. Otherwise saved in the map directory.

Key file

Relative paths are resolved against the effective base directory.

5.6 De-obfuscation API

De-obfuscation of stack trace is possible using the user interface and via a .NET API. This API is contained in the DeepSea.API.dll assembly.

The API consists of a single class called MapFile.

In order to de-obfuscate a stacktrace, create an instance of MapFile with the full path of the .dsomap file as constructor argument. Then call the Deobfuscate method to de-obfuscate a given stacktrace. Example: var map = new DeepSeaObfuscator.MapFile( "HelloWorld.dsomap" ); var originalStacktrace = map.Deobfuscate(obfuscatedStacktrace);

You may freely distribute DeepSea.API.dll with your application.

Part

Solving problems

DeepSea Obfuscator 2009

6 Solving problems In normal circumstances DeepSea Obfuscator 2009 will generate obfuscated assemblies that are 100% equivalent in function to the original assembly. These assemblies will run without problems.

However if you're using reflection or otherwise depend on specific names of types and/or members DeepSea Obfuscator 2009 may cause problems.

This chapter will help you solve those problems.

6.1 Reflection In the .NET framework you can use reflection to bind to types or members. Since reflection is based on specific names and cannot be fully detected by obfuscation tools (including DeepSea Obfuscator 2009) it is a common source of problems. In order to avoid this problems you must instruct DeepSea Obfuscator 2009 not to rename or cleanup the types and/or members you bind using reflection. To do so, you must exclude these types and/or members using the Obfuscation attribute.

For example to exclude type MyType from renaming and cleanup, add the following attribute to it.

[Obfuscation] internal class MyType

{ }

To exclude only a specific member in a type, you should add the attribute only to that member as shown below.

internal class MyType { [Obfuscation] internal void Foo() { /* some code */ } }

Note that the Obfuscation attribute without arguments will exclude the type or member from both renaming and cleanup.

6.2 Framework

In various cases, the .NET framework itself uses reflection on your code to accomplish some task. For example LINQ to SQL storage classes rely on reflection.

Solving problems 43

This means that although you're not actively using reflection, it is still being used on your code.

DeepSea Obfuscator 2009 uses Smart Protection rules to prevent errors that arise from these cases. However since the .NET framework is growing by the day, the set of Smart Protection rules employed by DeepSea Obfuscator 2009 also has to grow. This means that if you find an issue that you think should have been covered by a Smart Protection rule, please send us a sample and we'll happily extend the set of Smart Protection rules.

6.3 Bugs As any software developer will tell you, all software products have bugs in them. Of course we do extensive testing to avoid problems, but DeepSea Obfuscator 2009 will also have bugs. I you do find a bug, please make sure you're using that latest version first. If the problem still remains in the latest version, please contact our support team by sending an email to support@deepseaobfuscator.com with a clear description of the problem and steps needed to reproduce it.

We try to solve problems as soon as possible and we'll inform you once a fix is available.

6.4 The problem remains, now what?

If you're not able to solve the problem yourselves, please contact our support team. They are happy to assist you.

To contact them, send an email to support@deepseaobfuscator.com with the following information:

1. A clear description of the problem 2. A description how to reproduce the problem 3. The original assemblies (before obfuscation) needed to reproduce the problem We always consider customer materials highly confidential and tread them as secure or better as our own materials. Despite this, we know some customer are not allowed to send product assemblies what so ever. In that case you can also send a simple ("Hello world like") assembly that demonstrates the problem.

Please note that you do not have to be a licensed customer to contact our support team!

Page 1 Page 2 Page 3 Page 4 Page 5 Page 6 Page 7 Page 8 Page 9 Page 10 Page 11 Page 12 Page 13 Page 14 Page 15 Page 16 Page 17 Page 18 Page 19 Page 20 Page 21 Page 22 Page 23 Page 24 Page 25 Page 26 Page 27 Page 28 Page 29 Page 30 Page 31 Page 32 Page 33 Page 34 Page 35 Page 36 Page 37 Page 38 Page 39 Page 40 Page 41 Page 42 Page 43 Page 44 Page 45 Page 46 Page 47

Made with FlippingBook HTML5