Sign APK files with ApkSigner using PKCS#11 library

You’re probably wondering why we would sign an APK, right? A digital signature is a method for demonstrating the authenticity of a digital file, such as a document, executable file, or, in this case, an APK, which is just a collection of files. We can practically guarantee that whoever uses an APK will receive a verifiable copy of the file they anticipated by signing the APK. Since no one else can alter this file while keeping the same signature, there are clear security benefits.

Now, to achieve this, we are integrating PKCS#11 libraries, which enables us to use enhanced security by storing keys on Hardware Security Modules (HSMs) or some kind of Key Vault. This article is going to walk you through the process of using APKSigner with our (Encryption Consulting’s) PKCS#11 Wrapper on Ubuntu and MacOS for your APK signing operations.

Overview of PKCS#11 Integration

When it comes to APK signing operations, PKCS#11 APIs play a very important role. PKCS#11 is a very famous and widely adopted standard API that enables software to interact very smoothly with HSMs. Integrating PKCS#11 into APKSigner will allow you or your developers to sign Android APKs while ensuring that the private keys never leave a secure environment (HSMs). Your keys are protected from possible online threats in this way.

The PKCS#11 Wrapper from Encryption Consulting will give you an extra degree of dependability and trust. We guarantee outstanding performance, seamless integration, and—above all—client-side hashing. With the help of our PKCS#11 Wrapper, you can:

Protection against Key Leakage: Your organization’s private keys never leave the HSM. All of the cryptographic operations are performed directly within the HSM.
Hardware-Backed Security: All of your signing operations are going to be conducted in tamper-resistant hardware, which will ensure both physical and logical security. However, you have to comply with the CA/B Forum’s June 2023 guideline and have a FIPS 140-2 Level 2 HSM on your side.
Enhanced Trust for your Applications: Your signed APKs will fulfill Android’s security requirements and ensure that the end-user has confidence in your application’s integrity.
High-Performance Signing with Client-Side Hashing: Our PKCS#11 Wrapper supports client-side hashing, ensuring that your APK’s integrity remains intact. This will also drastically improve the speed of the signing process, making it ideal for your organization’s high-throughput scenarios like CI/CD pipelines.

Configuration of PKCS#11 Wrapper on Windows

Installation on Client System

Step 1: Go to EC CodeSign Secure’s v3.01’s Signing Tools section and download the PKCS11 Wrapper for Windows.

Step 2: After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

Step 3: Go to your Windows client system and edit the configuration files (ec_pkcs11client.ini and pkcs11properties.cfg) downloaded in the PKCS11 Wrapper.

Prerequisites for Windows System

Now, let’s install some prerequisites in your client system to run the PKCS11 Wrapper.

Step 1: Install Java 22 from Oracle’s official site and follow the instructions in the msi file.

Step 2: Set Java 22 as the active version by storing the bin path in the PATH variable.

Step 3: Install the Android SDK command-line tools from this link here.

Step 4:

Extract the files into a “cmdline-tools” folder.

Create a subfolder named latest.

Move the bin and lib folders into the latest folder.

Step 5: Set an environment variable called ANDROID_HOME and set it to the path where you extracted the command line tools.

Step 6: Install Build tools using SDKManager, which contains the APKSigner: .\bin\sdkmanager –channel=0 –install “build-tools;34.0.0”

Step 7: Ensure that APKSigner is present: Apksigner.bat –version

Perform Signing and Verification using PKCS11 Wrapper

Now that all the configurations and prerequisites have been installed. Let’s perform the signing operation first.

The signing command will look something like this (ensure you run this command only inside the folder where your PKCS11 Wrapper is installed):

apksigner sign –provider-class sun.security.pkcs11.SunPKCS11 –provider-arg  <path of the pkcs11properties.cfg file in your system> –ks NONE –ks-type PKCS11 –ks-pass pass:abcd1234 –ks-key-alias <private key alias> –in <path of the APK file you want to sign> –out <path of the Signed APK file>

For Example: apksigner sign –provider-class sun.security.pkcs11.SunPKCS11 –provider-arg C:\Users\riley\Downloads\PKCS11_Wrapper-Windows\pkcs11properties.cfg –ks NONE –ks-type PKCS11 –ks-pass pass:secretpassword –ks-key-alias gpg2 –in Sample.apk –out signed.apk

After successfully signing the APK, let’s verify it using this command:

apksigner verify -verbose <path of the signed APK file>

For example: apksigner verify -verbose signed.apk

Configuration of PKCS#11 Wrapper on Ubuntu

Prerequisites

Here are the prerequisites for using our PKCS#11 Wrapper in your system. Before starting, ensure the following are ready (you can refer to the CONFIGURING PKCS#11 WRAPPER section for the steps):

Ubuntu Version: Ubuntu version 22.04 or later (tested environment is Ubuntu 24.02)
Dependencies: Install liblog4cxx-dev, and curl.
JDK: Oracle/OpenJDK 8 or higher has to be installed and configured.

Installing EC’s PKCS#11 Wrapper

Step 1: Go to EC CodeSign Secure’s v3.01’s Signing Tools section and download the PKCS#11 Wrapper for Ubuntu.

Signing tools section in CodeSign Secure

Step 2: After that, generate a P12 Authentication certificate from the System Setup > User > Generate Authentication Certificate dropdown.

Step 3: Go to your Ubuntu client system and edit the configuration files (ec_PKCS#11client.ini and PKCS#11properties.cfg) downloaded in the PKCS#11 Wrapper.

Configuring PKCS#11 Wrapper

Now, let’s configure your client system to run the PKCS#11 Wrapper.

Step 1: Install Java 8: sudo apt install openjdk-8-jdk

Step 2: Set Java 8 as the active version: sudo update-alternatives –config java

Step 3: Install the Android SDK command-line tools: sudo apt install google-android-cmdline-tools-13.0-installer

Step 4: Ensure that the SDK Manager for Android Studio has been properly installed: sdkmanager –version

Step 5: Install Build tools using SDKManager, which contains the APKSigner: sdkmanager “build-tools;34.0.0”

Step 6: Ensure that APKSigner is present: apksigner –version

Step 7: Two packages are required to run the PKCS#11 Wrapper on your system. First, install liblog4cxx-dev using: sudo apt-get install liblog4cxx-dev

Step 8: The last prerequisite is to install the curl package: sudo apt-get install curl

Signing and Verifying an APK

Now that all the configurations and prerequisites have been installed. Let’s perform the signing operation first.

The signing command will look something like this (ensure you run this command only inside the folder where your PKCS#11 Wrapper is installed):

apksigner sign –provider-class sun.security.PKCS#11.SunPKCS#11 –provider-arg <path of the PKCS#11properties.cfg file in your system> –ks NONE –ks-type PKCS#11 –ks-pass pass:abcd1234 –ks-key-alias <private key alias> –in <path of the APK file you want to sign> –out <path of the Signed APK file>

For Example: apksigner sign –provider-class sun.security.PKCS#11.SunPKCS#11 –provider-arg /home/administrator/PKCS#11_Wrapper-Ubuntu/PKCS#11properties.cfg –ks NONE –ks-type PKCS#11 –ks-pass pass:abcd1234 –ks-key-alias gpg2 –in Sample.apk –out signed.apk

After successfully signing the APK, let’s verify it using this command:

apksigner verify -verbose <path of the signed APK file>

For example: apksigner verify -verbose signed.apk