Keystore: What It Is, What Formats Exist and How It Works

What Is a Keystore

Keystore (KeyStore) is a standard mechanism of the Java Cryptography Architecture (JCA) for storing cryptographic keys, certificates, and trusted entries. In Android development, a Keystore is used to store the private key that signs the application before publication. The signature guarantees that the application was indeed released by the specified developer and that its code has not been altered after publication. Every application update must be signed with the same key, otherwise Google Play will reject the APK or App Bundle.

A Keystore can contain multiple entries (aliases), each representing a key pair (private and public) with a certificate. Alias is a unique entry name by which the application accesses the key during signing. In a typical Android project, the Keystore contains one entry for signing the release version and may contain additional ones for signing debug builds. Google Play Console displays SHA-1 and SHA-256 certificate fingerprints for each uploaded application.

Android Studio includes built-in Keystore support via the Build → Generate Signed Bundle / APK menu. Android Studio's signing wizard allows you to create a new Keystore or select an existing one, specify an alias, Keystore and key passwords, as well as certification details (organization name, city, country). This data is embedded in the certificate and visible to users when verifying the APK signature. Google Play requires the certificate to be valid for at least 25 years — Android checks the expiration date when installing the application.

Why Keystore Is Important for Android

Application updates in Google Play are only possible with the same key that signed the first version. If the Keystore is lost, it is impossible to publish an update — the application would have to be re-released under a new package name. According to Google Play Console Help (2026), the application signing key can only be recovered through Google Play App Signing — a service that stores the key on Google's side. If the developer used this option, losing the local Keystore is not critical.

How a Keystore Works

The process of signing an Android application involves creating a digest (hash) of the APK contents and encrypting it with the private key from the Keystore. Android SDK Build Tools include the apksigner utility, which performs signing using APK Signature Scheme v2 (or v3 for Android 9+). When installing the application, Android verifies the signature: it decrypts the signature with the certificate's public key, compares the APK hash with the original — if the hashes do not match, installation is rejected.

Android supports several signing schemes: v1 (JAR signing), v2 (APK Signature Scheme), v3 (APK Signature Scheme with key rotation support), and v4 (incremental installations for Android 11+). Google Play requires v2 or v3 for new applications. apksigner automatically adds all necessary schemes during signing if the key supports the corresponding algorithms. Android 11+ supports ADB installation with v4 signing, which speeds up incremental loading of large APKs onto the device.

Algorithms: Android recommends using RSA-2048 or ECDSA P-256 for the signing key. The certificate must be X.509 v3. Android verifies that the certificate is valid at the time of installation — if it has expired, installation is blocked. This is why Google recommends setting the certificate validity period to at least 25 years. Google Play App Signing uses two keys: the app signing key and the upload key — the upload key is used by the developer to upload the APK to the Console, and Google signs the application for users with the main key.

Keystore Formats: JKS and PKCS12

Java supports two main Keystore formats: JKS (Java KeyStore) — Oracle's proprietary format that has existed since JDK 1.2, and PKCS12 — the standardized Public-Key Cryptography Standards #12 format from RSA Laboratories. JKS uses its own data storage format and is only supported within the Java ecosystem. PKCS12 is an open standard supported by Java, .NET, OpenSSL, Python (cryptography), and most other cryptographic libraries.

Google Play recommends PKCS12 as the preferred format for new Keystores created after 2021. JDK 9 and later default to creating Keystores in PKCS12 format (previously the default was JKS). The main advantage of PKCS12 is compatibility: a .p12 file can be opened in any environment not tied to Java. OpenSSL can extract certificates from PKCS12 and convert them to PEM format. JKS files require JDK utilities to read and cannot be processed by OpenSSL.

Conversion between formats is done using the keytool utility from JDK. When migrating from JKS to PKCS12, ensure that all aliases and passwords are correctly transferred. The keytool -importkeystore command allows importing the contents of one Keystore into another regardless of format. After conversion, it is best to delete the old JKS file to avoid confusion with key versions. Android Studio supports both formats when generating a signed build.

Creating a Keystore with keytool

The keytool utility is part of the JDK (Java Development Kit) and provides a full set of commands for creating, viewing, and managing Keystores. To create a new Keystore with one key pair, use the keytool -genkeypair command with the PKCS12 format, RSA algorithm, key size, and certificate validity period specified. Google Play requires a certificate validity of at least 25 years (9125 days) — it is recommended to specify this value in the -validity parameter.

Creating a New Keystore

Example of generating a Keystore in PKCS12 format for an Android project. The -dname parameter contains the X.500 Distinguished Name of the certificate. The -ext parameter includes Subject Alternative Name if required — for Android, Basic Constraints are sufficient:

# Creating a PKCS12 Keystore for Android
keytool -genkeypair -alias "upload_key" \
  -keyalg RSA -keysize 2048 -validity 9125 \
  -keystore "release-keystore.p12" \
  -storetype PKCS12 \
  -dname "CN=Developer,O=Company,C=RU"

Keytool will prompt for the Keystore password and key password (they can match). The -storetype PKCS12 parameter creates a file in the modern format. -keysize 2048 meets Google's requirements for the minimum RSA key size. -validity 9125 (25 years) ensures compatibility for the entire expected lifecycle of the application. After creating the Keystore, it is recommended to verify its contents with the keytool -list -v -keystore release-keystore.p12 command.

Viewing Keystore Contents

To check Keystore entries, use the command with the -list flag. The output includes the alias, creation and expiration dates, entry type, and SHA-256 fingerprints. Android Studio displays the same information in the Generate Signed Bundle / APK dialog when selecting an existing Keystore:

# Viewing Keystore Entries
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

Using Keystore in CI/CD

In a CI/CD pipeline, the Keystore must be stored securely and passed to the build agent without risk of compromise. GitHub Actions provides Secrets for storing binary files in base64 format. The Keystore is encoded using the base64 command, the resulting string is saved in repository secrets, and during the build stage it is decoded back into a file. GitLab CI uses a similar mechanism through Variables of type File.

An example of setting up a CI build with Keystore in GitHub Actions includes decoding the Keystore from a secret, configuring Gradle properties, and executing a signed build. Gradle's Android plugin reads the Keystore path and passwords from the keystore.properties file (excluded from .gitignore for local development) or from CI system environment variables:

// build.gradle (app) — signing configuration
@Override
android {
    signingConfigs {
        release {
            storeFile file("release-keystore.p12")
            storePassword System.getenv("STORE_PASSWORD")
            keyAlias System.getenv("KEY_ALIAS")
            keyPassword System.getenv("KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

Gradle reads environment variables set by the CI system. The Keystore file should be located in the root of the application module, as specified in storeFile. For security, never store passwords in the repository — use CI system Secrets. Fastlane for Android provides the supply plugin, which works with Google Play Console, but APK signing still requires a local Keystore on the agent.

An alternative is Google Play App Signing. When using this option, the developer uploads only the upload key to Google Play, and Google signs the final APK with its own key. In this case, the Keystore is only used to create the upload key, and losing it does not block updates — a new upload key can be generated and registered in the Console. Google Play App Signing is mandatory for new applications since August 2021.

Keystore Security and Backup

Losing a Keystore is one of the most critical issues in Android development. Without a backup, it is impossible to release an update to an existing application — Google Play rejects APKs signed with a different key. It is recommended to keep at least two backup copies of the Keystore in different physical or cloud storages: for example, an encrypted file in the team's cloud storage and a physical medium in the organization's safe. Keystore and key passwords are stored separately from the file, for example, in a password manager with access control.

Android Studio, when creating a new Keystore in the Generate Signed Bundle / APK dialog, offers to remember the paths for future builds. However, the development environment itself does not create a backup — this is the developer's responsibility. For team development, it is recommended to use Google Play App Signing with the upload key passed through a secure channel to all team members. Gradle can sign debug builds automatically with a generated debug.keystore, which does not require backup — it is the same for all Android Studio installations.

Keystore security during transfer: .p12 or .jks files must only be transferred through encrypted channels (SFTP, HTTPS, encrypted email attachments). Never include the Keystore in the source code repository — even a private one. GitGuardian or GitHub secret scanning automatically detect credential publication, but storing the Keystore in a repository is still a security violation. For CI/CD, use the platform's secret mechanism (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) with infrastructure-level encryption.