Sign your app

Android requires that all APKs be digitally signed with a certificate before
they can be installed. And you need to sign your
Android App Bundle before you can upload it to the
Play Console.

This document describes how to sign your APK or app bundle using
Android Studio, including creating and storing your certificate, signing
different build configurations using different certificates, and configuring
the build process to sign your APKs automatically.

Certificates and keystores

A public-key certificate, also known as a digital certificate or an identity
certificate, contains the public key of a public/private key pair, as well as
some other metadata identifying the owner of the key (for example, name and
location). The owner of the certificate holds the corresponding private key.

When you sign an APK, the signing tool attaches the public-key certificate to
the APK—the same is true when signing an app bundle. The public-key certificate
serves as a "fingerprint" that uniquely
associates the APK or app bundle to you and your corresponding private key.
This helps Android ensure that any future updates to your app are authentic
and come from the original author. The key used to create this certificate is
called the app signing key.

A keystore is a binary file that contains one or more private keys.

Every app must use the same certificate throughout its lifespan in order for
users to be able to install new versions as updates to the app. For more
about the benefits of using the same certificate for all your apps throughout
their lifespans, see Signing Considerations
below.

Sign your debug build

When running or debugging your project from the IDE, Android Studio
automatically signs your app with a debug certificate generated by the
Android SDK tools. The first time you run or debug your project in Android
Studio, the IDE automatically creates the debug keystore and certificate in
$HOME/.android/debug.keystore, and sets the keystore and key
passwords.

Because the debug certificate is created by the build tools and is insecure
by design, most app stores (including the Google Play Store) will not accept
an APK or app bundle that's signed with a debug certificate for publishing.

Android Studio automatically stores your debug signing information in a
signing configuration so you do not have to enter it every time you debug. A
signing configuration is an object consisting of all of the necessary
information to sign your app, including the keystore location, keystore
password, key name, and key password. You cannot directly edit the debug
signing configuration, but you can configure how you
sign your release build.

Expiry of the debug certificate

The self-signed certificate used to sign your app for debugging has an
expiration date of 365 days from its creation date. When the certificate
expires, you will get a build error.

To fix this problem, simply delete the debug.keystore file. The
file is stored in the following locations:

~/.android/ on OS X and Linux

C:\Documents and Settings\<user>\.android\ on Windows XP

C:\Users\<user>\.android\ on Windows Vista and Windows
7, 8, and 10

The next time you build and run the debug build type, the build tools will
regenerate a new keystore and debug key. Note that you must run your app,
building alone does not regenerate the keystore and debug key.

Manage your key

Because your app signing key is used to verify your identity as a developer and
to ensure seamless and secure updates for your users, managing your key and
keeping it secure are very important, both for you and for your users. You
can choose either to opt in to use App Signing by Google Play to securely manage
and store your app signing key using Google's infrastructure or to manage and
secure your own keystore and app signing key.

By opting in to App Signing by Google Play, you will gain the following benefits:

Ensure that the app signing key is not lost. Loss of the app
signing key means that an app cannot be updated, so it is critical for it not to be lost.

Ensure that the app signing key is not compromised. Compromise of the key would allow a
malicious attacker to deploy a malicious version of your app as an update over an existing
install. With Play App Signing, developers only manage an upload key
which can be reset in the case of loss and compromise. In the event of compromise, an
attacker also needs access to the developer account to be able to do anything malicious.

Use App Signing by Google Play

With App Signing by Google Play, Google manages and protects your app's signing
key for you and uses it to sign your APKs for distribution. And, because app
bundles defer building and signing APKs to the Google Play Store, you need to
enroll in App Signing by Google Play before you upload your app bundle.

When using App Signing by Google Play, you will use two keys: the app signing
key and the upload key. You keep the upload key and use it to
sign your app for upload to the Google Play Store.

When you opt in to use App Signing by Google Play, you export and encrypt your
app signing key using the Play Encrypt Private Key tool provided by Google
Play, and then upload it to Google's infrastructure. Then you create a
separate upload key and register it with Google. When you are ready to
publish, you sign your app using the upload key and upload it to Google Play.
Google then uses the upload certificate to verify your identity, and
signs your APK(s) with your app signing key for distribution as shown in
figure 1. (If you do not already have an app signing key, you can generate
one during the sign-up process.)

Figure 1. Signing an app with App Signing by Google Play

When you use App Signing by Google Play, if you lose your upload key, or if it
is compromised, you can contact Google to revoke your old upload key and
generate a new one. Because your app signing key is secured by Google, you
can continue to upload new versions of your app as updates to the original
app, even if you change upload keys.

Manage your own key and keystore

Instead of using App Signing by Google Play, you can choose to manage your own
app signing key and keystore. If you choose to manage your own app signing
key and keystore, you are responsible for securing the key and the keystore.
Additionally, you cannot upload Android App Bundles without enrolling in
App Signing by Google Play.

When you are ready to create your own key and keystore, make sure you first
choose a strong password for your keystore and a separate strong
password for each private key stored in the keystore. You must keep your
keystore in a safe and secure place. If you lose access to your app signing
key or your key is compromised, Google cannot retrieve the app signing key
for you, and you will not be able to release new versions of your app to
users as updates to the original app. For more information, see Secure your key, below.

If you manage your own app signing key and keystore, when you sign your APK,
you will sign it locally using your app signing key and upload the signed APK
directly to the Google Play Store for distribution as shown in figure 2.

Figure 2. Signing an app when you manage your own app
signing key

Generate a key and keystore

If you don't already have an app signing or upload key, you can generate
one using Android Studio as follows:

In the menu bar, click Build >
Build > Generate Signed Bundle/APK.

In the Generate Signed Bundle or APK dialog, select
Android App Bundle or APK and click Next.

Below the field for Key store path, click Create new.

On the New Key Store window, provide the following
information for your keystore and key, as shown in figure 3.

Figure 3. Create a new keystore in Android Studio.

Keystore

Key store path: Select the location where your
keystore should be created.

Password: Create and confirm a secure password for
your keystore.

Key

Alias: Enter an identifying name for your key.

Password: Create and confirm a secure password for
your key. This should be different from the password you chose for your
keystore.

Validity (years): Set the length of time in years that
your key will be valid. Your key should be valid for at least 25 years,
so you can sign app updates with the same key through the lifespan of
your app.

Certificate: Enter some information about yourself for
your certificate. This information is not displayed in your app, but is
included in your certificate as part of the APK.

Once you complete the form, click OK.

Continue on to Sign your app for release if you
would like to generate an APK signed with your new key, or click
Cancel if you only want to generate a key and keystore, not sign an
APK.

If you would like to opt in to use App Signing by Google Play, proceed to
Manage
your app signing keys and follow the instructions to set up
App Signing by Google Play.

Sign your app for release

Regardless of how you choose to manage your key and keystore, or whether you
want to build an APK or app bundle, you can use
Android Studio to sign your app with either the upload key or the app
signing key:

If you choose to manage and secure your own app signing key and keystore,
you should sign your app with your app signing key.

If you choose to use App Signing by Google Play to manage and secure
your app signing key and keystore, you should sign your app with your
upload key.

To sign your APK for release in Android Studio, follow these steps:

Click Build > Generate Signed Bundle/APK.

In the Generate Signed Bundle or APK dialog, select
Android App Bundle or APK and click Next.

Select a module from the drop down.

If you have your signing information ready, select a keystore, a private
key, and enter the passwords for both. Otherwise, first
generate a key and keystore and then return to
complete this step.

Note: If you are using App Signing by Google Play,
you should specify your upload key here. If you are managing
your own app signing key and keystore instead, you should specify your app
signing key. For more information, see Manage your
key above.

Figure 4. Select a private key in Android Studio.

If you're building an app bundle, you can tell Android Studio to also save
your signing key as an encrypted file by checking the box next to Export
encrypted key. To be able to upload your app bundle and take advantage
of Dynamic Delivery, you
need to upload this encrypted file to the Play Console and enroll in
App Signing by Google Play.

Click Next.

On the next window, select a destination for the signed APK(s) or app
bundle(s), select the build type, choose the product flavor(s) if
applicable, and click Finish.

Figure 5. Generate a signed version of your app for the selected
product flavors.

Note: If your project uses product flavors, you can
select multiple product flavors while holding down the
Control key on Windows/Linux, or the
Command key on Mac OSX. Android Studio will generate a
separate APK or app bundle for each product flavor you select.

After Android Studio finishes building your signed app, you can either
locate or analyze your app by clicking on the appropriate option
in the pop-up notification. If you selected the option to export your signing
key, you can quickly navigate to it by clicking the dropdown arrow in the bottom
right corner of the popup to expand it and clicking
Show Exported Key File, as shown in figure 6.

Figure 6. After the IDE finishes generating your signed app bundle,
click the links in the popup to analyze or locate your app bundle, or locate
your exported signing key.

You may now distribute your
signed app through an app marketplace like the Google Play Store, or using the
mechanism of your choice. For more about how to publish your signed APK to the
Google Play Store, see Get Started
with Publishing. To learn more about other distribution options, read
Alternative Distribution
Options.

In order for users to successfully install updates to your app, you will need
to sign your app with the same certificate throughout the lifespan of your
app. For more about this and other benefits of signing all your apps with the
same key, see Signing Considerations below. For
more information about securing your private key and keystore, see Secure your key, below.

Configure the build process to automatically sign your app

In Android Studio, you can configure your project to sign the release version
of your app automatically during the build process by creating a signing configuration
and assigning it to your release build type. A signing configuration consists
of a keystore location, keystore password, key alias, and key password. To
create a signing configuration and assign it to your release build type using
Android Studio, complete the following steps:

In the Project window, right click on your app and click
Open Module Settings.

On the Project Structure window, under
Modules in the left panel, click the module you would like
to sign.

Click the Signing tab, then click Add.

Select your keystore file, enter a name for this signing configuration
(as you may create more than one), and enter the required information.

Figure 7. The window for creating a new signing
configuration.

Click the Build Types tab.

Click the release build.

Under Signing Config, select the signing configuration
you just created.

Figure 8. Select a signing configuration in Android
Studio.

Click OK.

Now every time you build your release build type by selecting an option under
Build > Build Bundle(s) / APK(s) in Android Studio, the
IDE will sign your app automatically, using the signing configuration you
specified. You can find your signed APK or app bundle in the
build/outputs/ directory inside the project directory for the
module you are building.

When you create a signing configuration, your signing information is included
in plain text in your Gradle build files. If you are working in a team or
sharing your code publicly, you should keep your signing information secure
by removing it from the build files and storing it separately. You can read
more about how to remove your signing information from your build files in
Remove Signing Information from Your Build
Files. For more about keeping your signing information secure, read
Secure your key.

Sign each product flavor differently

If your app uses product flavors and you would like to sign each flavor
differently, you can create additional signing configurations and assign them
by flavor:

In the Project window, right click on your app and click
Open Module Settings.

On the Project Structure window, under
Modules in the left panel, click the module you would like
to sign.

Click the Signing tab, then click Add.

Select your keystore file, enter a name for this signing configuration
(as you may create more than one), and enter the required information.

Figure 9. The window for creating a new signing
configuration.

Repeat steps 3 and 4 as necessary until you have created all your signing
configurations.

Click the Flavors tab.

Click the flavor you would like to configure, then select the appropriate
signing configuration from the Signing Config dropdown menu.

Sign Wear OS apps

Signing considerations

You should sign your app with the same certificate throughout its
expected lifespan. There are several reasons why you should do
so:

App upgrade: When the system is installing an update to an app, it
compares the certificate(s) in the new version with those in the existing
version. The system allows the update if the certificates match. If you sign
the new version with a different certificate, you must assign a different
package name to the app—in this case, the user installs the new version as a
completely new app.

App modularity: Android allows APKs signed by the same certificate to run
in the same process, if the apps so request, so that the system treats them
as a single app. In this way you can deploy your app in modules, and users
can update each of the modules independently.

Code/data sharing through permissions: Android provides signature-based
permissions enforcement, so that an app can expose functionality to another
app that is signed with a specified certificate. By signing multiple APKs
with the same certificate and using signature-based permissions checks, your
apps can share code and data in a secure manner.

If you plan to support upgrades for an app, ensure that your app signing key has a
validity period that exceeds the expected lifespan of that app. A validity
period of 25 years or more is recommended. When your key's validity period
expires, users will no longer be able to seamlessly upgrade to new versions
of your app.

If you plan to publish your apps on Google Play, the key you use to sign
your app must have a validity period ending after 22 October 2033. Google
Play enforces this requirement to ensure that users can seamlessly upgrade
apps when new versions are available. If you use
App Signing by Google Play, Google
ensures your apps are correctly signed and able to receive updates throughout
their lifespans.

Secure your key

If you choose to manage and secure your app signing key and keystore yourself
(instead of opting in to use App Signing by
Google Play), securing your app signing key is of critical importance, both
to you and to the user. If you allow someone to use your key, or if you leave
your keystore and passwords in an unsecured location such that a third-party
could find and use them, your authoring identity and the trust of the user
are compromised.

Note: If you use App Signing by Google Play, your app signing key is
kept secure using Google's infrastructure. You should still keep your upload
key secure as described below. If your upload key is compromised, you can
contact Google to revoke it and receive a new upload key.

If a third party should manage to take your key without your knowledge or
permission, that person could sign and distribute apps that maliciously
replace your authentic apps or corrupt them. Such a person could also sign
and distribute apps under your identity that attack other apps or the system
itself, or corrupt or steal user data.

Your private key is required for signing all future versions of your app. If
you lose or misplace your key, you will not be able to publish updates to
your existing app. You cannot regenerate a previously generated key.

Your reputation as a developer entity depends on your securing your app signing
key properly, at all times, until the key is expired. Here are some tips for
keeping your key secure:

Select strong passwords for the keystore and key.

Do not give or lend anyone your private key, and do not let unauthorized
persons know your keystore and key passwords.

In general, if you follow common-sense precautions when generating, using, and
storing your key, it will remain secure.

Remove signing information from your build files

When you create a signing configuration, Android Studio adds your signing
information in plain text to the module's build.gradle files. If
you are working with a team or open-sourcing your code, you should move this
sensitive information out of the build files so it is not easily accessible
to others. To do this, you should create a separate properties file to store
secure information and refer to that file in your build files as follows:

Note: You could choose to store your
keystore.properties file in another location (for example,
in the module folder rather than the root folder for the project, or on
your build server if you are using a continuous integration tool). In
that case, you should modify the code above to correctly initialize
keystorePropertiesFile using your actual
keystore.properties file's location.

You can refer to properties stored in keystoreProperties
using the syntax keystoreProperties['propertyName'].
Modify the signingConfigs block of your module's
build.gradle file to reference the signing information stored in
keystoreProperties using this syntax.

Open the Build Variants tool window and ensure that the
release build type is selected.

Select an option under Build > Build Bundle(s) / APK(s) to build
either an APK or app bundle of your release build.
You should see the build output in the
build/outputs/ directory for your module.

Because your build files no longer contain sensitive information, you can now
include them in source control or upload them to a shared codebase. Be sure
to keep the keystore.properties file secure. This may include
removing it from your source control system.

Sign your app from command line

You do not need Android Studio to sign your app. You can sign your app from
the command line, using apksigner for APKs or jarsigner for app bundles,
or configure Gradle to sign it for you during the build. Either way, you need to
first generate a private key using
keytool.
For example:

Note:keytool is located in the bin/
directory in your JDK. To locate your JDK from Android Studio, select File
> Project Structure, and then click SDK Location and you will
see the JDK location.

This example prompts you for passwords for the keystore and key, and to
provide the Distinguished Name fields for your key. It then generates the
keystore as a file called my-release-key.jks, saving it in the
current directory (you can move it wherever you'd like). The keystore
contains a single key that is valid for 10,000 days.

Sign your app manually from the command line

If you haven't already done so,
build your app from the command line.
If you want to sign an app bundle from the command line, you can use
jarsigner.
If you instead want to sign an APK, you need to use zipalign and apksigner
as described below.

This example outputs the signed APK at my-app-release.apk
after signing it with a private key and certificate that are stored in a
single KeyStore file: my-release-key.jks.

The apksigner tool supports other signing options, including
signing an APK file using separate private key and certificate files, and
signing an APK using multiple signers. For more details, see the apksigner
reference.

Note: To use the apksigner tool, you must
have revision 24.0.3 or higher of the Android SDK Build Tools installed.
You can update this package using the SDK Manager.

Verify that your APK is signed:

apksigner verify my-app-release.apk

Configure Gradle to sign your app

Open the module-level build.gradle file and add the
signingConfigs {} block with entries for storeFile,
storePassword, keyAlias and
keyPassword, and then pass that object to the
signingConfig property in your build type. For example:

Additionally, because you've configured the release build with your signing key,
the "install" task is available for that build type. So you can build, align,
sign, and install the release APK on an emulator or device all with the
installRelease task.