Use Play App Signing - Play Console Help (original) (raw)

With Play App Signing, Google manages and protects your app's signing key for you and uses it to sign optimized distribution APKs that are generated from your app bundles. Play App Signing stores your app signing key on Google’s secure infrastructure and offers upgrade options to increase security.

To use Play App Signing in, you need to be an account owner or a user with the Release to production, exclude devices, and use Play App Signing permission, and you need to accept the Play App Signing Terms of Service.

How it works

When you use Play App Signing, your keys are stored on the same secure infrastructure that Google uses to store its own keys. Keys are protected by Google’s Key Management Service. If you want to learn more about Google’s infrastructure, read the Google Cloud Security Whitepaper.

Android apps are signed with a private key. To ensure that app updates are trustworthy, every private key has an associated public certificate that devices and services use to verify that the app update is from the same source. Devices only accept updates when its signature matches the installed app’s signature. By letting Google manage your app signing key, it makes this process more secure.

Note: For apps created before August 2021,you can still upload an APK and manage your own keys instead of using Play App Signing and publishing with an Android App Bundle. However, if you lose your keystore or it becomes compromised, you won’t be able to update your app without publishing a new app with a new package name. For these apps, Play recommends using Play App Signing and switching to app bundles.

Descriptions of keys, artifacts, and tools

Term	Description
App signing key	The key Google Play uses to sign the APKs that are delivered to a user's device. When you use Play App Signing, you can either upload an existing app signing key or have Google generate one for you. Keep your app signing key secret, but you can share your app’s public certificate with others.
Upload key	The key you use to sign your app bundle before you upload it on Google Play. Keep your upload key secret, but you can share your app’s public certificate with others. For security reasons, it’s a good idea to have app signing and upload keys that are different from each other. There are two ways to generate an upload key: Use your app signing key: If you have Google generate an app signing key, the key you use for your first release is also your upload key. Use a separate upload key: If you provide your own app signing key,you are given the option to generate a new upload key for increased security. If you don’t generate one, use your app signing key as your upload key to sign releases.
Certificate (.der or .pem)	A certificate contains a public key and extra identifying information about who owns the key. The public key certificate lets anyone verify who signed the app bundle or APK, and you can share it with anyone because it doesn’t include your private key. To register your key(s) with API providers, you can download the public certificate for your app signing key and your upload key from the Play App Signing page (Test and release> Setup > App signing) in Play Console. The public key certificate can be shared with anyone. It doesn’t include your private key.
Certificate fingerprint	A short and unique representation of a certificate that is often requested by API providers with the package name to register an application to use their service. The MD5, SHA-1, and SHA-256 fingerprints of the upload and app signing certificates can be found on the Play App Signing page (Test and release > Setup > App signing) in Play Console. Other fingerprints can also be computed by downloading the original certificate (.der) on the same page.
Java keystore (.jks or .keystore)	A repository of security certificates and private keys.
Play Encrypt Private Key (PEPK) tool	A tool to export private keys from a Java keystore and encrypt them for transfer to Google Play. When you provide the app signing key for Google to use, select the option to export and upload your key (and its public certificate if required) and follow the instructions to download and use the tool. If you prefer, you can download, review, and use the PEPK tool’s open source code.

App signing process

Here’s how the process works:

Sign your app bundle and upload it to Play Console.
Google generates optimized APKs from your app bundle and signs them with the app signing key.
Google uses apksigner to add two stamps to your app’s manifest (com.android.stamp.source and com.android.stamp.type) and then sign the APKs with your app signing key. Stamps added by apksigner make it possible to trace APKs to who signed them.
Google delivers signed APKs to users.

Set up and manage Play App Signing

If your app isn't yet using Play App Signing, follow the instructions below.

Step 1: Create an upload key

Following these instructions, create an upload key.
Sign your app bundle with the upload key.

Step 2: Prepare your release

Follow the instructions to prepare and roll out your release.
After you select a release track, the “App integrity” section displays the status of Play App Signing for your app.
To proceed with a Google-generated app signing key, upload your app bundle. Alternatively, you can select Change app signing key to access the following options:
- Use a Google-generated app signing key: More than 90% of new apps use Google-generated app signing keys. Using a Google-generated key protects against loss or compromise (the key is not downloadable). If you choose this option, you can download distribution APKs from the App bundle explorer signed with the Google-generated key for other distribution channels, or use a different key for them.
- Use a different app signing key: Choosing the app signing key allows you to use the same key as another app in your developer account or keep a local copy of your app signing key for increased flexibility. For example, you might already have a key decided because your app is pre-installed on some devices. Having a copy of your key outside Google’s servers increases risk if the local copy is ever compromised. You have the following options for how to use a different key:
  * Use the same app signing key as another app in this developer account
  * Export and upload a key from Java keystore
  * Export and upload a key (not using Java keystore)
  * Opt out of Play App Signing (you should only choose this option if you plan to upgrade your app signing key to enroll into Play App Signing).
Complete the remaining instructions to prepare and roll out your release.

Note: You need to accept the Terms of Service and opt in to app signing to continue.

Step 3: Register your app signing key with API providers

If your app uses any APIs, you usually need to register your app signing key with them for authentication purposes using the fingerprint of the certificate. Here’s where to find the certificate:

Open Play Console and go to the Play App Signing page (Test and release > Setup > App signing).
- Tip: You can also access this page via the App integrity page (Test and release > App integrity), which contains integrity and signing services that help you ensure that users experience your apps and games in the way you intend.
Scroll to the “App signing key certificate” section and copy the fingerprints (MD5, SHA-1, and SHA-256) of your app signing certificate.
- If the API provider requires a different type of fingerprint, you can also download the original certificate in .der format and convert it using the transformation tools that the API provider requires.

App signing key requirements

When you use a Google-generated key, Google automatically generates a cryptographically strong RSA key that’s 4096 bits. If you choose to upload your own app signing key, then it must be an RSA key that’s 2048 bits or more.

Instructions for private apps and apps created before August 2021

Step 1: Configure Play App Signing

Open Play Console and go to the Play App Signing page (Test and release > Setup > App signing).
- Tip: You can also access this page via the App integrity page (Test and release > App integrity), which contains integrity and signing services that help you ensure that users experience your apps and games in the way you intend.
If you haven’t already, review the Play App Signing Terms of Service and select Accept.

Step 2: Send a copy of your original key to Google and create an upload key

Locate your original app signing key.
Open Play Console and go to the Play App Signing page (Test and release > Setup > App signing).
Select the export and upload option that best suits your release process and upload an existing app signing key.

Step 3: Create an upload key (optional and recommended)

Create an upload key and upload the certificate to Google Play.
- You can also continue to use the app signing key as your upload key.
Copy the fingerprints (MD5, SHA-1, and SHA-256) of your app signing certificate.
- For testing purposes, you may need to register the certificate of your upload key with API providers using the certificate fingerprint and the app signing key.

Step 4: Sign your next app update with the upload key

When you release updates for your app, you need to sign them with your upload key.

If you didn’t generate a new upload key: Continue using your original app signing key to sign app bundles before you upload them to Google Play. If you lose your original app signing key, you can generate a new upload key and register it with Google to continue updating your app.
If you generated a new upload key: Use your new upload key to sign app bundles before you upload them to Google Play. Google uses the upload key to verify your identity. If you lose your upload key, you can contact support to reset it.

Upgrade your app signing key to enroll into Play App Signing

You might want to do it if you are not able to share your existing key. Before you choose to upgrade your app signing key to enroll, note that:

This option will require a dual release.
You will need to upload an app bundle and an APK signed with your legacy key in every release. Google Play will use your app bundles to generate APKs signed with the new key for devices on Android R* (API level 30) or later. Your legacy APKs will be used for older Android releases (up to API level 29).

*If your app makes use of sharedUserId, it is recommended to apply key upgrade for installs and updates on devices running Android T (API level 33) or later. To configure this, please set an accurate minimum SDK version in the bundle configuration.

Step 1: Upload your new key and generate and upload proof-of-rotation

For the new key to be trusted on Android devices, you must upload a new signing key from a repository, and generate and upload proof-of-rotation:

Open Play Console and go to the Play App Signing page (Test and release > Setup > App signing).
- Tip: You can also access this page via the App integrity page (Test and release > App integrity), which contains integrity and signing services that help you ensure that users experience your apps and games in the way you intend.
Select the App signing tab.
Click Show advanced options, and select Use a new app signing key (this requires ongoing dual releases).
Choose to use the same app signing key as another app in your developer account, or to upload a new app signing key from Android Studio, Java KeyStore, or another repository.
Following the on-screen instructions, download and run the PEPK tool.
When your ZIP is ready, click Upload generated ZIP and upload it to Play Console.
Next to "5. Allow the new key to be trusted on Android devices by uploading proof-of-rotation," click Show instructions.
Download APKSigner and generate proof-of-rotation by running this command:
- $ apksigner rotate --out /path/to/new/file --old-signer --ks old-signer-jks --set-rollback true --new-signer --ks new-signer-jks --set-rollback true
Click Upload generated proof-of-rotation file, and upload the proof-of-rotation generated in step 8.
Click Save.

Create an upload key and update keystores

For increased security, signing your app with a new upload key, instead of your app signing key, is recommended.

You can create an upload key when you opt in to Play App Signing, or you can create an upload key later by visiting the Play App Signing page (Test and release > Setup > App signing).

Here’s how to create an upload key:

Follow the instructions on the Android Developers site. Store your key in a safe place.
Export the certificate for the upload key to PEM format. Replace the following underlined arguments:
- $ keytool -export -rfc -keystore upload-keystore.jks -alias upload -file upload_certificate.pem
When prompted during the release process, upload the certificate to register it with Google.

When you use an upload key:

Your upload key is only registered with Google to authenticate the identity of the app creator.
Your signature is removed from any uploaded APKs before they’re sent to users.

Upload key requirements

Must be an RSA key that's 2048 bits or more.

Update keystores

After you create an upload key, here are some locations that you may want to check and update:

Local machines
Locked on-site server (varying ACLs)
Cloud machine (varying ACLs)
Dedicated secrets management services
(Git) repositories

Upgrade your app signing key

This section contains instructions relating to upgrading your app signing key. If you lost your upload key, you do not need to request a key upgrade; refer instead to the Lost or compromised upload key? section at the bottom of this page.

In some circumstances, you can request an app signing key upgrade.

Here are a couple of reasons to request an app signing key upgrade:

You need a cryptographically stronger key.
Your app signing key has been compromised.

Important: Key upgrades are only supported for apps that use app bundles.

Before requesting a key upgrade in Play Console, read the Important considerations before requesting a key upgrade section below. You can then expand the other sections below to learn more about requesting a key upgrade.

Important considerations before requesting a key upgrade

Before requesting a key upgrade, it’s important to understand the changes that you may need to make after the upgrade is complete.

If you use the same app signing key for multiple apps to share data/code between them, you need to update your apps to recognize both your new and legacy app signing key certificates. On devices running Android S (API level 32) or below, only the legacy app signing key certificate is recognized by the Android platform for the purpose of data/code sharing.
If your app uses APIs, make sure to register the certificates for your new and legacy app signing key with API providers before publishing an update to ensure the APIs continue working. Certificates are available on the Play App Signing page (Test and release > Setup > App signing) in Play Console.
If any of your users install updates via peer-to-peer sharing, they’ll only be able to install updates that are signed with the same key as the version of your app which they already have installed. If they’re unable to update their app because they have a version of your app that’s signed with a different key, they have the option of uninstalling and reinstalling the app to get the update.

Request a key upgrade for all installs on Android N (API level 24) and above

Each app can have its app signing key upgraded for all installs on Android N (API level 24) and above once annually.

If you successfully request this key upgrade, your new key is used to sign all installs and app updates. On devices running Android T (API level 33) and above, the Android platform enforces the usage of the upgraded key. On devices running Android S (API level 32) or below, the Android platform does not enforce the usage of this upgraded key and still recognizes the legacy signing key as the app’s signing key. This also includes any Android platform features (for example, custom permission sharing) that rely on the app’s signing key. On devices running Android N (API level 24) to Android S (API level 32), Google Play Protect will check that app updates are signed with your upgraded key, unless turned off by the user. This provides an additional validation since the Android Platform does not enforce the usage of the upgraded key on devices running Android S (API level 32) or below.

Open Play Console and go to the Play App Signing page (Test and release > Setup > App signing).
- Tip: You can also access this page via the App integrity page (Test and release > App integrity), which contains integrity and signing services that help you ensure that users experience your apps and games in the way you intend.
In the “Upgrade your app signing key” card, select Request key upgrade.
Select an option to upgrade your app signing key to all installs on Android N and above.
Have Google generate a new app signing key (recommended) or upload one.
- After upgrading your app signing key, if you were using the same key for your app signing and upload key, you can continue using your legacy app signing key as your upload key or generate a new upload key.
Select a reason for requesting app signing key upgrade.
If necessary, register your new app signing key with API providers.

Tip: If you distribute your app on multiple distribution channels and you want to maximise app update compatibility for your users, you should upgrade your key on each distribution channel. To be compatible with Google Play’s key upgrade, use the ApkSigner tool, bundled with Android SDK Build Tools (revision 33.0.1+):

$ apksigner sign --in ${INPUT_APK}

--out ${OUTPUT_APK}

--ks ${ORIGINAL_KEYSTORE}

--ks-key-alias ${ORIGINAL_KEY_ALIAS}

--next-signer --ks ${UPGRADED_KEYSTORE}

--ks-key-alias ${UPGRADED_KEY_ALIAS}

--lineage ${LINEAGE}

Learn more about how app updates work.

Best practices

If you also distribute your app outside of Google Play or plan to later and want to use the same signing key, you have two options:
- Either let Google generate the key (recommended) and then download a signed, universal APK from the from App bundle explorer to distribute outside of Google Play.
- Or you can generate the app signing key you want to use for all app stores, and then transfer a copy of it to Google when you configure Play App Signing.
To protect your account, turn on 2-Step Verification for accounts with access to Play Console.
After publishing an app bundle to a release track, you can visit the App bundle explorer to access installable APKs that Google generates from your app bundle. You can:
- Copy and share an internal app sharing link that allows you to test, in a single tap, what Google Play would install from your app bundle on different devices.
- Download a signed, universal APK. This single APK is signed with the app signing key that Google holds and is installable on any device that your app supports.
- Download a ZIP archive with all of the APKs for a specific device. These APKs are signed with the app signing key that Google holds. You can install the APKs in the ZIP archive on a device using the adb install-multiple *.apk command.
For increased security, generate a new upload key that’s different from your app signing key.
If you're using any Google API, you may want to register the upload key and app signing key certificates in the Google Cloud Console for your app.
If you're using Android App Links, make sure to update keys in the corresponding Digital Asset Links JSON file on your website.

Lost or compromised upload key?

If you’ve lost your private upload key or it’s been compromised, you can create a new one. Your developer account owner can then initiate a key reset in Play Console.

After our support team registers the new upload key, the account owner and global admins will receive a notification and email with further information. You can then update your keystores and register your key with API providers.

The account owner can also cancel the reset request in Play Console.

Important: Resetting your upload key doesn’t affect the app signing key that Google Play uses to re-sign APKs before delivering them to users.

APK Signature Scheme v4

Android 11 and above devices support the new APK signature scheme v4. Play App Signing uses v4 signing for eligible apps in order to make it possible for them to access optimized distribution features available on newer devices. No developer action is required and no user impact from v4 signing is expected.

Learn about integrity and signing services in Play Console
Learn about integrity and signing services on the Android developers site