Menu
Menu
inquire
DexProtector iOS documentation

Documentation

Android documentation
iOS menu

iOS

Configuring DexProtector

Introduction to configuring DexProtector

DexProtector works best when it is tailored to your app.

Configuration is by means of a single XML file, which can be edited directly or via the DexProtector Studio interface.

You can use the configuration file to control the DexProtector process according to your needs. The configuration file allows you to specify the details of:

  • Build and logging settings for the DexProtector process
  • Signing methods
  • Protection mechanisms and filters for including/excluding code and resources for protection
  • Environment checks, for the detection of rooted devices; debuggers; emulators; and hooking tools
  • Network security options, including certificate monitoring for both Certificate Transparency and Public Key Pinning mechanisms
  • Integration with Licel's Threat Reporting and Attack Telemetry system, Alice

We recommend making use of all of the security features provided, as each element of protection adds more resilience against reverse engineering, tampering, and data theft.

Configuration file overview

DexProtector - Example XML Configuration File - iOS Applications

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>

<dexprotector>

    <!-- CODE PROTECTION -->

    <stringEncryption />

    <classEncryption />

    <ios mode="all">
        <!-- Include this tag to protect Frameworks within a package.
   If you intend to protect ONLY a framework, there is no need to include this tag; the other protection mechanisms will be applied to the input file. -->
        <!-- <frameworks mode="all">
		<filters>
           <filter><![CDATA[glob:Critical.framework/*]]></filter> 
		</filters>
     </frameworks> -->
        <!-- <cordova/> -->
        <!-- <reactNative/> -->
        <!-- <nativeScript/> -->
    </ios>    

    <!-- RESOURCE PROTECTION -->

    <resourceEncryption>
        <!--Make sure to specify filters to target sensitive resources, otherwise 
   DexProtector may encrypt files that should not be encrypted -->
        <assets>
            <filters>
                <filter>Example.json</filter>
            </filters>
        </assets>
    </resourceEncryption>
    
    <!-- RASP - ENVIRONMENT & RUNTIME CHECKS -->

    <antiDebug>true</antiDebug>
    <antiEmulator>true</antiEmulator>
    <antiManualInstall>false</antiManualInstall>
    <runtimeChecks>
        <paranoidMode>true</paranoidMode>
    </runtimeChecks>
    
    <!-- UI PROTECTION -->

    <uiProtection />       

    <!-- NETWORK SECURITY -->

    <certificateTransparency mode="on">
        <domain includeSubdomains="true">my.example.domain.com</domain>
        <actions>block</actions>
        <cacheTTL>180</cacheTTL>
        <sufficientSCTNumber>2</sufficientSCTNumber>
     </certificateTransparency>
    
    <!-- THREAT REPORTING AND TELEMETRY (ALICE) -->

    <!-- <reportMonitoring>
        <apiKey>ADD_YOUR_API_KEY</apiKey>
    </reportMonitoring> -->     
    
    <!-- SIGNING -->

    <signMode>release</signMode>
    <!-- The signing key corresponding to your chosen distribution method
certificate must be present in the build environment. Command to view 
certificates in local keychain: security find-identity -v -p codesigning). -->
    <!--<certificate>CERTIFICATE</certificate>-->

    <!-- PROTECTION ASSESSMENT & LOGGING -->

    <verbose>true</verbose>    

</dexprotector>

Configuration XML: Reference Information

xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<dexprotector>

<!-- BUILD SETTINGS -->

  <verbose>true</verbose>

<!-- SIGNING -->

  <signMode>release</signMode> 
  <certificate>no_default</certificate> 

<!-- iOS SETTINGS -->

  <ios mode="all">

	<mobileProvisionFile>no_default</mobileProvisionFile>

  <!-- <frameworks mode="all">
		<filters>
			<filter>no_default</filter> 
		</filters>
     </frameworks> -->

  <!-- <cordova/> -->
  <!-- <reactNative/> -->
  <!-- <nativeScript/> -->
	
  </ios>
  
<!-- CODE PROTECTION -->

  <stringEncryption/> 

  <classEncryption/>

<!-- RESOURCE PROTECTION -->

  <resourceEncryption>
        <assets>
            <filters>
               <filter>no_default</filter>
            </filters>
        </assets>
  </resourceEncryption>

<!-- RASP - RUNTIME & ENVIRONMENT CHECKS -->

  <runtimeChecks>
        <paranoidMode>true</paranoidMode>
  </runtimeChecks>

  <antiEmulator>true</antiEmulator>

  <antiDebug>true</antiDebug>
	
<!-- NETWORK SECURITY -->

  <publicKeyPinning src="no_default">
    <actions>block, report</actions>
    <network-security-config>
      <domain-config>
          <domain includeSubdomains="false">no_default</domain>
          <pin-set expiration="no_default">
	     <pin digest="no_default"></pin>
          </pin-set>
      </domain-config>
    </network-security-config>
  </publicKeyPinning>

  <certificateTransparency>
    <actions>block, report</actions>
    <domain includeSubdomains="false">no_default</domain>
    <!-- <logFile>no_default</logFile> -->
  </certificateTransparency>

<!-- UI PROTECTION -->

  <uiProtection/>

<!-- THREAT REPORTING AND TELEMETRY (ALICE) -->

  <reportMonitoring>
    <apiKey>no_default</apiKey>
  </reportMonitoring>

</dexprotector>
Build Settings Description and values

Verbose Logging

boolean

Element: verbose

Description: Enables/disables verbose logging for the DexProtector process.

Valid values: true; false. Default value: false

<verbose>false</verbose>
Signing Description and Values

Signing Certificate

string

Element: certificate

Description: Specifies the certificate (Distribution; Ad Hoc; Enterprise; or Development) to be used for code signing before testing and/or distribution. The signing key corresponding to your chosen distribution method must be present in the build environment. Command to view certificates in local keychain: security find-identity -v -p codesigning

<certificate>Apple Distribution: Licel Corporation (2N2DJJYKB2)</certificate>

Sign Mode and Distribution Method

string

Element: signMode

Description: Specify your signing mode. <signMode>release</signMode> is necessary for TestFlight and App Store uploads. For all other distribution methods, set <signMode>debug</signMode>

<signMode>release</signMode>
iOS Settings Description and Values

iOS

Mobile Provision File

Frameworks

Cordova

React Native

NativeScript

Element: ios

Description: Instructs DexProtector to process an xcarchive, IPA, or Framework, and enables the configuration of nested elements for iOS packages.

Format: contains nested elements (<mobileProvisionFile>, <frameworks>, <cordova>, <reactNative>, <nativeScript>)

Element (nested): mobileProvisionFile

Description: Optional element which allows you to specify the path to a .mobileprovision file with which DexProtector will overwrite the embedded.mobileprovision in the input application. Note: It is important to ensure that the signing certificate in the .mobileprovision file corresponds to the key used to sign the app. Any discrepancy will cause problems during distribution.

Format: string

Element (nested): frameworks

Description: Enable Frameworks protection to target Frameworks within an app, and specify them through the filters. For filters, the names of frameworks are specified using the root of the frameworks folder. For example, if you have an AppCore.framework in your app, the filter will be AppCore.framework/*, not including Frameworks or any other folder names.

Format: contains nested elements

     Element (nested): filter

     Format: string

     Default value: no default value

<frameworks mode="all">
   <filters>
      <filter><![CDATA[glob:Secret.framework/*]]></filter> 
   </filters>
</frameworks>

Element (nested): cordova

Description: Enables the protection of an iOS app developed with Cordova/Ionic. With this element enabled, DexProtector will encrypt all Cordova-related assets (such as .js files within the www/ folder) automatically.

Element (nested): reactNative

Description: Enables the protection of an iOS app developed with React Native. With this element enabled, DexProtector will encrypt all React Native-related assets (such as .js files within the www/ folder) automatically.

Element (nested): nativeScript

Description: Enables the protection of an iOS app developed with NativeScript. With this element enabled, DexProtector will encrypt all NativeScript-related assets automatically.

Code Protection Description and Values

String Encryption

Element: stringEncryption

Description: Enables DexProtector's String Encryption mechanism. There is no need to specify filters for stringEncryption for iOS packages. DexProtector will encrypt strings in the package by default.

Class Encryption

filters

Element: classEncryption

Description: With Class Encryption enabled, DexProtector encrypts Swift and Objective-C class metadata, including selectors, to ensure that the logic of the application is comprehensively hardened against reverse engineering. In most cases, it is best to encrypt all class metadata possible, so there is no need to set filters.

Element (nested): filters

Format: string

Default value: no default value

Resource Protection Description and Values

Resource Encryption

Element: resourceEncryption

Description: Resource encryption protects against malicious copying, modification, and piracy by encrypting an application's internal resources and assets (such as JSON files, databases, media files).

Element (nested): assets

Description: Encrypts resource files in the target package. Files can be targeted by file pattern (i.e. **.csv denotes all files of CSV file format), name pattern (i.e. File1** denotes all files whose names begin with the string "File1"), by specific file name (e.g. File2.json), or by path (e.g. TestDir/File3.txt).

Format: contains nested elements

     Element (nested): filters

     Format: string

     Default value: no default value

<resourceEncryption>
    <assets>
        <filters>
            <filter>**.csv</filter>
        </filters>
    </assets>
</resourceEncryption>
RASP (Runtime Application Self-Protection) - Environment & Runtime Checks Description and Values

Runtime Checks

Element: runtimeChecks

Description: DexProtector's RASP engine performs checks for rooted or Jailbroken devices and untrusted firmware. With paranoidMode set to true, if a device is compromised in this way, DexProtector will prevent the app from running.

Nested element: paranoidMode

Valid values: true; false

<runtimeChecks>
  <paranoidMode>true</paranoidMode>
</runtimeChecks>

Anti-Emulator Checks

Element: antiEmulator

Description: With this setting enabled, DexProtector will automatically implement checks on start-up and during runtime, crashing all application processes instantly if the app is launched on an emulator or simulator.

Valid values: true; false.

<antiEmulator>true</antiEmulator>

Anti-Debug Checks

Element: antiDebug

Description: With this setting enabled, DexProtector will automatically implement checks on start-up and during runtime, crashing all application processes instantly if a debugger attached at any point.

Valid values: true; false.

<antiDebug>true</antiDebug>
Network Security Description and Values

Public Key Pinning

Element: publicKeyPinning

Description: Settings for SSL/HTTP Public Key Pinning

Default value: no default value

Format: contains nested elements (<actions>, <reportUri>, <reportMethod>, <network-security-config>)

Element (nested): actions

Description: Specifies the actions to be performed if there are errors or anomalies detected during the Public Key Pinning checks

Format: list with the ',' separator

Available values: block - block the connection; report - send a report regarding the connection

Default value: block, report

<actions>block, report</actions>

Element (nested): reportUri

Description: Specifies the address that will be used to send JSON reports regarding any errors or anomalies detected during the Public Key Pinning checks

Format: string

Element (nested): reportMethod

Description: Specfies a method (in the format ClassName.methodName) to which JSON reports are passed in the event of any errors or anomalies detected during the Public Key Pinning checks. These methods should have public static modifier and (String jsonStr) signature.

Format: string

Element (nested): cacheTTL

Description: Time to live for a server SSL certificate chain check result for each domain

Format: int

Default value: 180

Element (nested): network-security-config

Description: Embedded Security Configuration

Examples of embedded security configuration settings:

<network-security-config>
            <domain-config>
                <domain includeSubdomains="true">example.com</domain>
                    <pin-set expiration="2023-01-01">
                    <pin digest="SHA-256">7HIpactkIAq2Y49orFOOQKurWxmmSFZhBCoQYcRhJ3Y=</pin>
                    <!-- backup pin -->
                    <pin digest="SHA-256">fwza0LRMXouZHRC8Ei+4PyuldPDcf3UKgO/04cDM1oE=</pin>
                    </pin-set>
            </domain-config>
</network-security-config>

Certificate Transparency

Element: certificateTransparency

Description: Settings for monitoring public key certificates according to the Certificate Transparency standard. DexProtector uses a list of log servers that is located in the distribution package. This list is based on: https://source.chromium.org/chromium/chromium/src/+/master:components/certificate_transparency/data/log_list.json Alternatively, a list of authorized log servers can be specified manually by entering a path to a file containing that list.

Format: contains nested elements (<trace>, <logFile>)

Element (nested): trace

Format: string

Description: For debugging purposes, set trace to 1000.

Default value: no default value

Element (nested): logFile

Format: string

Description: Path to file containing your own list of authorized log servers.

Default value: no default value

<certificateTransparency mode="on">
	<trace>0</trace>
        <domain includeSubdomains="true">no-sct.badssl.com</domain>
	<logFile>/path_to_log_list_file</logFile>
</certificateTransparency>
UI Protection Description and Values

UI Protection

Element: uiProtection

Description: DexProtector’s UI Protection for iOS blocks screen capture and enforces use of the system keyboard. Screen capture blocking hardens your app against screenshots, screen recording, and screen casting. Enforced use of the system keyboard ensures that the app is not exposed to unsafe input from custom keyboards.

Threat Reporting and Telemetry - Alice Integration Description and Values

Threat Reporting

Element: reportMonitoring

Description: Enables API for reporting to Licel’s Real-Time Attack Telemetry and Threat Intelligence service, Alice. For more information, see our guide to Alice.

Format: contains nested elements (<apiKey>, <customFieldsUpdate>, <trace>)

Element (nested): apiKey

Format: string

Default value: no default value

Element (nested): trace

Format: string

Description: The logging level of DexProtector messages on the end device. For debugging purposes, set to 1000. Otherwise, set to 0 or exclude the <trace> node.

Default value: no default value

xml
<reportMonitoring>
    <apiKey>137feb09-f390-4f00-b43f-ebccf530adf6lt</apiKey>
    <trace>0</trace>
</reportMonitoring>

Filters: A guide to targeting resources

Resource Encryption

Resource Encryption can be used to target assets files in the framework, IPA, or xcarchive. These files can be targeted by file pattern (i.e. *.png denotes all files of PNG file format), name pattern (i.e. File1* denotes all files whose names begin with the string "File1"), by specific file name (e.g. File2.json), or by path (e.g. TestDir/File3.csv). Here is an example configuration for Resource Encryption:

'
<resourceEncryption>
   <assets>
      <filters>
         <filter>glob:**.png</filter>
         <filter>glob:File1*</filter>
         <filter>glob:File2.json</filter>
         <filter>glob:TestDir/File3.csv</filter>
      </filters>
   </assets>
</resourceEncryption>

Configuring DexProtector for applications

'

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<dexprotector>

<!-- BUILD SETTINGS -->

   <verbose>true</verbose>

<!-- SIGNING -->

   <signMode<release</signMode>
   <certificate>Apple Distribution: Licel Corporation (2N2DJJYKB2)</certificate> 

<!-- iOS SETTINGS -->

   <ios mode="all">
	
      <mobileProvisionFile>/Users/developer/distribution.mobileprovision</mobileProvisionFile>
	
 <!-- Include this tag to protect frameworks within an IPA. If you intend to protect only a framework,
there is no need to include this tag; the other protection mechanisms will be applied to the input framework file. -->
      <frameworks mode="all">
         <filters> <!-- For filters, the names of frameworks are specified using the root of the frameworks folder
                               of an IPA. For example, if you have an AppCore.framework in your app, the filter will be
                               AppCore.framework/*, not including Frameworks or any other folder names. -->
            <filter><![CDATA[glob:Secret.framework/*]]></filter> 
         </filters>
      </frameworks>
	
  </ios>
  
<!-- CODE PROTECTION -->

   <stringEncryption/> 

   <classEncryption/>

<!-- RESOURCE PROTECTION -->
	
   <resourceEncryption>
      <assets>
         <filters>  <!-- Replace the placeholder with a pattern matching the assets files that you wish to encrypt, 
                            and add additional filters as required. -->
            <filter>glob:**example.csv</filter>
         </filters>
      </assets>
   </resourceEncryption>

<!-- RASP - RUNTIME & ENVIRONMENT CHECKS -->

   <runtimeChecks>
      <paranoidMode>true</paranoidMode>
   </runtimeChecks>

   <antiEmulator>true</antiEmulator>

   <antiDebug>true</antiDebug> 
	
<!-- UI Protection -->

   <uiProtection/>

<!-- NETWORK SECURITY -->

   <publicKeyPinning>
      <trace>9</trace>
      <actions>block</actions>
      <network-security-config>
         <domain-config>
            <domain includeSubdomains="true">openweathermap.org</domain>
                    <pin-set expiration="2025-10-19"> <!-- Please choose the expiration date carefully. We do not recommend 
setting a date far into the future. If you issue updates once a month, please set the expiration around 2 months from the 
current date. And do not forget to change the value with each new update. This could be crucial if your private key and 
certificate become compromised. -->
						<pin digest="SHA-256">axmGTWYycVN5oCjh3GJrxWVndLSZjypDO6evrHMwbXg=</pin>
						<!--
						The pin can be generated using the following command (check and replace 
                                                server name as required):
                      openssl s_client -connect onlinebanking.mobilebank.com:443 | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256
 
                      If you have a backup certificate, please use the following command to generate the pib:
                      cat <PATH_TO_CERTIFICATE> | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64       
						-->
						<!-- Backup PIN(s) -->
						<pin digest="SHA-256">NzgSaUD6ERUxuom+Xu1qVANzKf5rwE4QGlaDLc02YiY=</pin>
                    </pin-set>
         </domain-config>
      </network-security-config>
   </publicKeyPinning>

   <certificateTransparency mode="all">
      <actions>block</actions>
      <domain includeSubdomains="true">no-sct.badssl.com</domain>
 <!-- If no additional settings are specified, DexProtector will use a list of log servers that is located in the
 distribution package. However, should you need to use your own list of log servers, you can use the logFile node 
and specify a path to your list, as follows:
      <logFile>path_to_log_list_file</logFile> -->
   </certificateTransparency>

<!-- THREAT REPORTING AND TELEMETRY (ALICE) -->

  <reportMonitoring>
    <apiKey>137feb09-f390-4f00-b43f-ebccf530adf6lt</apiKey>
  </reportMonitoring>

</dexprotector>