PreEmptive Protection - DashO v8.2 User Guide

Advanced Mode Screens

In this section, we describe how to use PreEmptive Protection - DashO's interface for Advanced mode projects. You can use the interface to create new projects or edit existing ones. The resulting project can be saved and used later by the command line interface, Ant, or you can obfuscate within the interface and view the results.

Input — Jars and Classes

The input section is used to configure the inputs to the project. This includes the location of jars and directories of classes that will be processed and entry points into these classes that are used to analyze the dynamic flow of the application.

It starts with Input — Jars and Classes where the locations for the classes to be processed are configured. DashO can handle directories or classes, zip files, and jar files in the classpath. It also supports a single APK file. Entries may be added by selecting them from the file system using the Add button. You can also create an entry by using the New button and editing its name. After adding or removing items from the input use the refresh class list item in the toolbar or from the menu.

Note:

Adding and removing entries will automatically refresh the class tree. However, manually entered names do not automatically refresh. Please use the refresh button when finished editing the name.

See the <inputpath> Section for more information regarding the creation of input entries.

Input — Supporting Classpath

DashO needs access to classes in the Java runtime and to classes in third party jars. The classes referenced here are needed for DashO’s analysis but are not processed. Entries may be added by selecting them from the file system using the Add button. You can also create an entry by using the New button and editing its name.

By default the location of the Java runtime used by DashO is added to the path. Projects that use J2ME or the Android API should not append the runtime jar to the classpath. These projects require the runtime jar for these particular environments: e.g., midpapi10.jar or Android.jar. You may also append or prepend the environmental classpath to the provided entries.

See the <classpath> Section for more information regarding the creation of new classpath entries.

Input — Global Processing Exclusions

The Input — Global Processing Exclusions panel lets you specify and classes or packages which should be excluded from all processing,

This UI defines the rules for the global exclusion of classes. See Graphical Rules Editing Interface for details. Any class which matches the rules set here will be excluded as if it were in the excluded sections of all the features. See the <globalProcessingExclude> Section for details.

Note:

Matched classes will also be excluded from being a candidate for a string decrypter and from the Constant Pool Tag and SourceFile Tag additions. The class listings of the other UI screens will be impacted, after reloading, and will not show classes which have been globally excluded.

Input — Included Non-Class Files

The Input — Included Non-Class Files panel lets you specify the source for non-class contents, such as images, property, or configuration files that need to be in the application.

Directories, individual files, or jar files may be added to list by selecting an existing file using Add button. You can also create an entry by using the New button and editing its name. For directories and jars all non-class files are copied into DashO's output. Directory entries can contain wildcard patterns using the * character to select particular file types.

Non-class files inside directory, zip, and jar sources will be copied to the output destination preserving their relative internal directories. Specified non-class files will be copied to the output destination. See the <includenonclassfiles> Section for details.

Note:

XML configuration files found when processing the non-class files may be updated allowing class and method names to be changed.

If you are merging inputs and your inputs contain the non-class files you can either turn on Auto Copy or reference them here. If you are not merging inputs DashO will copy over all non-class files in your input jars automatically; but non-class files that appear in input directories will not be copied. See Auto copy for details.

Input — Options

This panel controls some basic options that DashO uses while analyzing the input classes.

Ignore Missing Classes

DashO will attempt to analyze all classes that the application attempts to call. You can instruct DashO to ignore missing classes by selecting this option.

Note:

DashO cannot ignore classes and interfaces that the application extends or implements.

Ignore Missing Methods

DashO will attempt to locate concrete implementations of methods as part of its analysis. Turning this option on lets DashO proceeded even if it cannot locate the desired method. Use this option with caution.

Bypass DashO Processing

Turning this option on configures DashO to not perform any processing. The inputs will simply be copied to the output. This option is supported when outputting an unmerged directory or an APK.

Reflection Halts Build

DashO's analysis makes note of reflection usage in the application so that the targets of reflection can be identified. Turn this option on when you are determining what parts of the application use reflection.

Note: You may need to disable injection when enabling this option because some injected code uses reflection.

Determine Reflected Classes

DashO can determine some targets of reflection and automatically add make sure that these classes appear in the output. Note that this processing can increase the build time.

Rename Reflected Classes

By default targets of reflection are not renamed. Use this option to allow these classes to be renamed.

Entry Points — Methods and Fields

Fields and methods are used to indicate entry points into the application. DashO's analysis begins at these locations and is used to traverse the call graph of the application. This allows DashO to prune unused classes and members. Methods and fields that are used as entry points are non-renameable by default. The class and/or member can be made renameable by right-clicking on the item to bring up its properties, and checking Rename item.

See the Using the Graphical Rules Editing Interface section to compose rules that define method and field based entry points.

Conditional Including

It is sometimes necessary to manually include class files into the project. If the Class.forName() construct is used anywhere in the project, DashO will be unable to determine all possible classes that might be needed. In this case, any classes that will be referenced in the forName() construct must be manually included as entry points. These classes should not be renameable. See Dynamic Class Loading for more details on forname detection.

Note:

If no entry points are defined DashO will see if it can find entry points in the Manifests of input jars. If none are found, it defaults to library mode where all public and protected classes and members are used as entry points.

Entry Points — Libraries

Jars or directories of classes can be used as a library entry point. DashO uses all public members of the classes as non-renameable entry points. Optionally, protected members can be added as non-renameable entry points.

Libraries may be added by selecting them from the file system using the Add button. You can also create a library entry by using the New button and editing its name. The names of library entries can contain Property References.

See the section <library> Entry Point for details concerning library entry points.

Note:

Jars or folders added as libraries do not need to be added to the input list. Libraries are combined with the input list to determine the classes to be processed. When adding or removing library entries you can use the refresh option from the toolbar or menu to update the list of input classes.

Entry Points — Special Classes

A special class entry point allows the specification of a class that contains the implementation of interfaces or extensions of a class that define an entry point into an application. These entry points are typically defined by frameworks for such things as Spring, J2ME, or Applets. The names of these classes can be specified as an exact match, a pattern, or a by a regular expressions.

By default special classes are non-renameable. The class, and in most cases its members, can be made renameable by right-clicking on the item to edit its properties and check the Rename Class or Rename Members checkbox.

Applets

For DashO, an applet is a class that directly or indirectly extends java.applet.Applet. The applet's class can be made renameable, but the methods defined by java.applet.Applet are not renameable. See the <applet> section for details.

Servlets

For DashO a servlet is a class that directly or indirectly implements javax.servlet.Servlet. The servlet’s class can be made renameable, but the methods defined by java.applet.Servlet are not renameable. See the <servlet> section for details.

Enterprise JavaBeans — EJBs

Enterprise JavaBeans are server-side components written in Java that can be used to write distributed object-oriented enterprise applications. For DashO's purposes an EJB is any class that extends the interfaces defined in the javax.ejb package including the bean's home and key classes. See the <ejb> section for details.

Midlet and iAppli

A Midlet is a Java class that runs on embedded devices using Java ME, CLDC, or MIDP. The Midlet class should extend javax.microedition.midlet.Midlet directly or indirectly. iAppli classes are similar but use the NTT DoCoMo’s iAppli framework and extend com.nttdocomo.ui.IApplication either directly or indirectly. The midlet’s and iAppli’s classes can be made renameable, but the methods defined by javax.microedition.midlet.Midlet or com.nttdocomo.ui.IApplication are not renameable. See the <midlet> and <iappli> section for details.

Android

Android is used to identify classes from an Android application. These classes will extend android.app.Application, android.app.Activity, android.app.Service, android.content.BroadcastReceiver, or android.content.ContentProvider. These are each specified in the AndroidManifest.xml as an application, activity, service, receiver, or provider. See the <android> section for details.

SpringBean

SpringBean is used to identify classes used as Spring beans (these classes would be referenced in your spring xml configuration files). There is a setting for Additional Entry Points for non-property methods such as init-method and destroy-method. Unlike other special classes, renaming members is split into different categories:

  • Rename Property Methods – Controls the renaming of property methods and fields.

  • Rename Entry Points – Controls the renaming of the Additional Entry Points specified.

  • Rename Other Members – Controls the renaming of all other methods and fields.

See the <springbean> and Projects using the Spring Framework sections for additional details.

Class public fields/methods

DashO uses all public fields and methods in the classes as entry points. The class and its public members will not be renamed. See the <publics> section for details.

Class all fields/methods

DashO uses all fields and methods in the classes as entry points. The class and all its members will not be renamed. Specifying classes in this manner performs an unconditional include of the class. See the <unconditional> Entry Point section for details.

Properties

The User Properties panel lets you create and assign values to properties that can be referenced in the project. This can allow you to create a project that acts as a template. Properties may be defined in the terms of other properties, manipulate the value of other properties, or provide default values. The value of a property may be specified using one or more property references including to references to environment variables. These property references can include default values, indirection, or substitution syntax. See Property References for details. Recursive property definitions are not allowed.

See the <propertylist> section for information about using properties in your project.

Removal — Options

The Removal Options panel control which what happens to unused classes and members in the input and the removal of metadata.

Unused Classes

This controls the handling of unused classes. Options are to remove all unused class, only those that are not public, or to perform no removal at all. See the section on <removal> for details.

Unused Members

This controls the handling of unused methods and fields. Options are to remove all unused members, only those that are not public, or to perform no removal at all. See the section on <removal> for details.

Debug Information

This controls the removal of debugging information inserted by the compiler. Most information is for use by debuggers, but the most useful to retain are line numbers and the source file. To generate a stack trace with line number these two should be retained. See <debug> Section for details.

Note:

Field names in Local Variables and Local Variable Types are not renamed. Leaving these attributes in a production release may compromise the obfuscation.

Attributes

The Java compiler generates additional meta data for classes and their members and stores that information in attributes in the class files. Some of this information is required when for the compiler when you compile against a library or by applications using reflection. You can use these settings to selectively remove information that your application does not require at runtime to reduce the size of your class files. See <attributes> Section for details.

Note:

Type Annotations will always be removed. This is hard coded and cannot be un-checked.

Removal — Exclude

The Removal Exclude panel lets you compose rules that exclude classes and/or their methods and fields from renaming. Individual methods, fields, classes, or entire packages may be excluded.

You can create rules that exclude individual or groups of classes or even entire packages using regular expressions. See Graphical Rules Editing Interface for details.

Note:

Classes referenced here will still be removed if referenced in the Classes section.

Removal — Classes

If your inputs contain classes that you do not want to appear in the resulting output, such as unit tests or samples, you can have DashO remove them. Classes matched by these rules will not appear in DashO’s output. If any other input classes reference them, they will be treated as if they were support classes.

You can create rules that match individual or groups of classes or even entire packages using regular expressions. See Graphical Rules Editing Interface for details.

Note:

Classes referenced here, will be removed even if referenced in the Exclude section as well.

Removal — Method Calls

If your inputs contain calls to method you do not want to exist in the resulting output, such as logging or console output, you can allow DashO to remove them. Calls to the methods specified here will be removed from all input classes. Only calls to methods which return ‘void’ can be removed. The methods themselves are not removed, only the calls to those methods are removed.

Regular expressions are not supported in the class names, method names or signatures. However an entry of ** for the class name will match the method in all classes.

Obfuscation — Options

The Obfuscation Options panel controls the basic obfuscation setting for your project. Other panels under obfuscation allow you to change the specifics of each action and applying the obfuscation technique to all or part of your application.

Control Flow

Enables or disables control flow obfuscation globally. You can control the portions of the application to which control flow is applied by using include and exclude rules. If you do not specify any rules then all methods will have control flow applied.

Renaming

Enables or disables renaming of classes, methods, and fields globally. You can control the portions of the application to which renaming is applied by using exclude rules as well as controlling the renaming of packages, classes, and methods. Overload Induction™ renames method based on method signatures to produce many methods with the same name. Simple renaming renames the methods so that there is no overloading.

Encrypt Strings

Enables or disables string encryption obfuscation globally. You can control the portions of the application to which string encryption is applied by using include and exclude rules. If you do not specify any rules then all methods will have their strings encrypted.

Members Options

This section has obfuscation options that affect class members – methods and fields.

Make Synthetic

This obfuscation marks methods and fields as synthetic, generated by the Java compiler, which confuses some decompilers. It has four possible settings:

  • Never – No methods or fields are affected.

  • Only private and package – Methods and fields that are private or package-private are made synthetic.

  • If not public – Methods and fields that are private, package-private, or protected are made synthetic.

  • All – All methods and fields are made synthetic.

This setting is stored in the <make-synthetic> Section of the project file.

Control Flow — Options

The Control Flow Options panel lets you determine if Try/Catch handlers should be added to methods to further confuse de-compilers. You can also select the maximum number of handlers to be added to a method.

Control Flow — Include and Exclude

The Control Flow Include and Exclude panels let you compose rules that determine which parts of the application will have control flow obfuscation applied to methods. Methods, classes, or entire packages may be selected. Items should be excluded if you are concerned about possible performance issues.

See Graphical Rules Editing Interface for details.

Renaming — Options

When renaming has been enabled the Renaming Options panel gives you additional control over the renaming of items in your application.

Renaming

Enables or disables renaming of classes, methods, and fields globally. You can control the portions of the application to which renaming is applied by using exclude rules as well as controlling the renaming of packages, classes, and methods. Overload Induction™ renames method based on method signatures to produce many methods with the same name. Simple renaming renames the methods so that there is no overloading.

Rename Annotations

Enables or disables renaming of internally defined annotations.

Classes/Packages

You can elect to rename classes or to keep their original names. This provides for a very course level of control – you can use exclusions to preserve the names of individual classes, whole packages, or classes that meet certain criteria. When randomize is selected new class names are assigned in a random fashion from the list of shortest available identifiers.

When classes are renamed you can specify if the package hierarchy should be flattened or if the package naming hierarchy is retained.

When a class is renamed you can add an optional prefix to the new name. You can use periods in the prefix to place the renamed classes into a different package.

Note: When flattened, all renamed classes are moved to the default package, unless there is prefix which includes a period.

Members

You can elect to rename all methods and fields or to retain the names of public members. This provides for a very course level of control – you can use exclusions to preserve the names of particular methods based on their names, arguments and other criteria. When randomize is selected new method and field names are assigned in a random fashion from the list of shortest available identifiers.

Alphabets

You can specify the alphabets used to create the new names for classes and members. You can select one of the predefined alphabets or enter your own. When creating your own alphabet the following restrictions apply:

  • The minimum length of the alphabet is two characters. Three or more are recommended for larger projects.

  • The initial characters of the alphabet must be valid starting characters for Java identifiers. You must have at least one starting character.

  • The remaining characters of the alphabet must be valid characters for Java identifiers.

Renaming — Exclude

The Renaming Excludes panel lets you compose rules that exclude classes and/or their methods and fields from renaming. Individual methods, fields, classes, or entire packages may be excluded.

When a class rule is defined it can be used to exclude the class itself from renaming or only the members matched by its method and field rules. To change this setting, right-click on the rule to edit it’s properties and change the Selects Class setting.

See Graphical Rules Editing Interface for details.

Renaming — Map Files

The Renaming Map Files panel is used to instruct DashO to read or write the renaming information for the project. This information is used to perform Incremental Obfuscation and to decode stack traces from an obfuscated application.

Input

The map input file specified is a file created by a previous DashO run. When configuring this file, DashO uses the names used in the previous run to perform Incremental Obfuscation. The map report file will make note of the input classes which are not found in the map and any classes in the map which are not found in the inputs.

Output

The information created in this file can be used for the map input file in a future DashO run. It is also used to decode a stack trace from your obfuscated application. Since accidental loss of this file could destroy your chances of incrementally updating your application in the future, DashO does not automatically overwrite this file. Selecting the Overwrite option allows DashO to overwrite an existing file.

String Encryption — Options

The String Encryption — Options panel controls the encryption of strings, the encryption techniques, and allows you to control the location where the decryption method is placed.

Encrypt Strings

Enables or disables string encryption obfuscation globally. You can control the portions of the application to which string encryption is applied by using include and exclude rules. If you do not specify any rules then all methods will have their strings encrypted.

Level

This control selects the level of string encryption to use. Level 1 uses a simple and fast decryption technique while level 10 uses a more complex but slower technique. Increasing values use various expressions to increase the complexity of decompilation as well as adding randomness factors to the implementation of decryption methods. The default level is 2.

Decrypters

This controls the number of decryption methods that will be generated and added to classes included in each output. The names and signatures of the methods are randomly selected (except when using an input file). The default number of methods is 2.

Note:

If you want decrypters to be placed globally (not kept internal to the jars where they are used) add a User Property named INJECT_DECRYPTERS_GLOBALLY and set it to true.

Decrypter Class

This setting lets you specify criteria that control which classes may serve as outer classes for generated anonymous static inner classes that will house the decrypters. If you do not specify any value DashO will choose a class from the public classes in the input. To change the selection criteria click the Edit button to bring up a properties dialog.

Note:

If you specify criteria, the decrypters will be injected based on that criteria and will be used without regards to jar boundaries.

Input

The map input file specified is a file created by a previous DashO run. Using this file, DashO creates the same decrypters used in the previous run. This is necessary for an incremental obfuscation. It is used in addition to the renaming map file. When an input file is provided, settings for the number of decrypters and the decrypter class will be ignored.

Output

The information created in this file can be used for the map input file in a future DashO run. It stores information about the types of decrypters, the method names used, and the classes where they were placed.

String Encryption — Include and Exclude

The String Encryption Include and Exclude panels let you compose rules that determine which parts of the application will have strings encrypted. Methods, classes, or entire packages can be selected. Since string encryption adds a size and runtime performance cost, you can selectively include parts of you application where sensitive string information is located or exclude sections where performance may be impacted by the runtime decryption.

See Graphical Rules Editing Interface for details.

Custom Encryption

The Custom Encryption panel lets configure your own encryption/decryption methods to be used. This allows you to provide your own level of encryption. See Using Custom Encryption for the requirements of the encryption and decryption methods.

Use Custom Encryption

Enables or disables the use of custom encryption obfuscation globally. You can control the portions of the application to which custom string encryption is applied by using include rules. You must specify at least one rule for custom encryption to work.

Encryption Jar

The jar containing the encryption class and method. This jar is external to your project. It will be used while obfuscating to encrypt strings.

Encryption Class and Method

The class and method used to encrypt the text. This method will not be part of the output. Clicking Choose… will bring up a dialog with all the methods inside the encryption jar, which match the requirements.

Decryption Class and Method

The class and method used to decrypt the text. These classes must be part of the project inputs. The class and method you specify will remain in your output (but may be renamed/obfuscated based on other project settings). Clicking Choose… will bring up a dialog with all the methods from the inputs, which match the requirements.

Custom Encryption — Include

The Custom Encryption Include panels let you compose rules that determine which parts of the application will have strings encrypted using the custom encryption. Methods, classes, or entire packages can be selected. This should be considered a subset of overall string encryption. Any class/method specified here must not be excluded from string encryption.

See Graphical Rules Editing Interface for details.

Make Synthetic — Options

The Make Synthetic — Options panel lets you control if and how synthetic flags are added to fields and methods. Synthetic flags confuse some de-compilers

Make Synthetic

This obfuscation marks methods and fields as synthetic, generated by the Java compiler, which confuses some decompilers. It has four possible settings:

  • Never – No methods or fields are affected.

  • Only private and package – Methods and fields that are private or package-private are made synthetic.

  • If not public – Methods and fields that are private, package-private, or protected are made synthetic.

  • All – All methods and fields are made synthetic.

This setting is stored in the <make-synthetic> Section of the project file.

Make Synthetic — Exclude

The Make Synthetic Exclude panel let you compose rules that determine which parts of the application will have will not be marked synthetic. Methods, classes, or entire packages can be selected.

See Graphical Rules Editing Interface for details.

Optimization — Options

The Optimization — Options panel controls the optimization settings for your project.

Optimize Byte Codes

Enables or disables byte code optimization globally. You can control the portions of the application to which byte code optimization is applied by using include and exclude rules.

Make Public

This controls the modification of access control to public. Options are to force or prohibit the conversion to public access or to let DashO decide. The default value is to let DashO decide. See the section on makepublic and nomakepublic global options for details.

Optimization — Include and Exclude

The Optimization Include and Exclude panels let you compose rules that determine which parts of the application will be optimized. Methods, classes, or entire packages can be selected.

See Graphical Rules Editing Interface for details.

PreMark

The PreMark panel is used to add a watermark to jars produced by DashO. Watermarks can only be applied to jars and this feature will be disabled when DashO's output is to a directory or an APK. If multiple jars are created the same watermark is added to all jars. Watermarks are not supported for Android.

Watermark Jar

Enables and disables the watermarking feature.

Watermark

This is the watermark string that will be applied to the jar. The characters that can be used in the watermark are determined by the character map setting.

On overflow

If the watermark string is too long to be applied the jar, DashO can either truncate the string and proceed, or halt the build.

Character map

The character map is used to encode the watermark string into a minimal set of bits.

Passphrase

The optional passphrase is used to encrypt the watermark before it is applied to the jar.

Injection — Options

The Injection — Options panel is where you control the settings for instrumenting your application for PreEmptive Analytics. You enable the instrumenting of classes for PreEmptive Analytics, define annotation processing, and select the runtime Java environment for the application. You also enter the unique identifiers for the application and the application owner. Entering this information ensures that the analytics messages are routed to the right place and displayed correctly in the PreEmptive Analytics server.

Enable Code Injection

Enables or disable the feature. Injection is used to add analytics messages, Tamper Checking, Debug Checking, and Shelf Life expiration to the application.

Honor Annotations

Should PreEmptive instrumentation annotations references in the code be honored or ignored. Annotations in the code are merged with virtual annotations to determine the instrumentation that will take place.

Strip Annotations

Should PreEmptive instrumentation annotations references be removed from the input classes? If the annotations are not stripped you may have to ship the annotations jar with your application.

Java Environment

This selects the runtime environment of your application, and determines which PreEmptive Analytics implementation jar will be used with your application.

Merge Runtime

Should the jar that implements the PreEmptive Analytics classes be merged with the application or left as a separate jar. When merged with the application DashO will first try to merge it with one of the input jars. If no jars are available, or the classes in the jar have been excluded or pruned to the point where the jar is empty, it will select the first directory. If you do not merge the runtime jar then you will need to ship it separately with your application.

Send Messages

Should messages be sent to a PreEmptive Analytics server when the application is on-line or should messages be stored for later transmission?

Store Offline

Should messages that cannot be sent to a PreEmptive Analytics server, either because the application is off-line or Send Messages is disabled, be saved for later transmission. Offline storage is supported on Java applications and Android mobile devices.

Gather Full Data

Some PreEmptive Analytics actions, such as the performance probe and the system profile, can return either full or partial data. If your do not require detailed information such as the machines manufacture and model, you can opt to return partial data. This can reduce the time required to generate the message as well as the transmission and/or storage requirements.

Omit PII

Configures if the messages sent to a PreEmptive Analytics server should contain personally identifiable information (PII). PII includes IP addresses, MAC identifiers, and names that could be used to identify the user or machine.

Endpoint

This is the location of a PreEmptive Analytics server. You can either choose the Commercial endpoint, Community Workbench endpoint, or enter a custom endpoint if you have a self-hosted server. The endpoint is like a URL but does not include the protocol.

Note:

If you choose the use the Community Workbench, there is no guarantee of privacy or security of the transmitted data and there are restrictions on the Company ID. Please see http://www.preemptive.com/support/resources/community-workbench for more information.

Use SSL

Should HTTP or HTTPS protocol be used when sending data to the endpoint?

Company ID

This is the unique ID for your company. It defaults to the information you entered in User Preferences. Clicking the button next to ID will populate the company ID field with a new random identifier.

Company Name

This is the name of your company. It defaults to the information you entered in User Preferences.

App ID

This is a unique ID for your application. Clicking the button next to ID will populate the ID field with a random identifier that you can use for your application.

App Name

This is the name of your application that will be sent to a PreEmptive Analytics server and will be used for identification purposes.

App Version

This is the version number of your application that will be sent to a PreEmptive Analytics server and will be used for identification purposes.

App Type

This identifies the application type that will be sent to a PreEmptive Analytics server and will be used for identification purposes.

Notes:
The App Type field is deprecated and will only appear if it is already configured.

All the data on this panel is optional. It can be combined or overridden by annotations in the code or by virtual annotations in DashO. The values on this panel will be used only if they are not superseded by annotations.

If both Send Messages and Store Offline are off then message generation is disabled. These global values can be overridden by real or virtual annotations. Values for both options can be either fixed Boolean values or from dynamic sources.

Offline Storage Customization

By default, messages are stored in a directory called .psrios located in the user’s home directory on the machine (e.g. C:\Users\{username}\.psrios or /usr/home/{username}/.psrios). The base location can be changed by setting the dasho_offline_ri_dir variable. This can be set in as an environment variable or java system variable. If both are set, the java system variable takes precedence. The location specified must be a directory where the user running the instrumented application has permissions to read, write, and delete files. Examples of ways to set:

  • Set an environment variable:

    • Windows: set dasho_offline_ri_dir={the full path you want}

    • Unix(csh): setenv dasho_offline_ri_dir {the full path you want}

    • Unix(bash): export dasho_offline_ri_dir={the full path you want}

  • Set on to the java command line:

    • -Ddasho_offline_ri_dir={the full path you want}
  • Set inside the codebase as follows:

    • System.setProperty(“dasho_offline_ri_dir”, {the full path you want});

    • However, this method call must occur before the Instrumentation for application start.

Note:

If dasho_offline_ri_dir is set to an invalid location or a directory where the user does not the appropriate permissions, offline messages will not be stored.

Injection — Instrumentation

DashO uses annotations to perform instrumentation. Annotations are the instructions for identifying what is to be instrumented, such as classes or methods, and how to instrument them. These annotations augment or override annotations present in the class files. The Virtual Annotations screen behaves similarly to the Graphical Rules Editing Interface.

Name

This is the name of the class, method, or annotation that is clicked on or highlighted.

Signature

This is a list of types that match the types in the method’s parameter list.

Value

This is an annotation specific value. Annotations such as FeatureStart and FeatureStop use this as the name of the feature. Not all annotations use a value.

Annotate Button

This allows you to add annotations to be applied to the method or class. You can also add the annotations by right-clicking rules or items in the class list. Only FeatureTick, FeatureStart, and FeatureStop annotations can be used multiple times on a given method.

Injection — Debug Check

The Injection — Debug Check panel is where you configure DebuggingChecks, DebuggingResponses, DebugEnabledChecks, and DebugEnabledResponses.

The Type column shows the type of Check or Response. The Description column describes the locations in the code, the methods and classes, where the Check or Response will be injected. The Properties column shows the settings for that particular Check or Response. The tooltips expand to show more details about the locations or properties.

Debugging Check

Configures a DebuggingCheck to be injected in the selected Locations. The Debugging Check uses the standard configuration.

Debugging Response

Configures a DebuggingResponse to be injected in the selected Locations. The Debugging Response uses the standard configuration.

Debug Enabled Check

Configures a DebugEnabledCheck to be injected in the selected Locations. The Debug Enabled Check uses the standard configuration.

Debug Enabled Response

Configures a DebugEnabledResponse to be injected in the selected Locations. The Debug Enabled Response uses the standard configuration.

Injection — Root Check

The Injection — Root Check panel is where you configure RootChecks and RootResponses.

The Type column shows the type of Check or Response. The Description column describes the locations in the code, the methods and classes, where the Check or Response will be injected. The Properties column shows the settings for that particular Check or Response. The tooltips expand to show more details about the locations or properties.

Root Check

Configures a RootCheck to be injected in the selected Locations. The Root Check uses the standard configuration.

Root Response

Configures a RootResponse to be injected in the selected Locations. The Root Response uses the standard configuration.

Injection — Shelf Life Check

The Injection — Shelf Life Check panel is where you configure ShelfLifeChecks in your application. DashO uses this information to create an expiration token that is placed inside your code to enforce the expiration policy. The Check is injected based on the locations configured on this screen or where a @ShelfLifeCheck code annotation is used.

The Type column shows the type of Check. The Description column describes the locations in the code, the methods and classes, where the Checks will be injected. The Properties column shows the settings for that particular Check. The tooltips expand to show more details about the locations or properties.

Defaults

The information defined here is used for all individual Checks, unless the Check(s) overrides these defaults. It is also used to define properties to be added to the generated tokens.

Key File

Enter the location of the Shelf Life key file you received from PreEmptive Solutions. This file authorizes you to add Shelf Life Checks to your application.

Expiration Date

Your application can be configured to expire on an explicit date or a certain number of days after a dynamically determined start date. Dates are always in MM/DD/YYYY format regardless of the local convention.

Warning Date

Your application can be configured to issue expiration warnings starting on either an explicit date or a certain number of days before it is due to expire. Dates are always in MM/DD/YYYY format regardless of the local convention.

Properties

You can add arbitrary properties to the expiration token that can be retrieved by your application. To use this feature you need to supply a user defined action to the ShelfLifeCheck – this action method is passed the expiration token where you will be able to retrieve these properties. Note that both the property name and values can contain DashO property references.

Note:

The information supplied on this panel can be overridden or supplemented by a ShelfLifeCheck or a @ShelfLifeCheck code annotation.

Shelf Life Check

Configures a ShelfLifeCheck to be injected in the selected Locations. The Shelf Life Check has all the standard fields except Response and adds six additional fields:

  • Expiration Date - Absolute date that the application expires in MM/DD/YYYY format.
  • Warning Date - Absolute date that warnings about expiration will start to be emitted in MM/DD/YYYY format.
  • Start Date Source - Source for the start date provided at runtime as a java.util.Date. See Specifying Sources and Actions for more information.
  • Expiration Period - Relative expiration date in number of days since the start date.
  • Warning Period - Relative warning date in number of days until the expiration date.
  • Token Source - Source of the Shelf Life token as a java.io.Reader if managing it externally. See Specifying Sources and Actions for more information.

Injection — Tamper Check

The Injection — Tamper Check panel is where you configure TamperChecks and TamperResponses.

The Type column shows the type of Check or Response. The Description column describes the locations in the code, the methods and classes, where the Check or Response will be injected. The Properties column shows the settings for that particular Check or Response. The tooltips expand to show more details about the locations or properties.

Tamper Check

Configures a TamperCheck to be injected in the selected Locations. The Tamper Check has all the standard fields and adds four additional fields:

  • Keystore - The URL to the key store; defaults to .keystore in the user's home directory. May reference DashO properties.
  • Keystore Type - The type of the key store; defaults to the value set for keystore.type in the Java security properties file. May reference DashO properties.
  • Keystore Password - The password for the key store. The user interface stores this in an encoded form but the value can be in plain text. May reference DashO properties.
  • Alias - The alias used to store the private key in the key store. May reference DashO properties.

Tamper Response

Configures a TamperResponse to be injected in the selected Locations. The Tamper Response uses the standard configuration.

Configuring Checks and Responses

Checks

Checks have many common configuration elements:

  • Action - An optional custom action. See Specifying Sources and Actions for more information. This action will generally be passed true when triggered and false when not.
  • Response - The response to take when the Check is triggered.
    • None – Do nothing (default).
    • Exit – Exit the application with a random, non-zero return code.
    • Hang – Cause the current thread, which is running the injected Check, to hang indefinitely.
    • Error – Throw a randomly selected subclass of java.lang.Error.
    • Exception – Throw a randomly selected unchecked subclass of java.lang.Exception.
  • Where - Where in the method should the code be injected?
    • Beginning – The beginning of the method (default).
    • End – The end of the method.
    • Beginning and End – Both the beginning and end of the method.
  • Send Message - Should a message be sent to PreEmptive Analytics if the Check is triggered?
  • Custom Data Source - The optional source of custom data to be sent with the message. See Specifying Sources and Actions for more information.
  • Locations - Where should the Check be inserted? See Locations.

Responses

All Responses work in a similar fashion to each other:

  • Source - The source to determine if the Check has been triggered. See Specifying Sources and Actions for more information.
  • Response - The response to take when the source indicates the Check was triggered (i.e. true).
    • None – Do nothing (default).
    • Exit – Exit the application with a random, non-zero return code.
    • Hang – Cause the current thread, which is running the injected Response, to hang indefinitely.
    • Error – Throw a randomly selected subclass of java.lang.Error.
    • Exception – Throw a randomly selected unchecked subclass of java.lang.Exception.
  • Probability - The probability the Response (i.e. Exit, Hang, Error or Exception) should happen. Expects a decimal from 0.0 to 1.0 (default: 1.0).
  • Where - Where in the method should the code be injected?
    • Beginning – The beginning of the method (default).
    • End – The end of the method.
    • Beginning and End – Both the beginning and end of the method.
  • Send Message - Should a message be sent to PreEmptive Analytics? If true, a message will be sent if the Source indicates the Check was triggered. It is not affected by Probability.
  • Custom Data Source - The optional source of custom data to be sent with the message. See Specifying Sources and Actions for more information.
  • Locations - Where should the Response be inserted? See Locations.

Locations

Checks and Responses can be injected into one or more places. You can select the methods manually or create a Selection Rule.

Selection Rule

Configures a Pattern or Regular Expression to determine which method or methods to select.

  • Type - Regular Expression or Pattern.
  • Class Modifiers - The optional class modifiers.
  • Full Class Name - The fully-qualified name of the class.
  • Method Modifiers - The optional method modifiers.
  • Method Name - The name of the method.
  • Method Signature - The method signature.

Notes:
The name and signature fields must contain valid entries.
See the description of the Modifiers attribute for values to use for the optional modifiers.
See Patterns and Regular Expressions for values to use for the names and the signature.

Output — Options

The Output — Options panel controls where DashO will place the results of the build and what form those results will take.

Create Directory/Single Jar/APK

DashO can place the results of the build into a directory, a single jar, or an APK. Changing the main output type may change other settings on this page to their defaults. See the <output> Section for instructions regarding configuring the output.

Merge inputs

When outputting to a directory, DashO can combine the obfuscated results into a single directory or keep the original packaging of the input classes.

Auto copy

Auto copy controls how non-class files are handled when merging inputs. It is available when merge is on and works as follows:

  • Merge Off

    • Non-class files from jar inputs will be copied. Non-class files from input directories will not be copied.
  • Merge On

    • Auto Copy On – Non-class files from both input directories and input jars will be copied to the output.

    • Auto Copy Off – Non-class files will not be copied to the output.

Note:

XML configuration files found when processing the non-class files may be updated allowing class and method names to be changed.

Name and Manifest

The Name field specifies the name of the output directory or jar. When merging is off only a directory can be used. DashO will use this as the root of the output and will attempt to recreate the hierarchy of the original input jars and directories.

If you have DashO create a single merged jar for you DashO can add a manifest file to the jar. The manifest can either be in the form of a text file or DashO can extract the manifest from a jar file.

Jar Options

  • Compress: Not only store data but also compress it.

  • Level: Level at which file compression should be performed. Valid values range from 0 (no compression/fastest) to 9. The default value is 6.

  • Exclude Directory Entries: Store only file entries, not directory entries.

  • Preserve Jars With No Classes: Output jars when they have no remaining classes. This can be used to output resource jars.

Constant Pool Tag

The optional constant pool tag text is inserted into every class in the resulting output. See <constpooltag> for details.

SourceFile Tag

The SourceFile attribute of every resulting output class is set to the given value. See <sourcefile> for details.

Output — APK

The Output — APK panel configures settings specific to APK output.

Build Tools Directory

Specifies the location for the Android build tools. The directory configured should contain the zipalign command.

Zipalign

Specifies if the output APK should be aligned (uses zipalign). This box is only enabled if the APK is being signed.

Output — Reports

The Output — Reports panel configures the generation of reports that detail the results of the build.

Report file

Specifies the name and location for a report outlining the class and member removal and renaming performed by DashO. A summary is given detailing the total methods/fields/constant pool entries, as well as the final number and percentage of reduction after DashO execution. It also contains information about dynamically loaded classes, including reflection and Class.forName() calls.

Renaming Report File

This specifies the name and location for a report listing old and new names for renamed classes as well as their renamed members.

Output — Preverification

You can choose to run the preverifier on your CLDC application after DashO is finished processing your class files. You can enable or disable preverification by checking the Run Preverifier checkbox.

By default DashO will try to find the preverifier application preverify on the system path. If you need to run a particular version of the preverifier you can explicitly specify which one to run.

No Finalize

Pass -nofinalize to the preverifier: no finalizers are allowed in the input.

No Floating Point

Pass -nofp to the preverifier: no floating point operations allowed in the input.

No Native Methods

Pass -nonative to the preverifier: no native methods allowed.

Output — Signing

You can have DashO sign the output jars or APK that it produces. You can enable or disable signing by checking the Sign Jars/APK checkbox.

By default DashO will try to find the signing application jarsigner on the system path. If you need to run a particular version of jarsigner or want to run apksigner, you can explicitly specify which one to run.

Key Store

This information defines the key store that contains the private key used for signing. Only the Password is required. The Type defaults to type specified in the global keystore.type security property and the Location defaults to the .keystore file in your home directory. Passwords that do not contain property references are stored in an encrypted form in the project file.

Signing Key

This information specifies the private key that is used to perform the signing. Only the Alias value is required. The Password defaults to the password specified for the key store. This password is also stored encrypted in the project file if it does not contain any property references.

Options

Signature File

This corresponds to the -sigFile option on jarsigner and the --v1-signer-name option on apksigner.

Internals .SF & Sections Only

These values correspond to the -internalsf and -sectionsonly options of jarsigner. They are not applicable with apksigner.

Additional Arguments

This field allows you to specify any additional flags. If signing APKs using jarsigner you may need to enter additional arguments (E.G. -sigalg SHA1withRSA -digestalg SHA1). If using apksigner you may want to enter additional arguments to determine the APK signature scheme (E.G. --v1-signing-enabled [true|false] --v2-signing-enabled [true|false] or --min-sdk-version nn --max-sdk-version nn (where nn is an sdk version)).

Note:

Signing will pass the passwords via the environment instead of the command line. If you need to use an older version of jarsigner which does not support this, add a User Property named SIGN_WITH_PLAINTEXT_PASSWORDS and set it to true.

Please see the jarsigner and apksigner documentation for details on the arguments.

Results

The Results panel shows the class hierarchy of the input classes of the project and the results of renaming.

Using the Graphical Rules Editor

Many of the panels in DashO’s user interface are rule editors, primarily for including and excluding elements in your application in an obfuscation transformation. A rule editor is divided into two lists – a class list on the left hand side that shows the classes and members of the input and a rule list on the right. The rules specify what parts of the input are affected by the operation and in some cases the actions to be taken. The rules editor is used to set rules for the following operations:

Other parts of DashO, such as entry points, use an interface very similar to the rule editor.

Creating Rules

There are several ways to create rules in the interface:

  • Right-click items in the class list – you can click on items in the class list to bring up a contextual menu. From there you can build a rule that will match the item that you have selected. If you hold down the shift key when you create the rule the rule will be made a regular expression. If you create a rule for a method or a field, DashO will add the new rule to a pre-existing class rule or create one if needed.

  • Drag and drop items from the class list – you can drag an item from the class list and drop it on the rules. If you drag and drop either a method or a field, DashO will add the new rule to a pre-existing class rule or create one if needed.

  • Using the buttons – You can click the new buttons to the right of the rules list to create a new entry. A new rule will be created with a dummy name that you can edit.

Editing Rules

The basic parts of a rule can be modified directly in the editor. The name of any item and the signature or methods can be changed by using the text field immediately below the rules list. Specialized editors may also provide for direct editing of their values.

To access all the settings for a rule right-click on the rule and select the Properties item on the contextual menu. In the properties box you will find the settings for values such as:

  • Modifiers – the Java modifiers, or their negation, which are required for this rule to match an item. See the description of the Modifiers attribute for values you can use here.

  • Name – the name of the item that the rule affects. This can be a constant value, a pattern, or a regular expression.

  • Signature – the signature for methods.

  • Type – determine how the name and/or signature are to be interpreted. See Patterns and Regular Expressions for details.

  • Select class – For rules that affect the class itself as well as its members, this setting determines if the rule applies to the class, or if the class is just a container for nested field or method rules.

  • Renaming controls – Entry points are non-renameable by default. Some types of entry points can be made renameable and these controls determine if the class and/or its members can be renamed.

  • Values for annotations – Virtual annotations can contain many specialized values. Some contain only a generic value – use the tooltip display to determine its use. Annotations that perform an action will also have a where value. This determines the location in the method where the action will take place.

Previewing rules

You can use the preview function to determine what will be affected by the rules. You can elect to preview a single rule or all rules. Right-click a rule to bring up the contextual menu and select Preview Rule or Preview All. The items in the class list that will be affected by the rule will be displayed in bold. You can use the contextual menu in either list to clear the highlighting of rules.

Patterns and Regular Expressions

A simple rule selects a particular item, such as a class, using the name of the item literally. A rule can also select items by using patterns or by using regular expressions. See Patterns and Regular Expressions.

Regular Expressions are checked automatically. If your expression has an error a red X will be displayed next to it. Move the pointer over the rule and the tooltip will display the location of the error and its description.

Note:

Regular expressions apply to the rule as a whole. If a class name is specified as a regular expression, all member names will be treated as regular expression. Patterns do not have this restriction.

Combining Include and Exclude Rules

DashO can use a combination of inclusion and exclusion to determine what parts of your application to obfuscate. When an obfuscation transformation allows for the definition of both includes and exclude it is important to remember how the two are combined:

  • If no include rules are defined all items are included by default.

  • If no exclude rules are defined no items are excluded by default.

  • Includes are determined first, then excludes. An item must be included by at least one rule and not excluded by any rule to have a transformation apply to it.

PreEmptive Protection - DashO Version 8.2.0. Copyright © 2017 PreEmptive Solutions, LLC