PreEmptive Protection - Dotfuscator 4.31
User Guide

Protection for Unity Apps

Note: The following instructions cover both the Professional Edition and the Community Edition of Dotfuscator

The following instructions will walk you through using Dotfuscator to protect apps made with Unity. You can apply these steps to each platform your app supports, creating an app with a proven, layered protection strategy, no matter what device it's running on.

In order to follow along with these instructions you will need the Unity-supplied Space Shooter example project or you can follow along with your own project and use this guide as a reference for adding protection.

You will also need to install Dotfuscator if you do not already have it. To do so, see Dotfuscator Editions to learn which Edition is best suited for your project, and see the Dotfuscator Downloads page to get the latest version of your selected edition of Dotfuscator.

If you already have Dotfuscator, please verify that you have a version that supports Unity.

Minimum Version Requirements
Dotfuscator Edition Minimum Version for Unity
Professional Edition 4.31
Community Edition 5.31

Note: These versions are required for apps made with the .NET scripting backend. If you are using the Mono scripting backend it is possible to use older versions of Dotfuscator.

Supported Platforms

Dotfuscator supports Unity projects that target the following platforms:

  • PC, Mac, and Linux Standalone
  • iOS
  • Android
  • Windows Store

Example Project

After you have Dotfuscator installed you will need to set up the example project. This guide uses the Space Shooter tutorial available on Unity's website.

Space Shooter App

Set up

Download the Assets

On the Asset Store page:

  1. Click the "Add to Downloads" button
  2. Click the "Open in Unity" button
  3. This will bring up the Unity window for opening projects

Create a Project

  1. Create a new project by clicking on the "New" button
  2. Give the project the a name and location to save. This example assumes the name is SpaceShooter and the location is C:\Unity\
  3. Add the Asset Package: "Space Shooter tutorial"
  4. Create the Project

Add Scene to Project

Find the _Complete-Game directory in the Assets directory of the project. Click on the _Complete-Game scene to bring it into the Scene tab, and then click the play button. Take a moment to play the game in the preview so you will be able to tell if anything is not working later in the protected version.

In the file menu click on Build Settings to open the build settings window. Add the _Complete-Game scene to the "Scenes the Build" by clicking the add open scenes button.

General Process to Add Protection

The general process for protecting Unity applications with Dotfuscator is the same across all the supported platforms, with the exception of a few platform specific steps. There are links to platform specific instructions from these general instructions when they are necessary.

Steps 1-7 will give basic protection to the application. Step 8 will add more protection to harden the app even further.

1. Build the App

To build the application that will be protected by Dotfuscator, first select the platform to build, then set the necessary player settings for the selected platform, and lastly build and save the Unity produced app.

Select Platform

To change the build platform in Unity, select File -> Build Settings to open the build settings window. The list of platform options will be on the left. Select the desired platform and click the 'Switch Platform' button.

Set Player Settings

Select a Scripting backend

Unity offers the option of three different scripting backends depending on target platform: Mono, .NET and IL2CPP.

The first two scripting backends, Mono and .NET, produce managed code which can be easily reversed engineered. (See the viewing an unprotected assembly example to see how easy it is)

The Mono and .NET scripting backends combine all the C# scripts written for the project into one dynamic linked library, called Assembly-CSharp.dll. The Assembly-CSharp.dll is what needs to be protected with Dotfuscator.

IL2CPP as a scripting backend does not produce output that can be used as an input to Dotfuscator.

The scripting backend can be set by clicking on the Player Settings... button in the Build Settings window. Under the "Configurations" section is the drop down menu for selecting the scripting backend. Select the appropriate scripting backend for your project.

See the Unity documentation for more information on scripting backends.

Platform Specific Player Settings

The iOS Platform and the Android Platform require additional configuration. Please see the following sections for details:

Build and Save the Output

Once everything for the build is configured in Unity, press the "Build" button in the "Build Settings" window. See the section on Building for Windows Store Inputs for platform specific details.

If you haven't built for another platform already, create a new directory in C:\Unity\SpaceShooter called "Builds" where we will store the build output for all the platforms we build in this example.

Inside C:\Unity\SpaceShooter\Builds create a directory with the name of the platform and select this directory as where to save the build output. Set the file name to be SpaceShooter if it is required for building on your current platform. For example the output for a Standalone platform build will be in C:\Unity\SpaceShooter\Builds\Standalone and the executable will be named SpaceShooter.exe.

Then build the project for the specified platform by pressing "Save".

2. Add Input to Dotfuscator

Open the Dotfuscator Gui and add the input by following instructions for Professional Edition or Community Edition. The correct input will depend on the target platform. See the following sections for details:

If you are following along with your own app the input will be in a similar location.

3. Configure Dotfuscator

If you are using Dotfuscator Professional Edition go to the settings tab, under the Advanced section, and change "Use only Mono-compatable-transforms" from 'No' to 'Yes'.

Save the Dotfuscator project in C:\Unity\SpaceShooter\Builds\<Platform>, and give it any name you would like. This Dotfuscator config file can be used to reopen the Dotfuscator project for this platform later.

See the Windows Store Dotfuscator Configuration section for an additional setting for Windows Store Universal 10 apps.

4. Build Dotfuscator Project

Now, you are ready to press the build button in the Dotfuscator GUI. Verify that the build was successful by looking in the output at the bottom of the GUI.

5. Replace the Assembly

Next to the build button is a button with an arrow on it. Pressing this will take you to the location of Dotfuscator's Output.

After you've found the output from Dotfuscator, copy it and go back to the original location of the input Assembly-CSharp.dll. Replace the unprotected Assembly-CSharp.dll with the protected version you copied from Dotfuscator's output.

The Windows Store platform skips this step.

6. Build the Protected Version of the App

Now that we've built a protected version of the Assembly-CSharp.dll, we need to build the entire app that uses it. Instructions on how can be found in the platform specific sections:

The Standalone platform skips this step.

7. Verify App Behavior

Try out the app on your computer, device, or emulator to verify the app's behavior with protection added. If there are issues, this most likely means that you need to add additional renaming exclusions beyond library mode. Please see the protection exclusions page for additional details on the workflow for identifying renaming exclusions.

8. Add More Protection

Now that your app is working with basic protection, you can increase the strength of the protection by following the steps below.

Turn off Library mode

First, in Dotfuscator you will want to turn off library mode for the Assembly-CSharp.dll. This step will make the obfuscation on the assembly more aggressive.

In Dotfuscator Professional, click the plus sign next to the assembly to expand the options. Then uncheck "Library" to turn off library mode. If you are using Dotfuscator CE, click on the assembly, and then to the right in the properties section uncheck Library mode.

Add Renaming Exclusions

We can improve protection by turning off Library Mode, but that will un-exclude some things that need to be excluded, so we need to add specific exclusion rules to cover those things.

Exclusions for all Platforms

It is neccessary to exclude:

  • All public types
  • All the Start() methods
  • All the methods that have to do with updating: Update(), FixedUpdate()
  • All the methods that occur on an event : OnEnable(), OnTriggerEnter(), OnTriggerExit()

After this, all public methods that weren’t specifically excluded will be renamed, which is an improvement over when we had Library Mode turned on. To add these exclusions follow the steps bellow. When you are done your renaming tab page should look like the following:

Unity Renaming Exclusions

To add the necessary renaming exclusions :

  1. Add a type rule by pressing the "Add Type" button and set the name to *.
  2. Select the +public attribute in the Attribute Specifier for that type. This takes care of excluding all public types in the assembly.
  3. Add another type rule by pressing the "Add Type" button and set the name to *.
  4. Uncheck the "Exclude Type" box for this type.
  5. Right click on the type that you just added, and select 'Add Method'. Repeat this step two more times, so you have three methods listed on the type.
  6. For each method, click on the method and set the name. The names will be Start, On.*, and .*Update. The names are regular expressions so they will cover all the methods listed above. For example .*Update will cover both Update() and FixedUpdate() methods.

You can verify this by selecting the method and then pressing "Preview". In the tree view of the inputs on the left you will see both of those types highlighted.

These exclusion rules aren't just important for the Space Shooter app, they can and should also be excluded from renaming in your own apps you build with Unity. See the general workflow for identifying renaming exclusions for finding and configuring additional renaming exclusions that may also be needed for your own app.

Since not all the methods are able to be renamed its important to keep this in mind when you are writing the scripts for your project. Try to keep any critical code out of methods that have to be excluded so it is not as easy to find.

See the Windows Store specific exclusions if you are targeting that platform.

Standalone Platform Details

Dotfuscator Input

For the Standalone platform you will need to add the Assembly-CSharp.dll as the input to Dotfuscator. For the Space Shooter example this can be found in the C:\Unity\SpaceShooter\Builds\Standalone\SpaceShooter_Data\Managed directory.

iOS Platform Details

These instructions assume you are using Unity on Windows but all the steps should be similar if you are using Unity on a Mac.

Unity Configuration Settings

After the platform and scripting backend are set, you will also have to configure the build for the device you plan to test the app on. In Player Settings below where the scripting backend was set in the 'Configuration' section, change the Target SDK to either Simulator or Device depending on which you are going to test the application on.

Dotfuscator Input

For the iOS platform you will need to add the Assembly-CSharp.dll as the input to Dotfuscator. For the Space Shooter example this can be found in C:\Unity\SpaceShooter\Builds\iOS\Data\Managed.

Build the XCode Project

Unity produces an XCode project which you use to build the actual iOS app. Before you can build the XCode project you need to update the Assembly-CSharp.dll.s in C:\Unity\SpaceShooter\Builds\iOS\Libraries by using Ahead of Time Compilation or AOT on the protected version of the Assembly-CSharp.dll.

To create a compatible version of the Assembly-CSharp.dll.s

  1. Locate the mono-xcompiler tool that comes with Unity.
    • If you are using Unity on Windows, then it will typically be located at C:\Program Files\Unity\Editor\Data\PlaybackEngines\iOSSupport\Tools\Win\mono-xcomiler.exe. The steps below assume you have Unity installed on Windows.
    • If you are using Unity on Mac, then the "mono-xcompiler" will typically be located at /Applications/Unity/PlaybackEngines/iOSSupport/Tools/OSX/mono-xcompiler and you can run a similar version of the following steps. Note you will need to use export instead of SETX in step 3.
  2. From your unity project directory (C:\Unity\SpaceShooter\Builds\iOS) open a new command prompt.
  3. Run mono-xcompiler as follows:
     SETX MONO_PATH "Data\Managed"
     SETX GAC_PATH "Data\Managed" 
     "C:\Program Files\Unity\Editor\Data\PlaybackEngines\iOSSupport\Tools\Win\mono-xcompiler.exe" --aot=full,static,nodebug,asmonly,outfile="Libraries/Assembly-CSharp.dll.s" "Data/Managed/Assembly-CSharp.dll"
    
  4. Check that a new Assembly-CSharp.dll.s is located in C:\Unity\SpaceShooter\Builds\iOS\Libraries.

Now that there is a new version of the Assembly-CSharp.dll.s, you'll need to copy C:\Unity\SpaceShooter\Builds\iOS\ over to a Mac in order to be able to build the XCode project.

Open the XCode project called Unity-iPhone.xcodeproj located in C:\Unity\SpaceShooter\Builds\iOS\.

If XCode suggests you "Update the project to recommended settings", don't do it. For this example updating may cause the app not to work.

Build the XCode project and from here you can also test the app on a device or an Emulator to see that Space Shooter works as expected.

Android Platform Details

Unity Configuration Settings

Open the player settings window by clicking on the 'Player Settings' button in the "Build Settings" window. The player settings window will be to the right in the regular Unity window. In the player settings window, set the Package Name in the Identification section above the Configuration section (where you set the scripting backend) to be com.Company.SpaceShooter. Then at the top of the Player Settings change the company name to Company and the product name to SpaceShooter.

Dotfuscator Input

To access the Assembly-CSharp.dll you will have to decompile the APK that Unity produced.

Download and set up APKtool with the instructions from the APKTool install page

In a command prompt in the directory that the APK is in, C:\Unity\SpaceShooter\Builds\Android, run the command:

 apktool d SpaceShooter.apk 

The Assembly-CSharp.dll can now be found in C:\Unity\SpaceShooter\Builds\Android\SpaceShooter\assets\bin\Data\Managed.

Build and Sign the APK

After replacing the unprotected assembly with the protected assembly, you must rebuild and re-sign the APK with the protected assembly.

  1. Rename or delete the old APK
  2. In the command prompt window from when you decomiled the APK run the following command to rebuild the APK

     apktool b SpaceShooter -o SpaceShooter.apk 
    
  3. Sign the app using your keystore and the jarsigner tool If you don't already know how to do this, for this example project you can enter the command:

     keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000
    

    Remember the password you set, and fill in appropriate values for your project.

  4. Sign the APK by executing:

     jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore my-release-key.keystore SpaceShooter.apk alias_name
    

Once that is done, you can install the APK on your Android device or Emulator and test out the Space Shooter app verify its behavior.

Windows Store Platform Details

Build in Unity

For the Windows store platform instead of using the "Build" button, use the "Build and Run" button. The input used for Dotfuscator will be created by doing this instead and you won't have to manually open up Visual Studio to build the Appx.(You can still build from Visual Studio if you want to)

Dotfuscator Input

If you built and ran the application from Unity then the input can be found in the directory C:\Unity\SpaceShooter\Builds\Windows\SpaceShooter\bin\x86\Master\AppX. If you build yourself from visual studio, the AppX directory will be located similarly based on what configuration you built the project in.

See the Windows store inputs page for instructions on adding this input.

Exclude everything from the package except the Assembly-CSharp.dll by left clicking on the assemblies and selecting "Exclude assembly from package". You should see all the assemblies you excluded show up in "Package Artifacts".

Dotfuscator Configuration

If you are using the Universal 10 SDK for the Windows Store platform there is an additional configuration setting required. In the "Settings Tab", add the Project Property ilreader.alias_system_runtime.never with the value 0. See the Project Properties section for details on how to add Project Properties.

Build the Appx

For a more permanent solution you can follow this article on integrating Dotfuscator into the Appx build.

To test protecting a Windows Store app in development:

To build the Appx from the output from Dotfuscator, first locate the MakeAppx tool, usually it can be found somewhere like C:\Program Files (x86)\Windows Kits\10\bin\x86\makeappx.exe. Then open a command prompt and execute the command

"C:\Program Files (x86)\Windows Kits\10\bin\x86\makeappx.exe" pack /d "C:\Unity\SpaceShooter\Builds\Windows\Dotfuscated" /p "C:\Unity\SpaceShooter\Builds\Windows\Space_Shooter.appx" /l

This will save the Appx in the C:\Unity\SpaceShooter\Builds\Windows directory.

Note: Make sure you don't include your map file in with the Appx.

Sign the Appx

The next step is to sign the Appx so you will be able to install it to test it. You can see the Microsoft documentation for help on this step.

Next, use SignTool to sign the application with the certificate.

Install the Appx

In the Administrator PowerShell command prompt execute the following commmand to install the Appx to test:

 add-appxpackage -path "C:\Unity\SpaceShooter\Builds\Windows\Space_Shooter.appx"

Windows Store Specific Exclusions

Windows Store platform apps need a few extra renaming exclusions that the other platforms don't need.

It is neccessary to additionally exclude:

  • All types
  • The namespace UnityEngine.Internal in the Assembly-CSharp.dll
  • The namespace UnityEngine.Internal.Types in the Assembly-CSharp.dll

To exclude all types:

  1. Select the type rule you made named *
  2. Check the "Exclude Type" box.

To add the namespaces to the renaming exclusions:

  1. In the tree view on the left expand the C:\Unity\SpaceShooter\Builds\Windows\SpaceShooter\bin\x86\Master\AppX node , then Assembly-CSharp.dll below it, then expand the Assembly-CSharp.dll listed under that
  2. At the bottom of that node are the two namespaces that need to be excluded. Check their boxes to exclude them.

Further Reading

If you have any trouble finding the necessary settings mentioned in these instructions in Unity, please refer to the Unity Documentation.

These instructions focused mainly on renaming exclsions, but Dotfuscator offers additional protections beyond renaming. Check out and explore the quickstart guide, Professional Edition documentation, and Community Edition documentation for information on all the other protection available for your apps.

We on the Dotfuscator team are always adding new features to improve the protection provided by Dotfuscator, as well as making the configuration process easier. Stay up-to-date with the latest Dotfuscator version by visiting the Dotfuscator Downloads page. For announcements and other information, keep an eye on our blog and follow our Twitter account, @PreEmptive.

Dotfuscator Version 4.31.0.6091. Copyright © 2017 PreEmptive Solutions, LLC