Update your Android app signing key from a new Keystore with Play App Signing.

5 min readFeb 17, 2023

Hello everyone! Today, I would like to talk to you about a topic that is rarely discussed in our work as Android engineers but is one of the most important things we should consider in case the need arises: updating your app signing key. 🔑

It is important to clarify that this article assumes that you are using Play App Signing; beforehand, it would be ideal to use this feature in the Google Play Console. On the other hand, we are going to carry out the process by generating the new certificate from a new Keystore.

Play App Signing

It is a service offered to Android developers by the Google Play Console that allows you to store your app’s signing key in Google’s secure infrastructure and offers upgrade options to increase security.

See more information here.

But why would I have to change my signature key?

You should consider changing your signing key if you suffer a loss of it or if it is compromised by people outside your organization. Another scenario would be when the application changes ownership and you want to ensure that only authorized people have access to the key; and finally, if your signing key collides with another App Signing Key.

First we will create a new Keystore to generate the new app signing key. You can generate a Keystore from Android Studio or from the command line with help of keytool.

If you want to use Android Studio, check out the Android documentation here.

Modal to create a keystore from android studio

On the other hand if you want to use the keytool then you could copy the following command

keytool -genkey -v -keystore new_keystore.jks -alias new_alias -keyalg RSA -keysize 2048 -validity 10000

A keystore with the specified name and the private key associated with the specified alias will be generated. In the creation process, you will be asked for some details, such as the name and location of the organization, the common name of the issuer, etc.

Now go to the Play App Signing page and select the App signing tab. (Release > Setup > App integrity > App signing tab).

Then, request to update the signing key and select the option Upload a new app signing key from Java Keystore and execute the suggested steps:

1. Download the PEPK tool
2. Copy the command shown in the Play Console and replace only the parameters highlighted in bold
3. Once the certificate is generated, upload it to the Play Store Console

Image to represent the option: Upload a new app signing key from Java Keystore

PEPK tool is an encryption tool provided by Google for protecting private keys of Android applications. PEPK stands for “Private Key Encryption Protection” and is a file format that contains an encrypted private key with a master password.

Let’s explain a little more detailed the command that we must execute. Open your terminal and paste the command copied from the Google Play console

java -jar pepk.jar \
    --keystore=foo.keystore \
    --alias=foo \
    --output=output.zip \
    --signing-keystore=uploadkey.keystore \
    --signing-key-alias=upload-key-alias \
    --encryptionkey=generated-encryption-key

Next I explain what each argument means.

keystore: specifies the location and filename of the new keystore that will be used to sign the encrypted private key output by the PEPK tool. This keystore should contain a private key with the alias specified by the alias parameter.
alias: This is the alias of the private key in the keystore file that will be used in the signed file.
output: This parameter is used to specify the name of the signed file.
signing-keystore: specifies the location and filename of the existing keystore that contains the private key that will be used to sign the APK file after it is processed by the PEPK tool. The keystore specified here should contain a private key with the alias specified by the signing-key-alias parameter.
signing-key-alias: This parameter specifies the alias of the private key in the keystore file that will be used to sign the file.
encryptionkey: Encryption key to use to encrypt the output file.

📝: signing-keystore and signing-key-alias are parameters that correspond to the keystore that contains the upload key certificate. If by mistake you put in all the parameters only the data of the new keystore you will get the following error: