Skip to main content

Shield Package Selection & Configuration Guide

This document provides structured guidance on module-wise Shield integration, outlines decision criteria for package inclusion and exclusion, explains platform-specific encryption behaviour and covers key performance and stability considerations to ensure secure and reliable application protection.

1. Introduction​

Bugsmirror Shield is a build-time application protection solution designed to safeguard mobile applications against reverse engineering, static patching, and unauthorized binary modification.

Shield operates as a static-time transformation layer that encrypts protected code during the build process and performs controlled runtime decryption inside a secured execution environment. This design enables strong protection while preserving application stability and runtime performance.

Note:
Please make sure that you are always using the latest version of MASST CLI from the portal for the shield integration.

2. Native Android Integration​

Native Android applications require explicit package configuration. Shield does not automatically encrypt Android application logic. Developers must carefully determine which packages to include and which to exclude.

2.1 Encryption Scope Behavior​

Shield applies encryption at the package namespace level.

When a parent package is selected for protection, all nested subpackages and child namespaces are automatically included.

Example​

If the following namespace is included:

com.company.app.security

Shield automatically protects:

com.company.app.security.crypto  
com.company.app.security.validation  
com.company.app.security.network

Key Points to Remember​

  • Including a high-level namespace increases the protection surface
  • Fine-grained module-level inclusion improves stability and maintainability

2.2 R8 and ProGuard Compatibility Considerations​

Shield operates on compiled binary output. Applying aggressive bytecode obfuscation on the same packages can introduce conflicts.

Note: Do not apply Shield encryption to packages already processed by aggressive R8 or ProGuard rules

Combining shield encryption and heavy obfuscation on the same code can cause:

  • Runtime decryption complexity
  • Difficult crash diagnostics
  • Mapping file mismatches
  • Increased risk of runtime instability

2.3 Exclusion Scope Relationship​

Exclusion rules are only applicable when encryption inclusion rules are defined.

Note: Excluded packages must always fall within an included namespace.

Example​

If you include:

com.company.app

You may exclude:

com.company.app.startup  
com.company.app.initializer

However, excluding packages outside the included scope has no effect.

It is strongly recommended to selectively encrypt only those packages that require protection rather than applying encryption across the entire application. Over-encryption can increase application size, impact runtime performance, and complicate debugging. A targeted approach ensures maximum protection where it matters most while maintaining overall efficiency.

  • Include packages that contain core business rules, proprietary algorithms, or critical decision-making logic that differentiates your application.

  • Include packages that handle API keys, encryption keys, authentication tokens, or any form of sensitive credentials.

Note: To minimize runtime overhead, avoid including packages for tasks like UI rendering, logging, and analytics unless they are absolutely essential.

3. Native iOS Integration​

Native iOS applications do not require manual package selection for Shield encryption. Shield is integrated through the Defender iOS workflow and applies binary-level protection during post-build processing.

To enable Shield encryption, a one-time linker configuration is required to allow secure relocation and protection of constant string sections.

3.1 Required Linker Configuration​

Shield requires relocation of the constant string section (__cstring) so it can be encrypted and protected during the build process.

Configuration Steps​

  1. Open your Xcode project.
  2. Navigate to:
Build Settings → Linking → Other Linker Flags → Release
  1. Add the following linker flag:
-Wl,-rename_section,__TEXT,__cstring,__DATA,__cstring

This configuration enables Shield to relocate and encrypt string literals securely.

3.2 Build and Archive Process​

After applying the linker configuration:

  1. Select Product → Archive in Xcode.
  2. Generate the .xcarchive build artifact.
  3. Provide the archive to the Defender iOS Integrator Tool or Bugsmirror integration workflow for Shield processing.

Shield automatically applies encryption and binary hardening during post-build integration.

4. Flutter Applications​

Flutter applications combine Dart-compiled business logic with native platform integration layers. Shield provides automatic protection for Flutter runtime artifacts.

Note:
Ensure that required Flutter embedding classes are not removed or obfuscated, as this may impact Shield integration. Keep the following rule in your ProGuard/R8 configuration file to ensure proper functionality:

-keep class io.flutter.embedding.** { *; }

This ensures that essential Flutter embedding components remain intact during the build and Shield processing.

4.1 Automatic Flutter Encryption Behavior​

Shield automatically encrypts:

  • Compiled Dart application logic
  • Flutter framework execution components
  • Flutter build-generated artifacts

No manual configuration is required for Dart packages or Flutter framework code.

Note: If the majority of your application logic resides in the native platform layers and you only intend to protect that portion, you may choose to use Native Android and/or Native iOS Shield integration exclusively instead of Flutter Shield. This approach allows you to encrypt only the native code while leaving the Flutter (Dart) layer unchanged. Please refer to Native Android Integration or Native iOS Integration, respectively.

4.2 Native Platform Code Considerations​

Flutter projects contain native platform directories:

android/  
ios/

Custom code added inside these directories is treated as standard native application logic.

Important Guidance​

If you want to apply protection to both the Flutter (Dart) layer and the native platform code, you should opt for Flutter Shield integration. This ensures that both the Dart application logic and the underlying native modules are encrypted as part of a unified protection workflow.

To properly manage and configure encryption for the native components:

5. React Native Applications​

React Native applications use JavaScript execution combined with native bridge modules.

Shield automatically protects JavaScript runtime assets.

Disclaimer: If your application uses CodePush for over-the-air updates, React Native Shield integration is not supported. In such cases, it is recommended to opt for Native Android Shield integration only and apply protection to the required Android packages. This ensures compatibility while still securing the native layer of your application. Please refer to Native Android Integration

5.1 Automatic React Native Encryption Behavior​

Shield automatically encrypts:

  • React Native JavaScript bundles
  • Framework execution logic
  • Packaged application business logic

No manual configuration is required for JavaScript assets.

Note: If the majority of your application logic resides in the native platform layers and you only intend to protect that portion, you may choose to use Native Android and/or Native iOS Shield integration exclusively instead of React Native Shield. This ensures that only the native code is encrypted while the React Native (JavaScript) layer remains unaffected. Please refer to Native Android Integration or Native iOS Integration respectively.

5.2 Native Module Handling​

React Native projects contain native platform directories:

android/  
ios/

Custom native modules created for React Native are treated as standard native code.

Important Guidance​

If you want to apply protection to both the React Native (JavaScript) layer and the native platform code, you should opt for React Native Shield integration. This ensures that both the JavaScript bundle and the underlying native modules are encrypted as part of a unified protection workflow.

To properly manage and configure encryption for the native components:

Last updated on