81b3c82d16
- Translate arkguard-obfuscation.md (ArkGuard code obfuscation guide) - Translate hstack.md (stack trace analysis tool) - Translate codelinter.md (code linting tool) - Translate hvigor-commandline.md (Hvigor build tool) - Fix capitalization: ArkTs -> ArkTS in README title
127 lines
3.7 KiB
Markdown
127 lines
3.7 KiB
Markdown
# ArkGuard Code Obfuscation Guide
|
|
|
|
ArkGuard is the officially recommended code obfuscation tool for HarmonyOS, designed to enhance application security and prevent reverse engineering.
|
|
|
|
## Requirements
|
|
|
|
- **DevEco Studio**: Version 5.0.3.600 or above
|
|
- **Project Model**: Stage model only
|
|
- **Effective Mode**: Only active in Release mode
|
|
|
|
## Enabling Obfuscation
|
|
|
|
Configure in the module's `build-profile.json5`:
|
|
|
|
```json
|
|
{
|
|
"arkOptions": {
|
|
"obfuscation": {
|
|
"ruleOptions": {
|
|
"enable": true,
|
|
"files": ["./obfuscation-rules.txt"]
|
|
},
|
|
"consumerFiles": ["./consumer-rules.txt"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Obfuscation Rules Configuration
|
|
|
|
Create `obfuscation-rules.txt` in the project root directory:
|
|
|
|
```text
|
|
# Enable property obfuscation
|
|
-enable-property-obfuscation
|
|
|
|
# Enable top-level scope name obfuscation
|
|
-enable-toplevel-obfuscation
|
|
|
|
# Enable filename obfuscation
|
|
-enable-filename-obfuscation
|
|
|
|
# Enable import/export name obfuscation
|
|
-enable-export-obfuscation
|
|
```
|
|
|
|
## Whitelist Configuration
|
|
|
|
Certain names must not be obfuscated (e.g., dynamic property names, API fields, database fields):
|
|
|
|
```text
|
|
# Keep property names
|
|
-keep-property-name apiKey
|
|
-keep-property-name userId
|
|
-keep-property-name responseData
|
|
|
|
# Keep global names
|
|
-keep-global-name AppConfig
|
|
|
|
# Keep file names
|
|
-keep-file-name MainPage
|
|
-keep-file-name LoginPage
|
|
```
|
|
|
|
## Configuration Files
|
|
|
|
| Config File | Purpose | Editable | Scope |
|
|
|-------------|---------|:--------:|-------|
|
|
| `obfuscation-rules.txt` | Obfuscation rules applied when building this module | ✓ | Current module |
|
|
| `consumer-rules.txt` | Obfuscation rules applied when this module is used as a dependency (recommended: keep rules only) | ✓ | Modules depending on this module |
|
|
| `obfuscation.txt` | HAR/HSP build artifact, auto-generated | ✗ | Dependent modules |
|
|
|
|
## Common Obfuscation Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `-enable-property-obfuscation` | Obfuscate object property names |
|
|
| `-enable-toplevel-obfuscation` | Obfuscate top-level scope variable and function names |
|
|
| `-enable-filename-obfuscation` | Obfuscate file names |
|
|
| `-enable-export-obfuscation` | Obfuscate import/export names |
|
|
| `-disable-obfuscation` | Temporarily disable obfuscation (for debugging) |
|
|
|
|
## Whitelist Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `-keep-property-name <name>` | Preserve specified property name from obfuscation |
|
|
| `-keep-global-name <name>` | Preserve specified global name from obfuscation |
|
|
| `-keep-file-name <name>` | Preserve specified file name from obfuscation |
|
|
|
|
## Troubleshooting
|
|
|
|
### Diagnostic Steps
|
|
|
|
1. **Confirm obfuscation is the cause**: Temporarily add `-disable-obfuscation` and check if the issue disappears
|
|
2. **Locate the problematic field**: Identify the obfuscated field from crash logs
|
|
3. **Add to whitelist**: Add the problematic field to the `-keep-property-name` whitelist
|
|
|
|
### Common Scenarios Requiring Whitelisting
|
|
|
|
- **Network requests**: Request parameter field names, response data field names
|
|
- **Database operations**: Table field names
|
|
- **System APIs**: System callback parameters
|
|
- **Third-party library interfaces**: Field names required by third-party libraries
|
|
|
|
### Example: Preserving Network Request Fields
|
|
|
|
```text
|
|
# API request/response fields
|
|
-keep-property-name code
|
|
-keep-property-name message
|
|
-keep-property-name data
|
|
-keep-property-name token
|
|
-keep-property-name userId
|
|
```
|
|
|
|
## Verifying Obfuscation Results
|
|
|
|
1. Switch to **Release** mode and build
|
|
2. Inspect the build artifacts
|
|
3. Use decompilation tools to verify that class/method/property names are obfuscated
|
|
4. Test that the application functions correctly
|
|
|
|
## References
|
|
|
|
- [Huawei Official Documentation - ArkGuard](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-arkguard)
|