ArkGuard Principles and Capabilities for Bytecode Obfuscation

Glossary

Obfuscation Scope

Supported Languages

ArkGuard supports the ArkTS/TS/JS languages. For JSON, only filename obfuscation is supported. It does not support C/C++ or resource files.

Obfuscation Capabilities

ArkGuard provides basic name obfuscation, but does not support advanced features like control obfuscation or data obfuscation.

It primarily offers renaming and trustlist configuration for retention.

Limitations of Obfuscation Capabilities

Language Limitations Code obfuscation tools vary in type analysis mechanisms, obfuscation strategies, and execution efficiency based on the target language. For example, ProGuard targets strongly-typed languages like Java, where each type has a clear definition source. This feature makes the type relationship tracing and processing in the obfuscation process more accurate, greatly reducing the need for retention rules.

In contrast, ArkGuard targets JS, TS, and ArkTS. Suppose ArkGuard supports configuring a trustlist for specific types. JS supports dynamic modification of objects and functions at runtime, but obfuscation is a static process in the compilation phase. This difference may cause a failure in parsing obfuscated named at runtime, resulting in runtime exceptions. TS and ArkTS use a structural type system, where different named types with the same structure are considered as equivalent types. Therefore, it is difficult to trace the exact source of types.

As such, when using ArkGuard, you need to configure trustlists for more syntax scenarios. Moreover, ArkGuard uses a global property retention mechanism that retains all properties with the same name according to the trustlist. It does not support precise retention settings for specific types.

To illustrate, consider this example:

Assume that ArkGuard allows the configuration of a trustlist for specific types. If class A1 is configured in a trustlist with its property prop1, but prop1 in class A2 is not in the trustlist, passing an instance of A2 (a2) to the test function would cause issues when accessing the prop1 property.

// example.ts
// Before obfuscation:
class A1 {
  prop1: string = '';
}

class A2 {
  prop1: string = '';
}

function test(input: A1) {
  console.info(input.prop1);
}

let a2 = new A2();
a2.prop1 = 'prop a2';
test(a2);

// After obfuscation:
class A1 {
    prop1: string = '';
}

class A2 {
    a: string = '';
}

function test(input: A1) {
    console.info(input.prop1);
}

let a2 = new A2();
a2.a = 'prop a2';
test(a2);

You should be aware of these differences and use unique names to achieve better obfuscation results.

Limited security assurance

Like other obfuscation tools, ArkGuard increases reverse engineering difficulty but cannot prevent it entirely.

You should not rely solely on ArkGuard for security. For higher security requirements, consider application encryption and third-party hardening measures.

Obfuscation Mechanism and Process

The following figure shows a simplified compilation process.

You can enable the obfuscation feature in the build-profile.json5 file of the module so that the .abc files can be automatically obfuscated during compilation and packaging. For details, see Using ArkGuard for Bytecode Obfuscation.

During obfuscation, the tool reads the obfuscation switch. If the switch is enabled, it parses the obfuscation configuration file, merges rules according to the merging strategies, applies bytecode obfuscation to .abc files generated, and writes the obfuscated files to the build directory. You can verify the obfuscation effect by examining the output in the build directory.

Before using obfuscation, you are advised to learn about the capabilities of obfuscation options and retention options, and select the appropriate capabilities for your needs.

Obfuscation Options

Summary of Existing Obfuscation Options

-disable-obfuscation

Disables code obfuscation.

If this option is configured, the default obfuscation capabilities and all configured obfuscation and retention options become invalid. This has the same effect as disabling obfuscation in the module's build-profile.json5 file.

-enable-property-obfuscation

Enables property name obfuscation. The effect is as follows:

// test.ts
// Before obfuscation:
class TestA {
  static prop1: number = 0;
}
TestA.prop1;

// After obfuscation:
class TestA {
    static i: number = 0;
}
TestA.i;

If this option is configured, all property names except the following are obfuscated:

• Property names of classes and objects that are directly imported or exported by using import or export in case that the -enable-export-obfuscation option is not enabled. For example, the property name data in the following example is not obfuscated.

  // example.ts
  export class MyClass01 {
    data1: string;
  }
  

  BytecodeObfuscation.ts

• Property names in ArkUI components. For example, message and data in the following example are not obfuscated.

  // example.ets
  @Component struct MyExample {
    @State message: string = "hello";
    data: number[] = [];
  
    build() {
    }
  }
  

  BytecodeObfuscation.ets

• Property names specified in retention options.

• Property names in the SDK API list. The SDK API list is a set of names automatically extracted from the SDK during build. Its cache file is systemApiCache.json, which is stored in build/default/cache/{...}/release/obfuscation in the project directory.

• String literal property names. For example, firstName and personAge in the following example are not obfuscated.

  let person = {"firstName": "abc"};
  person["personAge"] = 22;
  

  BytecodeObfuscation.ts

• Annotation member names. For example, authorName and revision in the following example are not obfuscated.

  @interface MyAnnotation1 {
    authorName: string;
    revision: number;
  }
  

  BytecodeObfuscation.ets

-enable-string-property-obfuscation

Enables obfuscation of string literal property names. It is effective only if property name obfuscation is enabled.

To obfuscate string literal property names, you must use this option together with -enable-property-obfuscation. Example:

-enable-property-obfuscation
-enable-string-property-obfuscation

According to the preceding configuration, the obfuscation effect of "firstName" and "personAge" is as follows:

let person = {"firstName": "abc"};
person["personAge"] = 22;

// After obfuscation:
let person = {"a": "abc"};
person["b"] = 22;

NOTE 1. If a string literal property name contains special characters, for example, let obj = {"\n": 123, "": 4, " ": 5}, you are advised not to use the -enable-string-property-obfuscation option because these names may fail to be retained using retention options. Special characters refer to characters other than lowercase letters a-z, uppercase letters A-Z, digits 0-9, and underscores (_).

2. The property trustlist of the SDK API list does not contain string constants used in the declaration file. For example, the string 'ohos.want.action.home' in the example is not included in the property trustlist.

// Part of the SDK API file @ohos.app.ability.wantConstant:
export enum Params {
  ACTION_HOME = 'ohos.want.action.home'
}
// Source code example:
let params = obj1['ohos.want.action.home'];

When the -enable-string-property-obfuscation option is used, use the -keep-property-name option if you want to retain the property names in the SDK API string constants in the code, for example, obj['ohos.want.action.home'].

-enable-toplevel-obfuscation

Enables obfuscation of top-level scope names. The effect is as follows:

// Before obfuscation:
let count = 0;

// After obfuscation:
let s = 0;

If this option is configured, the names of all top-level scopes except the following are obfuscated:

• Names that are directly imported or exported by using import or export in case that the -enable-export-obfuscation option is not enabled.
• Top-level scope names that are not declared in the current file.
• Top-level scope names specified by retention options.
• Top-level scope names in the SDK API list.

-enable-export-obfuscation

Enables obfuscation for imported/exported names. The effect is as follows:

// Before obfuscation:
namespace ns {
  export type customT = string;
}

// After obfuscation:
namespace ns {
    export type h = string;
}

If this option is configured, names imported/exported in non-top-level scopes will be obfuscated. To obfuscate names imported/exported in the top-level scope, use this option with -enable-toplevel-obfuscation. To obfuscate imported or exported property names, use this option with -enable-property-obfuscation. Note the following special scenarios:

• Names exported from remote HARs (packages whose real paths are in oh_modules) and their property names are not obfuscated.
• Names and property names specified by retention options are not obfuscated.
• Names in the SDK API list are not obfuscated.

-enable-filename-obfuscation

Enables obfuscation of file/folder names. The effect is as follows:

// Before obfuscation:
import * as m from '../test1/test2';
import { foo } from '../test1/test2';
// ...
const module = import('../test1/test2');

// After obfuscation:
import * as m from '../a/b';
import { foo } from '../a/b';
const module = import('../a/b');

If this option is configured, all file/folder names except the following are obfuscated:

• File or folder names specified by the main and types fields in the oh-package.json5 file.
• File or folder names specified by the srcEntry field in the module.json5 file of the module.
• File or folder names specified by -keep-file-name.
• File or folder names in non-ECMAScript module reference mode (for example, const module = require('./module')).
• File or folder names in non-path reference mode. For example, json5 in the example import module from 'json5' is not obfuscated.

NOTE

• For files that the system needs to load files during application running, manually configure them into a trustlist using the -keep-file-name option. Otherwise, the application may fail to run.

• The names of the compilation entry file, ability component file, and Worker multithreaded file cannot be obfuscated and have been automatically added to the trustlist in DevEco Studio 5.0.3.500. No manual configuration is required. For other files that cannot be obfuscated, you need to manually configure their names in the trustlist.

-compact

Removes unnecessary spaces and all line feeds.

If this option is configured, all code is compressed to one line. The effect is as follows:

// test.ts
// Before obfuscation:
class TestA {
  static prop1: number = 0;
}
TestA.prop1;

// After obfuscation:
class TestA { static prop1: number = 0; } TestA.prop1;

NOTE

The stack information built in release mode contains the line number of code, but not the column number. Therefore, when the compact option is used, the source code cannot be located based on the line number in the stack information.

-remove-log

Removes calls to console.* statements, provided the return value is not used. The effect is as follows:

// Before obfuscation:
if (flag) {
  console.info("hello");
}

// After obfuscation:
if (flag) {
}

If this option is configured, the console.* statements in the following scenarios are removed:

1. Calls at the top layer of a file.

   console.info("in tolevel");
   

   BytecodeObfuscation.ts

2. Calls within a code block.

   function foo1() {
     console.info('in block');
   }
   

   BytecodeObfuscation.ts

3. Calls with a module or namespace.

   // example.ts
   namespace ns {
     console.info('in ns');
   }
   

   BytecodeObfuscation.ts

4. Calls within a switch statement. Example:

   switch (value) {
     case 1:
       console.info("in switch case");
       break;
     default:
       console.info("default");
   }
   

   BytecodeObfuscation.ts

-print-namecache

Saves the name cache to the specified file path. The name cache contains the mappings of names before and after obfuscation. The filepath parameter is mandatory. It supports relative and absolute paths. For a relative path, the start point is the current directory of the obfuscation configuration file. The file name extension in filepath must be .json.

Example:

-print-namecache
./customCache/nameCache.json

NOTE

A new namecache.json file is generated each time the module if fully built. Therefore, save a copy of the file each time you publish a new version.

-apply-namecache

Reuses a name cache file in the specified file path. The filepath parameter is mandatory. It supports relative and absolute paths. For a relative path, the start point is the current directory of the obfuscation configuration file. The file name extension in filepath must be .json.

This option should be used in incremental build scenarios. After this option is enabled, the names will be obfuscated according to the cache mappings. If there is no corresponding name, new random names are used.

Example:

-apply-namecache
./customCache/nameCache.json

By default, DevEco Studio saves cache files in a temporary cache directory and automatically applies the cache files during incremental build.

Default cache directory: build/default/cache/{...}/release/obfuscation

-enable-lib-obfuscation-options

Merges obfuscation options of dependent modules into the obfuscation configuration of the current module.

Obfuscation configuration includes obfuscation options and retention options.

By default, the effective obfuscation configuration is the merged result of the current module's obfuscation configuration and the dependent modules' retention options.

When this option is configured, the effective obfuscation configuration is the merged result of the current module's obfuscation configuration and the dependent modules' obfuscation configuration.

For details about the merging logic, see Obfuscation Rule Merging Strategies.

-enable-bytecode-obfuscation

Enables or disables bytecode obfuscation. This function is disabled by default.

-enable-bytecode-obfuscation-debugging

Controls whether bytecode obfuscation outputs debugging information. If this option is enabled, obfuscation logs are generated. For details, see Viewing Obfuscation Effects. This option is not enabled by default.

Use this option with -enable-bytecode-obfuscation.

Retention Options

Summary of Existing Retention Options

-keep-property-name

Retains the specified property names. Name wildcards are supported. The following configuration is used to retain properties named age, firstName, and lastName:

-keep-property-name
age
firstName
lastName

NOTE

1. This option takes effect when -enable-property-obfuscation is used.

2. The property trustlist applies globally. That is, if multiple properties with the same name exist in the code, they will not be confused as long as they match the names in the trustlist configured in -keep-property-name.

Which property names should be retained?

1. If object properties are defined via string concatenation, variable access, or the defineProperty method within the code, these property names should be retained. Example:

// example.js
let obj = {x0: 0, x1: 0, x2: 0};
for (let i = 0; i <= 2; i++) {
    console.info(obj['x' + i]); // x0, x1, and x2 should be retained.
}

Object.defineProperty(obj, 'y', {}); // y should be retained.
Object.getOwnPropertyDescriptor(obj, 'y'); // y should be retained.
console.info(obj.y);

obj.s1 = 'a';
let key = 's1';
console.info(obj[key]); // The variable value s corresponding to key should be retained.

obj.t1 = 'b';
console.info(obj['t' + '1']); // t1 should be retained.

For the following string literal property calls, you can choose to retain them.

// Obfuscation configuration:
// -enable-property-obfuscation
// -enable-string-property-obfuscation
obj2.t = "0";
console.info(obj2['t']); // 't' will be correctly confused, and t can be retained.

obj2['v'] = "0";
console.info(obj2['v']); // 'v' will be correctly confused, and v can be retained.

2. In the case of indirect exports, for example, export MyClass and let a = MyClass; export {a}, if you do not want to obfuscate property names, use retention options to retain them. For property names of directly exported classes or objects, such as firstName and personAge in the following example, if you do not want to obfuscate them, use retention options to retain them.

// myclass.ts
export class MyClass02 {
  person = {firstName: "123", personAge: 100};
}

3. If you want to use an API (for example, foo in the example) of the .so library in the ArkTS/TS/JS file, manually keep the API name.

export const add: (a: number, b: number) => number;

// test.ets
import testNapi from 'libentry.so'
// ...
testNapi.add(2, 3); // add should be retained. Example: -keep-property-name foo

4. Fields used in JSON parsing and object serialization should be retained.

// Example JSON file structure (test.json):
/*
{
  "jsonProperty": "value",
  "otherProperty": "value2"
}
*/
import jsonData from './test.json';
// ...
let jsonProp = jsonData.jsonProperty; // jsonProperty should be retained.

class jsonTest {
  prop1: string = '';
  prop2: number = 0
}

let obj = new jsonTest();
const jsonStr = JSON.stringify(obj); // prop1 and prop2 will be obfuscated and should be retained.

5. Database-related fields should be manually retained. For example, properties in the database key-value pair type (ValuesBucket):

const valueBucket: ValuesBucket = {
  ID1: 'ID1', // ID1 should be retained.
  NAME1: 'jack', // NAME1 should be retained.
  AGE1: 20, // AGE1 should be retained.
  SALARY1: 100 // SALARY1 should be retained.
}

6. When custom decorators are used on member variables, member methods, or parameters in the source code, and the intermediate product of source code compilation is a JS file (for example, compiling release-mode source code HAR or source code containing @ts-ignore or @ts-nocheck), the names of these member variables or member methods should be retained. This is because the names of these member variables/methods are hardcoded as string literals during conversion from TS syntax to standard JS syntax. Example:

function CustomDecorator(target: Object, propertyKey: string) {}
function MethodDecorator(target: Object, propertyKey: string, descriptor: PropertyDescriptor) {}
function ParamDecorator(target: Object, propertyKey: string, parameterIndex: number) {}

class A {
  // 1. Member variable decorator
  @CustomDecorator
  propertyName1: string = ""   // propertyName1 should be retained.
  // 2. Member method decorator
  @MethodDecorator
  methodName1() {} // methodName1 should be retained.
  // 3. Method parameter decorator
  methodName2(@ParamDecorator param: string): void {} // methodName2 should be retained.
}

-keep-global-name

Retains the specified top-level scope names and imported/exported element names. Name wildcards are supported. You can perform the configuration as follows:

-keep-global-name
Person
printPersonName

Names exported from the namespace can also be retained using the -keep-global-name option. The following is an example:

// example.ts
export namespace Ns {
  export const myAge = 18 // -keep-global-name myAge: retains variable myAge.
  export function myFunc() {} // -keep-global-name myFunc: retains function myFunc.
}

NOTE

The trustlist specified by -keep-global-name applies globally. That is, if multiple top-level scope names or exported names exist in the code, they will not be confused as long as they match the names in the trustlist configured in -keep-global-name.

Which top-level scope names should be retained?

1. In JS, variables in the top-level scope are properties of globalThis. If globalThis is used to access a global variable in the code, the variable name should be retained.

Example:

var a = 0;
console.info(globalThis.a);  // a should be retained.
function foo2(){}
globalThis.foo2();           // foo2 should be retained.
var c = "0";
console.info(c);             // c can be correctly obfuscated.
function bar(){}
bar();                      // bar can be correctly obfuscated.
class MyClass {}
let d = new MyClass();      // MyClass can be correctly obfuscated.

2. When importing API names from .so libraries using named imports, if both -enable-toplevel-obfuscation and -enable-export-obfuscation are configured, the API names should be manually retained.

// src/main/cpp/types/libentry/Index.d.ts
declare function testNapi2(): void;
declare function testNapi3(): void;

// example.ets
import { testNapi2, testNapi3 as myNapi } from 'libentry.so' // testNapi2 and testNapi3 should be retained.
// ...
testNapi2();
myNapi();

-keep-file-name

Retains the file/folder names. You do not need to specify the file name extension. Name wildcards are supported. Example:

-keep-file-name
index
entry

Which file names should be retained?

1. When require is used to import file paths, the path should be retained. This is because ArkTS does not support CommonJS syntax.

// example.js
const module1 = require('./file1'); // file1 should be retained.

2. For dynamically imported paths, since it is impossible to determine whether the parameter in the import function is a path, the path should be retained.

// file2.ts
export function foo () {}

// main.ts
const moduleName = './file2'         // The path name file2 corresponding to moduleName should be retained.
const module2 = import(moduleName)

3. When cross-package dynamic routing is used for navigation, the path passed to the dynamic routing should be retained. Dynamic routing provides two modes: system routing table and custom routing table. If a custom routing table is used for redirection, the way to configure a trustlist is consistent with the second dynamic reference scenario. However, if the system routing table is used for redirection, the path corresponding to the pageSourceFile field in the resources/base/profile/route_map.json file of the module should be added to the trustlist.

{
  "routerMap": [
    {
      "name": "PageOne",
      "pageSourceFile": "src/main/ets/pages/directory/PageOne.ets",  // The path should be retained.
      "buildFunction": "PageOneBuilder",
      "data": {
        "description" : "this is PageOne"
      }
    }
  ]
}

-keep-dts

Adds names (such as class names, and property names) in the .d.ets file of the specified file path into the trustlist of -keep-global-name and -keep-property-name. Note that filepath supports only absolute paths and can be specified as a directory. In this case, the names in all .d.ets files in the directory are retained.

-keep

Retains all names (such as class names, and property names) in the specified relative file path. filepath can be a file or directory. If it is a directory, the files in the directory and subdirectories are not obfuscated.

filepath must be a relative path. ./ and ../ are relative to the directory where the obfuscation configuration file is located. Path wildcards are supported.

-keep
./src/main/ets/fileName.ts   // Names in the fileName.ts file are not obfuscated.
../folder                    // Names in all the files under the folder directory and its subdirectories are not obfuscated.
../oh_modules/json5          // Names in all the files in the imported third-party library json5 are not obfuscated.

NOTE 1. For files retained by -keep filepath, all exported names and their properties in the dependency chain of these files are also retained. 2. This option does not affect the capability provided by the -enable-filename-obfuscation option.

Wildcards Supported by Retention Options

Name Wildcards

The table below lists the name wildcards supported.

Example Retain all property names that start with a.

-keep-property-name
a*

Retain all single-character property names.

-keep-property-name
?

Retain all property names.

-keep-property-name
*

Path Wildcards

The table below lists the path wildcards supported.

Example

Retain the c.ets file in the ../a/b/ directory (excluding subdirectories).

-keep
../a/b/*/c.ets

Retain the c.ets file in the ../a/b/ directory and its subdirectories.

-keep
../a/b/**/c.ets

Retain all files except the c.ets file in the ../a/b/ directory. The exclamation mark (!) cannot be used alone. It can only be used to exclude existing cases in the trustlist.

-keep
../a/b/
!../a/b/c.ets

Retain all the files in the ../a/ directory (excluding subdirectories).

-keep
../a/*

Retain all the files in the ../a/ directory and its subdirectories.

-keep
../a/**

Retain all the files in the module.

-keep
./**

NOTE 1. In these options, the wildcards *, ?, and ! cannot be used for other meanings. Example:

class A {
    '*'= 1
}
-keep-property-name
*

In this example, * indicates any number of characters, and all property names are retained (not obfuscated). It does not mean that only the * property is retained.

2. In the -keep option, only the path format / is allowed. The path format \ or \ is not.

Obfuscation Rule Merging Strategies

During module compilation, by default, the effective obfuscation rules are the merged result of the current module's obfuscation rules and the dependent modules' obfuscation rules. The specific rules are as follows:

Obfuscation rules of the current module

Content of the obfuscation configuration file specified by the arkOptions.obfuscation.ruleOptions.files field in the current module's configuration file build-profile.json5.

Obfuscation rules of dependent modules

Depending on the type of dependent module, the obfuscation rules come from the following two sources:

• Local HAR/HSP modules

  Content of the obfuscation configuration file specified by the arkOptions.obfuscation.consumerFiles field in the module's configuration file build-profile.json5.

• Remote HAR/HSP packages

  Content of the obfuscation.txt file in the remote HAR/HSP package.

If an HAP, HSP, or HAR is built, the final obfuscation rules are the merge of the following files:

• ruleOptions.files attribute of the current module
• consumerFiles attribute of the dependent local HSP
• consumerFiles attribute of the dependent local HAR
• obfuscation.txt files in the dependent remote HAR and remote HSP

If an HAR is built, the obfuscation.txt file in the generated remote HAR is the merge of the following files:

• Its own consumerFiles attribute
• consumerFiles attribute of the dependent local HSP
• consumerFiles attribute of the dependent local HAR
• obfuscation.txt files in the dependent remote HAR and remote HSP

If an HSP is built, the obfuscation.txt file in the generated remote HSP only contains its own consumerFiles attribute. If a HAP is built, no obfuscation.txt will be generated.

Obfuscation Rule Merging Logic

Obfuscation options: The OR operation is used for merging. If a switch option exists in any of the rule files being merged, it will be included in the final merged result.

Retention options: When merging, for trustlist options, their content is the union of all.

• If the current module's obfuscation configuration does not include the -enable-lib-obfuscation-options option, the merged result is the current module's obfuscation rules and the retention options in the dependent modules' obfuscation rules.

• If the current module's obfuscation configuration includes the -enable-lib-obfuscation-options option, the merged result is the current module's obfuscation rules and the dependent modules' obfuscation rules.

When the obfuscation configuration file specified by consumerFiles contains the following obfuscation rules, these rules will be merged into the obfuscation.txt file of a remote HAR or remote HSP, whereas other obfuscation rules will not.

// Obfuscation options
-enable-property-obfuscation
-enable-string-property-obfuscation
-enable-toplevel-obfuscation
-remove-log
// Retention options
-keep-property-name
-keep-global-name

Precautions for Obfuscation in HSP and HAR

1. If the obfuscation configuration file specified by consumerFiles contains the above obfuscation options, when other modules depend on this module, these obfuscation options will be merged with the main module's obfuscation rules, thereby affecting the main module. Therefore, you are not advised to configure obfuscation options in the consumer-rules.txt file. Instead, configure only retention options in the file.

2. If the -keep-dts option is added to the obfuscation configuration file specified by consumerFiles, it will be converted into -keep-global-name and -keep-property-name.