HarmonyOS Code Obfuscation: Harden Your Apps Against Reverse Engineering

Overview

Code obfuscation increases code complexity and ambiguity, raising the difficulty for attackers to analyze the code. It serves four key purposes:

Protect intellectual property: Prevents easy copying and theft of software code, increasing reverse engineering difficulty.

Prevent reverse engineering: Makes it harder to analyze the software's working principles and implementation details, protecting against malicious modification or cracking.

Improve security: Reduces vulnerabilities and security risks, increasing the difficulty for attackers to exploit vulnerabilities.

Lower piracy and fraud risk: Increases the difficulty of cracking license verification or bypassing payment mechanisms, reducing piracy and fraud.

Obfuscating engineering source code raises cracking difficulty, shortens class and member names, and reduces application size.

Enabling Obfuscation

Starting from DevEco Studio 4.0 Beta1, the hvigor plugin provides code obfuscation. Three conditions must be met:

The project uses the Stage model.

Compilation is in Release mode.

The module's build-profile.json5 file enables obfuscation configuration.

"arkOptions":{
  "obfuscation":{
    "ruleOptions":{
      "enable": true,
      //...
    }
  }
}

Note: enable defaults to false, so obfuscation is off by default.

After meeting the conditions, select the target module and click Build → Make Module to compile.

Building HAR (Static Library)

If the project or module is a Static Library, it becomes a HAR. There are three build modes:

Debug mode: Packages source code directly, no obfuscation.

Release mode: Compiles, obfuscates, and minifies code.

Bytecode format HAR: When obfuscation is enabled, the compiler first obfuscates intermediate source files, then generates ABC bytecode.

Obfuscation Configuration Capabilities

Compiler Options

In DevEco Studio versions before 5.0.3.600, only parameter names and local variable names were obfuscated by default. From version 5.0.3.600 onward, four recommended options are enabled by default:

-enable-property-obfuscation

-enable-toplevel-obfuscation

-enable-filename-obfuscation

-enable-export-obfuscation

Developers can further modify the obfuscation configuration as needed.

Obfuscation Configuration File

Each module contains a build-profile.json5 file for configuring obfuscation enablement and rule files.

New projects include an obfuscation-rules.txt file per module for rule configuration.

In the example above, -enable-property-obfuscation and -enable-toplevel-obfuscation are added, enabling property obfuscation and top-level scope name obfuscation.

Detailed usage and sample code for each obfuscation option are available in the official code obfuscation documentation.

Optimization Suggestions

Developers may find many unobfuscated source names in cache files or SDK files. Two main causes and fixes:

Too few obfuscation options enabled: Enable -enable-property-obfuscation, -enable-toplevel-obfuscation, -enable-export-obfuscation, and -enable-filename-obfuscation.

Source names clash with system or language whitelists: Add suffixes to avoid whitelist conflicts.

Rule Merging Strategy

When compiling a module, the effective obfuscation rules are the merge of the current module's rules and its dependencies' rules. Refer to the official documentation for specifics.

Viewing Obfuscation Results

After compilation, the module's build directory contains:

Source compilation and obfuscation cache: build/[…]/release/<module-name> Name mapping table and system API whitelist: build/[…]/release/obfuscation Name mapping file: nameCache.json — records source name mappings.

System API whitelist file: systemApiCache.json — records SDK interface and property names.

Debugging

Obfuscation changes code names, making runtime crash stack logs hard to interpret because the stack no longer matches the source code. Without preserved debug information, line numbers and name changes prevent accurate issue location. Enabling options like -enable-property-obfuscation and -enable-toplevel-obfuscation may cause runtime crashes or functional errors. Developers must restore error stacks, investigate, and configure whitelists to ensure correct functionality.

Function Call Stack Restoration

Obfuscated applications have altered code names, so error stacks differ from source code. Handling instructions are in the official Error Stack Restoration guide.

Deobfuscation Tool: hstack

hstack

requires Node.js in the environment variables. Detailed usage is in the hstack documentation.

Using Third-Party Hardening

Beyond HarmonyOS's built-in obfuscation, developers can use advanced obfuscation and hardening from third-party security vendors. Multiple vendors have started HarmonyOS support; developers choose services based on needs and coordinate directly with vendors.

Due to HarmonyOS code signing, app encryption, and app store review requirements, third-party hardening must satisfy six constraints:

Must not hide sensitive system API calls; reviewers must clearly see app capabilities.

Must not obfuscate non-proprietary SDKs; SDK vendors should obfuscate their own SDKs. Obfuscating third-party SDKs affects app store fingerprint verification.

Hardened apps must not contain malicious behavior, or they risk removal.

Must not use third-party virtual machines; HarmonyOS restricts dynamic code loading via code signing, which may break the app.

Must not tamper with Ark bytecode files; this can break the app and affect app store security review.

Must not hook system libraries; this affects app store security review.