Skip to main content
Version: 2023.4

4.4. Symbol Encryption

Symbol encryption is a complementary feature to symbol renaming technique. Encryption feature is useful in production scenarios when it's necessary to resolve possible issues with your product. Such issues are very often reported via log files and error stack traces.

But as you might know, symbol names are renamed with randomly generated titles and become irreversibly lost after obfuscation. This makes it nearly impossible to analyze stack traces because it's hard to establish a correlation between error stack trace and original source code. Symbol encryption can be used to overcome this problem. It encrypts obfuscated symbol names instead of random generation.

Symbol encryption technology uses symmetrical crypto algorithm underneath. Used crypto algorithm is AES with 256 bits key strength. Cryptographic key for the algorithm is derived from the password. Symbol encryption produces printable ASCII characters in encrypted symbol names, so error dumps can be easily transfered with E-mail or some other kind of textual error reporting.

By default, symbol encryption is not used during obfuscation of the assembly.

To enable symbol encryption, you should apply a specially formed attribute to your assembly. In order to do that, you can use the instructions below.

Instructions on enabling symbol encryption

  1. Open obfuscatable project inside the IDE

  2. Add new source file to the project and call it ObfuscationSettings.cs (for C#) or ObfuscationSettings.vb (for Visual Basic .NET). You may prefer to use another name instead of ObfuscationSettings.cs or ObfuscationSettings.vb

  3. Fill ObfuscationSettings.cs with the following content (C#):

    using System;
    using System.Reflection;

    [assembly: Obfuscation(Feature = "encrypt symbol names with password XXXXXX", Exclude = false)]

    For Visual Basic .NET, fill ObfuscationSettings.vb with the following content:

    Imports System
    Imports System.Reflection

    <Assembly: Obfuscation(Feature:="encrypt symbol names with password XXXXXX", Exclude:=False)>
    Note

    Change XXXXXX with your password. Keep the password in secret.

    Passwords with a greater length are more preferable than short ones. Longer passwords have a better informational entropy thus greatly improving cryptographic strength of the encrypted data. It's suggested to have a password which at least consists of 8 characters. A password can contain script variables.

When symbol encryption is enabled for your project then you are able to use stack trace decoding feature.

Tip

If your product or solution consists of several projects then you most likely want to give them all the same encryption password. In order to do that globally, you can create CommonObfuscationSettings.cs (or .vb) file that is shared among all the projects in the solution. Note that Microsoft Visual Studio supports adding of a project file as a reference, so you can add a reference to the same global CommonObfuscationSettings.* file in several projects. Please also note, that a reference to global CommonObfuscationSettings.* file may be added just to one project and then just drag and dropped to all other projects.