Introduction: Understanding ‘Bad Signature’ Errors in Android Kernel Modules

When developing or customizing Android devices, working with custom kernel modules is often a critical step for adding new hardware support, optimizing performance, or implementing specialized functionalities. However, developers frequently encounter the frustrating ‘Bad Signature’ error when attempting to load these modules using insmod. This error is not merely a compilation oversight; it’s a fundamental security mechanism, deeply rooted in the Linux kernel’s module signing infrastructure, especially prevalent in modern secure boot environments like those found on Android devices.

This guide will demystify the ‘Bad Signature’ error, explaining why it occurs, and provide a comprehensive, expert-level walkthrough on how to properly sign your custom kernel modules and configure your Android kernel to trust them. We’ll cover everything from generating cryptographic keys to modifying kernel configurations, ensuring your modules load seamlessly and securely.

The Core Concept: Kernel Module Signing and Secure Boot

At its heart, kernel module signing is a security feature designed to ensure the integrity and authenticity of code loaded into the kernel. The goal is to prevent malicious or untrusted code from gaining kernel-level privileges, which could compromise the entire system. When a kernel is configured for module signing, it will only load modules that have been cryptographically signed with a trusted key.

In Android’s context, this often integrates with Secure Boot mechanisms. Secure Boot, typically implemented at the UEFI/bootloader level, ensures that only authenticated and signed software components (bootloader, kernel, system image) are loaded. Kernel module signing extends this trust chain into the runtime, verifying modules loaded post-boot.

Why You Encounter ‘Bad Signature’

A ‘Bad Signature’ error typically means one of the following:

• The kernel module you’re trying to load is not signed at all.
• The module is signed, but with a key that the running kernel does not trust.
• The kernel is configured to enforce module signing (CONFIG_MODULE_SIG_FORCE=y), and the signature check failed.
• The module has been tampered with after signing, invalidating its signature.
• There’s an ABI mismatch, and the kernel mistakenly reports a signature issue instead of an ABI incompatibility (less common, but possible).

Prerequisites for Signing Custom Modules

Before diving into the signing process, ensure you have the following:

• The exact kernel source code that matches the kernel running on your target Android device. This is crucial for ABI compatibility and correct build configurations.
• A compatible cross-compilation toolchain (e.g., AOSP prebuilts, Linaro GCC/Clang) for your device’s architecture (ARM, ARM64).
• OpenSSL installed on your build machine for generating cryptographic keys.
• Basic understanding of Makefiles and kernel compilation.

Step-by-Step Resolution: Signing and Trusting Your Modules

Step 1: Verify Kernel Module Signing Configuration

First, determine how your target kernel is configured regarding module signing. You can often find this information in /proc/config.gz on the running device, or in the .config file within your kernel source.

# On your Android device (as root) or extracted from a firmware image: gzip -dc /proc/config.gz | grep CONFIG_MODULE_SIG

Look for these key configurations:

• CONFIG_MODULE_SIG=y: Indicates that module signing is enabled in the kernel.
• CONFIG_MODULE_SIG_FORCE=y: Indicates that the kernel will *always* reject unsigned modules. If this is ‘y’, you absolutely must sign your modules and ensure the kernel trusts your key.
• CONFIG_MODULE_SIG_ALL=y: All modules built with this kernel will be automatically signed.
• CONFIG_SYSTEM_TRUSTED_KEYS="": Specifies the path to a certificate bundle containing trusted keys. This is where we’ll inject our own key.

If CONFIG_MODULE_SIG=n, module signing is disabled, and ‘Bad Signature’ errors are likely due to something else (e.g., ABI mismatch, corrupted module). However, in modern Android kernels, it’s almost always enabled.

Step 2: Generate Cryptographic Keys

You’ll need a private key to sign your modules and a public certificate to allow the kernel to verify them. Generate these on your build machine:

# Generate a 2048-bit RSA private key openssl genrsa -out module_signing_key.pem 2048 # Generate a self-signed X.509 certificate from the private key openssl req -new -x509 -nodes -sha256 -days 3650 -key module_signing_key.pem -out module_signing_cert.der -outform DER -subj "/CN=Android Kernel Module Signing"

Keep module_signing_key.pem secure and private. The module_signing_cert.der file is your public certificate that the kernel needs to trust.

Step 3: Integrate Your Public Key into the Kernel Source

For your kernel to trust modules signed with your key, your public certificate must be built into the kernel’s trusted keyring. This involves placing your .der file into the kernel source and updating the build configuration.

1. Copy your public certificate into the kernel’s certs/ directory:

cp module_signing_cert.der <your_kernel_source>/certs/

2. Modify the kernel’s .config to point to your certificate. Ensure CONFIG_SYSTEM_TRUSTED_KEYS includes your certificate. You can edit the .config directly or use make menuconfig:

# Inside <your_kernel_source> make menuconfig # Navigate to "Cryptographic API" -> "Certificates for signature checking" # Ensure "Additional X.509 certificates for module signature verification" is enabled. # And the path points to your certificate: # e.g., CONFIG_SYSTEM_TRUSTED_KEYS="certs/module_signing_cert.der"

If you don’t use make menuconfig, manually add or modify the line in .config:

CONFIG_SYSTEM_TRUSTED_KEYS="certs/module_signing_cert.der"

Step 4: Recompile the Kernel with Your Trusted Key

With your certificate integrated, you must now recompile the entire kernel. This will embed your public key into the kernel image, allowing it to verify modules signed by your corresponding private key.

# Navigate to your kernel source directory cd <your_kernel_source> # Clean the build directory make clean # Recompile the kernel and modules. # Replace ARCH and CROSS_COMPILE with your specific values. make ARCH=arm64 CROSS_COMPILE=aarch64-linux-android- O=../out # For specific modules or entire tree make ARCH=arm64 CROSS_COMPILE=aarch64-linux-android- O=../out modules

After recompiling, ensure you have the new vmlinuz (or `Image`), `dtb`, and module (`.ko`) files ready for flashing or deployment.

Step 5: Compile and Sign Your Custom Kernel Module

Now, compile your custom module, ensuring it’s signed during the build process. You can instruct the kernel’s build system to use your private key for signing.

A typical Makefile for an out-of-tree module:

# Assuming your kernel source is in ../kernel KDIR := ../kernel PWD := $(shell pwd) obj-m := your_module.o all: $(MAKE) -C $(KDIR) M=$(PWD) modules sign: all $(MAKE) -C $(KDIR) M=$(PWD) modules  MODSECKEY=$(PWD)/module_signing_key.pem \ MODSECCERT=$(PWD)/module_signing_cert.der clean: rm -rf *.o *~ core .depend .*.cmd *.ko *.mod.c .tmp_versions Module.symvers modules.order

To build and sign your module, navigate to your module’s directory and run:

# Make sure module_signing_key.pem and module_signing_cert.der are in the current directory. make sign

This command tells the kernel’s build system to use your generated private key (MODSECKEY) and corresponding certificate (MODSECCERT) to sign the module as part of the compilation process. The resulting your_module.ko file will now contain the cryptographic signature.

Step 6: Deploy and Load the Signed Module

Finally, deploy the recompiled kernel (if necessary) and your signed module to your Android device.

1. Flash the new kernel (`vmlinuz`/`Image` and `dtb`) to your device’s boot partition using tools like `fastboot`.

# Example fastboot flash boot <path_to_new_boot.img>

2. Push your signed your_module.ko to the device:

adb push your_module.ko /data/local/tmp/

3. On the device, attempt to load the module:

# As root su insmod /data/local/tmp/your_module.ko

4. Check kernel messages for success or any remaining issues:

dmesg | grep your_module

If successful, you should no longer see ‘Bad Signature’ errors. You might see messages related to the module loading, or simply no error output from insmod.

Advanced Considerations

• ABI Compatibility: Even with correct signing, ABI (Application Binary Interface) mismatches can prevent modules from loading. Always ensure your module is built against the *exact* kernel headers of the target kernel. Tools like modinfo or depmod -e can sometimes help diagnose ABI issues.
• OEM-Specific Requirements: Some Android OEMs might implement additional layers of module verification or restrict kernel modifications. In such cases, you might need specific OEM-provided keys or firmware signing processes, which are typically outside the scope of general custom module development.
• Security Best Practices: Treat your private signing key (module_signing_key.pem) with utmost care. Compromise of this key allows anyone to sign modules that your kernel will trust, undermining system security.

Conclusion

Resolving ‘Bad Signature’ errors when loading custom Android kernel modules is a journey into the Linux kernel’s security architecture. By understanding the role of module signing, generating your own cryptographic keys, embedding your public key into the kernel, and correctly signing your modules, you gain the ability to extend your Android system’s capabilities while maintaining its integrity. This comprehensive approach ensures that your custom kernel modules are not only functional but also securely integrated into modern Android environments.