[0x0 Unpacking JNI Binaries]: Introduction, reverse engineering JNI_OnLoad + RegisterNatives

TL;DR

1. JNI Binaries are a foreign function calling interface in Android, bridges in C/C++ code.
2. JNI Binaries host their own function resolution in the JNI_OnLoad + RegisterNatives call chain.
3. Malware has been known to override this call chain to obfuscate code.

Introduction to Java Native Interface (JNI) on Android

Java Native Interface (JNI) is the crucial framework that enables Java code in the Android Virtual Machine to interact with applications and libraries written in C/C++. Introduced with Java 1.1, JNI was adopted by Android to access the underlying Linux kernel and system C/C++ libraries, and to allow developers to integrate custom native code. JNI is essentially a borrowed foreign function interface for Java that was adoped by the Android folks and it allows for (i)  Code Reusability: Integrate existing, mature C/C++ libraries (e.g., for cryptography, physics engines, or image processing), famously the Unity Engine, VR applications, banking apps that makes use of crypto will typically embed some JNI libraries.  And the developers don’t need to go through much headache porting this to android beyond just making the compiler work. (ii) Performance Optimization: Achieve significant speed gains in computationally intensive tasks by bypassing the overhead of the Java Garbage Collector (GC) and the AVM. (iii) Precise Memory Management: Gain explicit control over memory allocation and deallocation, crucial for low-latency or resource-constrained applications. (iv)  Access to Low-Level System Features: Directly interact with platform-specific hardware or system calls not exposed via standard Java APIs. (v) Obfuscation and Protection: Moving sensitive logic to native binaries can make it marginally more challenging for casual reverse engineers to analyze compared to pure Java bytecode –more on this later.

How Calls to JNI Binary Functions are Made (Static vs. Dynamic Registration)

The process of bridging Java and native code involves loading the library and resolving the method addresses and calling a few initialisation and de-init functions. There are two primary methods for resolving native functions: static registration (relying on naming conventions) this uses the implicit mechanisms in the JNI runtime to figure out how to run your natively defined code and dynamic registration (using JNI_OnLoad) which requires you to explicitly define what happens once your library touches the process memory space.

JNI_OnLoad is called by the runtime if defined in the binary, and because it may present a profound modification of execution flow and environment we must unpack how it works and take a look at some common examples collected from the wild so you know what to expect. The next few sections handle that.

Static Registration (The Default Process)

In this section we will look at the steps required in order to setup your own JNI_OnLoad call and we’re doing it with some reference code included in the android jni repo. First lets look at the code flow in a native lib when a JNI_OnLoad call is not defined.

(i) Declare a Java Native Method: You declare a method with the native keyword in Java. This is not the JNI_OnLoad call just yet, its our code the stuff you want to actually run in C/C++ land. The code snippet below we define an example method called “getNativeString()” which has a string return type. As you can see in the code it needs to be tagged with the “native” keyword in order for the JVM to understand that the JNI runtime must take over when its gotta figure out where this code is.

public class MyNativeClass{
    public native String getNativeString();
    // Statically load the native library
    static {
        System.loadLibrary("mynativelib");// Resolves to libmynativelib.so } }

(ii) Define a Corresponding Method in C/C++ (by Name): The native function must adhere to the strict JNI naming convention: Java_<package_name>_<class_name>_<method_name>. If you’re using Android Studio most of this is done for you when you select the JNI presets for your project. And for the most part when you’re unpacking android packages from the wild, you’ll see a similar naming convention, this should tip you off that you’re most probably dealing with an SDK built app – the dev wanted to rely on the common resolution mechanism. Here’s what a typical method looks like:

extern "C" JNIEXPORT jstring JNICALL
Java_com_example_mynativeapp_MyNativeClass_getNativeString(
        JNIEnv* env,
        jobject /* this */){
    // ... implementation ...
}

(iii) Load the Native Library & Resolution: When System.loadLibrary("mynativelib") is called the runtime ads a little resolution step to figure out which canonical path to use and how to add on the right file extension. Alternative to this you could use System.load("mynativelib.so") which requires the dev to use a more explicit name including the file extension. The difference in convenience is slight, loadLibrary allows you to use platform agnostic naming. These two calls make use of dlopen to inject the library into the processes executable memory space (whatever memory is preconfigured for this according to the load commands in the ELF definition, memory space permissions enforced by the OS etc).

At this point we have our code injected, and once loaded into memory the runtime will handle calling your string method defined above. With the standard process out of the way, we need to walk through the JNI_OnLoad process, which may or may not trigger depending on whether your binary defines one. The following sections walk through JNI_Onload and how its related to RegisterNatives, after that we will look at some disassembly help figure out how to identify this in simple and perhaps more semantics devoid environments like obfuscated and stripped binaries.

Dynamic Registration using JNI_OnLoad (The Alternative Process)

When a native library exports a function named JNI_OnLoad, the entire resolution process changes significantly.  JNI_OnLoad is called before your actual code and it receives a pointer to the JVM instance (different to the JNIEnv pointer that normal JNI methods receive!).  Typically this is a point in the lifecycle that allows you to prepare pointers, data structures and classes the wider library might need so basic “init” type stuff. For instance for a video rendering library it might help to load up any textures that you would want here, maybe download images that might be needed or start up the threads that would do that. 

This function has a fixed signature and is automatically called by the ART/JVM (an example i used that worked was from the test samples from test/004-JniTest/jni_test.cc), lets take a look at the sample before i blab about it out of context:

// --- JNI_OnLoad Implementation ---
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
    printf("--- JNI_OnLoad Test Function Calls ---\n");
    g_JavaVM = vm;
    JNIEnv* env = NULL;
    jint result;

    result = vm->GetEnv((void**)&env, JNI_VERSION_1_6);
    print_result("GetEnv (JNI_VERSION_1_6)", result);

    if (result != JNI_OK || env == NULL) {
        return JNI_ERR;
    }

    // Verbose runtime checks
    printf("  -> **SKIPPING** DestroyJavaVM: Calling this would terminate the JVM.\n");
    result = vm->AttachCurrentThread(&env, NULL);
    print_result("AttachCurrentThread (Redundant)", result);
    result = vm->GetEnv((void**)&env, (jint)9999);
    print_result("GetEnv (JNI_VERSION_9999)", result);

    // Dynamic Registration for callmenative_fromonload
    jclass clazz = env->FindClass("com/kmsec/nativellibsec/MainActivity");
    if (clazz == NULL) return JNI_ERR;

    // Cache a global reference to demonstrate cleanup later in OnUnload
    g_cachedClass = (jclass)env->NewGlobalRef(clazz);

    JNINativeMethod methods[] = {
            {(char*)"callmenative_fromonload", (char*)"()V", (void*)native_logic_for_onload}
    };

    if (env->RegisterNatives(clazz, methods, 1) < 0) { <--- make sure the JVM knows about our methods
        printf("RegisterNatives failed.\n");
        return JNI_ERR;
    }

    printf("--- JNI_OnLoad Test & Registration Complete ---\n");
    return JNI_VERSION_1_6;
}

The example in the test code above is great because it shows some common patterns and things you would expect in a typical, sane non-malicious JNI_Onload call. Namely stuff like (i) grabbing a copy of the JNIEnv pointer, so it can make the (ii) RegisterNatives call which setups up the resolution of native to java methods. Another important thing to note is that the JNI_Onload function receives a pointer to the JavaVM struct, (as I’ve mentioned before, its very very hard to find a break down of how this looks in reverse engineering and there’s no reference material available for what offset means what – but you’re in luck we will dig into this before the end of the post!).

Here’s a code snippet of the JavaVM pointer definition i found, just to make sure i know what im  talking about (this is from the oracle docs btw) :

...
01905 
01906 struct JavaVM_ {
01907     const struct JNIInvokeInterface_ *functions;
01908 #ifdef __cplusplus
01909 
01910     jint DestroyJavaVM() {
01911         return functions->DestroyJavaVM(this);
01912     }
01913     jint AttachCurrentThread(void **penv, void *args) {
01914         return functions->AttachCurrentThread(this, penv, args);
01915     }
01916     jint DetachCurrentThread() {
01917         return functions->DetachCurrentThread(this);
01918     }
01919 
01920     jint GetEnv(void **penv, jint version) {
01921         return functions->GetEnv(this, penv, version);
01922     }
01923     jint AttachCurrentThreadAsDaemon(void **penv, void *args) {
01924         return functions->AttachCurrentThreadAsDaemon(this, penv, args);
01925     }
01926 #endif
01927 };

So basically it wraps whats called a JNIInvokeInterface (might be more interesting uses of this), and it populates with some methods that look like they’re pretty useful for handling VM threads and controlling the VM instance. We’re gonna need this info a bit later so lets make a listing of the JavaVM methods, in full:

So we have a hand full of functions here (post edit note: I’ve linked the Oracle definition here, which is technically not correct, but i checked and the APIs are similarly defined here) , a really common one you’ll encounter, usually early in the JNI_OnLoad is GetEnv, because it provides a copy of the JNIEnv pointer which can allow you to instantiate classes and do a bunch of useful stuff we will talk about in a coming post. Okay so we get JNI_OnLoad we get what its arguments are and we even have a working example to try out. So What happens after the JNI_OnLoad?  Well then its the user defined function which will get executed potentially, and when thats done there is a de-initialisation call which is fired call JNI_OnUnLoad which is called. This function is not so commonly defined but may still appear, here’s a working example of one:

// --- JNI_OnUnload Implementation ---
/**
 * Note on Disassembly: The argument list for OnUnload is identical to OnLoad (JavaVM*, void*).
 * To differentiate them in a dump, look for specific function calls like DeleteGlobalRef
 * or resource releasing logic rather than FindClass or RegisterNatives.
 */
JNIEXPORT void JNICALL JNI_OnUnload(JavaVM* vm, void* reserved) {
    JNIEnv* env;
    printf("\n--- JNI_OnUnload Called ---\n");

    if (vm->GetEnv((void**)&env, JNI_VERSION_1_6) != JNI_OK) {
        // Even if GetEnv fails, we proceed with manual cleanup where possible
        g_JavaVM = NULL;
        return;
    }

    // (i) Global reference management
    // If you want to avoid leaking memory, you must destroy global references here.
    if (g_cachedClass != NULL) {
        env->DeleteGlobalRef(g_cachedClass);
        g_cachedClass = NULL;
        printf("  -> Global reference g_cachedClass destroyed.\n");
    }

    printf("Native library unloaded and JNI_OnUnload executed successfully.\n");

    g_JavaVM = NULL;
}

We also see an interesting pattern (pointer offset + branch with link) that will become increasingly common, to harken back to what we covered earlier what you are seeing here the pattern of taking a pointer probably passed as an argument (offset 0x00c1cec register x20 takes in something pointing to the stack. This is our magic JNI environment structs and objects that get populated in by the JNI runtime.

References and Reading

1. https://www.usenix.org/system/files/usenixsecurity25-di-bartolomeo.pdf
2. https://s3.eurecom.fr/docs/tops25_ruggia.pdf
3. https://github.com/maddiestone/AndroidAppRE/blob/master/reversing_native_libs.md
4. https://www.virusbulletin.com/virusbulletin/2019/01/vb2018-paper-unpacking-packed-unpacker-reversing-android-anti-analysis-native-library/