Development of applications for the platform Android does not end when the last line of code is written. After compiling the project, you receive a file .apk, which is an archive with resources and code. However, before this file can be installed on the user's device or published in the store Google Play, it must be digitally signed.
This process is necessary to confirm authorship and ensure that the application has not been modified by attackers after assembly. The operating system verifies the digital signature with every installation and update. If you try to install a file without a signature or with an incorrect signature, the system will throw a package parsing error or deny access.
In this guide, we will go into detail about all aspects of creating a signature, from generating keys to using various command line tools and graphical interfaces. You will learn how the formats differ keystore and truststore, how to use apksigner and what to do if the key has expired.
Why a digital signature is needed and how it works
Digital signature in the ecosystem Android performs the function of a digital certificate. It associates a specific application with a specific developer. Unlike SSL certificates in web browsers, there is no third-party certificate authority (CA) required. You create a pair of keys yourself and sign your code with them.
When the user installs the application, the system verifies the signature. If it is valid, the application gains access to certain privileges. Moreover, to update an already installed application, the new version must be signed with the same key. This prevents a situation where an attacker tries to replace your application with his own using the same package name.
- 🔐 Identification: The signature uniquely identifies the author of the application for the operating system.
- 🛡️ Integrity: Any change in the bytes in the APK file after the signature will make the signature invalid.
- 🔄 Update: Only applications with a matching signature can update each other, preserving user data.
⚠️ Warning: Never share the keystore file (keystore) and passwords from him to third parties. Losing this file means that you will not be able to release updates for your application in the future.
The mechanism is based on public key cryptography. You keep the private key secret and the public key is embedded in the APK. The system uses the public key to verify that the file was actually encrypted with the corresponding private key.
Generating a key store (Keystore)
The first step in the process is to create a keystore. This is a special file, usually with the extension .jks or .keystorethat contains your key pair. To generate, use the utility keytool, included in Java Development Kit (JDK).
The generation process requires entering a number of parameters, such as the owner's name, organization and key expiration date. Expiration is critical: if the key expires, you will not be able to sign new versions of the application with the same key. It is recommended to set the validity period to 25 years or more.
keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-aliasWhen executing the command, the system will ask you to enter passwords. You will need to come up with a password for the vault itself and a separate password for the key inside it. It is often recommended to use the same passwords to simplify work with automation scripts, although this is not a strict security requirement.
| Parameter | Description | Recommended value |
|---|---|---|
-keyalg |
Encryption algorithm | RSA (standard industry) |
-keysize |
Key length in bits | 2048 or higher |
-validity |
Validity in days | 10000 (about 27 years) |
-alias |
Key alias | A unique name (for example, upload) |
After successful execution of the command, a file will appear in the current directory my-release-key.jks. Store it in a safe place, preferably with a backup copy in cloud storage or on external media. Losing this file is fatal for continued support of the application.
Save the key generation command and all entered data in a text file in encrypted form. After a few years, you may forget which algorithm or alias name you used.
Signing an APK using Jarsigner
The utility jarsigner is a classic tool for signing JAR archives, which includes the APK format. This method was widely used in the early days. versions Android SDK and still works, although Google recommends upgrading to newer tools.
The signing process requires an uncompressed APK file. If you are using Android Studio, make sure that the build is done in release and does not include the compression step (zipalign) that usually comes after the signature in modern pipelines.
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore my-release-key.jks app-release-unsigned.apk my-aliasIt is important to note that the use of the algorithm SHA1 is now considered obsolete from a security perspective, but many older devices still require support for compatibility. For modern applications (Android 7.0+), you should use SHA256withRSA.
Once jarsigner has finished, the file is technically signed, but is not yet optimized for installation. At this stage it is necessary to align the archive. Without this step, the application may run slowly or not launch at all on some devices.
⚠️ Attention: Make sure that the environment variable JAVA_HOME points to the correct version of the JDK. Using JRE instead of JDK will result in an error since JRE does not have development tools like jarsigner.
Using Apksigner for modern versions of Android
Starting from Android 7.0 (Nougat), APK Signature Scheme v2 was introduced. It signs the entire file, not just its contents, which makes the verification process much faster and safer. The tool jarsigner does not support this scheme, so you must use apksigner.
This utility is included in Android SDK Build-tools. It can both sign and verify the presence of a signature, as well as perform alignment (zipalign) in a single command cycle. This makes it the preferred choice for modern development.
The command syntax is slightly different from jarsigner. You need to explicitly specify the paths to the key and alias. Also apksigner allows you to sign a file with several keys at once, which is useful for complex corporate scenarios for distributing access rights.
apksigner sign --ks my-release-key.jks --out app-release.apk app-release-unsigned.apkAfter signing, it is strongly recommended to perform verification. This ensures that the file matches all signature schemes supported by the target versions of Android. Errors at this stage may only appear after publication in the store.
- ✅ v1 Signature: Classic JAR signing (required for older devices).
- ✅ v2 Signature: Signing the entire file (required for Android 7.0+).
- ✅ v3 Signature: Added in Android 9, allows you to change keys when updating.
☑️ Verification before publication
Automating the process in Gradle and Android Studio
Manually entering commands into the terminal with each build is ineffective and prone to errors. The development environment Android Studio and the build system Gradle allow you to configure automatic signing. This is done by editing the file build.gradle at the module level.
In the block android -> signingConfigs you specify the path to the key storage and passwords. gradle, which ends up in the version control system (Git), is unsafe.
signingConfigs { release { storeFile file("my-release-key.jks") storePassword "password" keyAlias "my-alias" keyPassword "password" } }
To protect sensitive data, it is recommended to put passwords in a separate file keystore.properties and add it to .gitignore. The build script then reads these values dynamically. This is standard practice in professional development.
After setting up the signature configuration, you need to bind it to the build type release. In the block buildTypes indicate signingConfig signingConfigs.release. Now, when you run the task assembleRelease APK will be signed automatically.
What to do if Gradle does not see the keys?
Make sure that the path to the keystore file is relative to the root folder of the module, not the project. Often the error occurs due to incorrect nesting of folders.
Verification and troubleshooting
Even after successful compilation, installation problems may occur. Type errors INSTALL_PARSE_FAILED_NO_CERTIFICATES indicate the absence of a signature or its incorrectness. For diagnostics, use the verification command.
The tool apksigner has a mode verifythat will show detailed information about all signature schemes found in the file. It will tell you whether the file is signed with schema v1, v2, or v3, and whether the certificates are valid.
apksigner verify --verbose app-release.apkIf you get a schema mismatch error, you may have used jarsigner for a file that requires v2, or vice versa. In such cases, it is better to re-sign the file using only apksignerwhich automatically adds the necessary schemas depending on the target SDK version.
Also a common problem is signature conflicts when updating. If the device already has a version of the application signed with a debug key (debug key), you will not be able to install the release version on top of it. The old application must be completely uninstalled before installing the new one.
⚠️ Note: Command line tool interfaces may be updated. Always check the official Android Developers documentation for the latest command flags, especially when upgrading to new versions of Build Tools.
Using apksigner verify --verbose is a mandatory step before submitting an APK to testers or uploading to the app store.
Frequently asked questions (FAQ)
Is it possible to use the same key for different applications?
Technically this is possible, but not recommended. Using different keys for different applications provides better isolation. If one application's key is compromised, your other projects will not be affected. Additionally, some system permissions require a unique signature.
What should I do if I lost my Keystore file?
Unfortunately, it is cryptographically impossible to recover the key. You won't be able to update an existing app on Google Play. The only way out is to create a new application with a new package name (applicationId) and publish it as a completely new product, losing the user base of the old one.
What is the difference between Debug and Release signature?
The debug signature (debug) is created automatically by Android Studio and has a short validity period. It is only suitable for testing. The release signature (release) is created manually by you, stored securely and used for publication in stores.
Do I need to sign AAB (Android App Bundle)?
Yes, format files .aab also must be signed before uploading to Google Play Console. However, if you use Play App Signing, Google can re-sign the file with its distribution keys, using your key only as an upload key.
How to extend the validity of an existing key?
You cannot extend the validity of an already created key. You will have to generate a new key with a new expiration date. For existing applications, this will create an update problem, so plan for a long validity period (25+ years) immediately when creating the first key.