Preparing Your Project

Areas to protect are selected by symbol name (i.e., native function/method names). Therefore, it is important that Jigsaw has access to the debug symbols to discover all code included in the binary files. See below for operating system specifics on how to accomplish this.

Android Preparations

To ensure that the native debug symbols are created, add the following line to your app’s build.gradle file:

android.buildTypes.release.ndk.debugSymbolLevel = { SYMBOL_TABLE }

If your project builds an Android App Bundle (i.e., an .aab), there is nothing more you need to do. Jigsaw will find the debug symbol files automatically.

If your project builds an Android Package Kit (APK), you must add the --native-debug-symbols option when running the Shielding Tool command line. For example:

java -jar Shielder.jar myApp.apk --rules rules.cfg --native-debug-symbols path/to/native-debug-symbols.zip

Also note that Android binaries must include an auxiliary program header (PT_NOTE) or a GNU stack marker (PT_GNU_STACK) to be processed by Jigsaw.

iOS Preparations

For iOS libraries, Jigsaw uses the app’s debug symbol (dSYM) file to discern the symbol names. Xcode projects produce a dSYM file by default, but to verify that your project is set up correctly, use the following steps:

1. Navigate to the Build Settings tab for your selected target. Make sure the viewing option is set to All and not Basic.

2. In the Filter field in the top-right corner, search for debug information format.

3. Ensure that the Release option under Debug Information Format is set to DWARF with dSYM File.

The process looks like the following image:

If you run the Shielding Tool command line on the same machine that built the Xcode project, there is nothing more you need to do. Jigsaw will find the debug symbol files automatically.

If you want to run protections on a different machine, you must add the --native-debug-symbols option when running the Shielding Tool command line. For example:

java -jar Shielder.jar myApp.ipa --rules rules.cfg --native-debug-symbols path/to/native-debug-symbols/

The --native-debug-symbols path can either be a directory or a .dSYM file.

Moving Binary Sections

As mentioned in Section Encryption, Jigsaw encrypts code and data, including all C-style strings, making it much harder to infer meaning in the code. By default, Xcode places this data in the __TEXT section of the binary, a section that cannot be encrypted on iOS. However, by using a linker flag, you can tell Xcode to move the __cstring section inside the __DATA section, where it can be encrypted.

To make this change in Xcode, use the following steps:

1. Navigate to the Build Settings tab for your selected target.

2. In the Filter field in the top-right corner, search for "linker flag".

3. Set the value of "Other Linker Flags" to the following:

   -Wl,-rename_section,__TEXT,__cstring,__DATA,__cstring

The process looks like the following image:

On some apps running iOS 12 or earlier, there is a small chance that encrypting the __DATA, __cstring section will cause the app to terminate unexpectedly. In the unlikely event that this happens, simply remove the linker flag in your build settings.