This document provides information about signing your Android applications prior to publishing them for mobile device users.
Overview
The Android system requires that all installed applications be digitally
signed with a certificate whose private key is held by the application's
developer. The Android system uses the certificate as a means of identifying the author of
an application and establishing trust relationships between applications. The certificate is not
used to control which applications the user can install. The certificate
does not need to be signed by a certificate authority: it is perfectly
allowable, and typical, for Android applications to use self-signed
certificates.
The important points to understand about signing Android applications are:
- All applications must be signed. The system will not install an application
that is not signed.
- You can use self-signed certificates to sign your applications. No certificate authority
is needed.
- When you are ready to release your application for end-users, you must sign it with a suitable private
key. You can not publish an application that is signed with the debug key generated
by the SDK tools.
- The system tests a signer certificate's expiration date only at install time. If an
application's signer certificate expires after the application is installed, the application
will continue to function normally.
- You can use standard tools — Keytool and Jarsigner — to generate keys and
sign your application .apk files.
The Android system will not install or run an application that is not signed appropriately. This
applies wherever the Android system is run, whether on an actual device or on the emulator.
For this reason, you must set up signing for your application before you will be able to
run or debug it on an emulator or device.
The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin
for Eclipse and the Ant build tool offer two signing modes — debug mode
and release mode.
- While developing and testing, you can compile in debug mode.
In debug mode, the build tools use the Keytool utility, included in the JDK, to create
a keystore and key with a known alias and password. At each compilation, the tools then use
the debug key to sign the application .apk file. Because the password is known, the tools
don't need to prompt you for the keystore/key password each time you compile.
- When your application is ready for release, you must compile in release mode
and then sign the .apk with your private key.
There are two ways to do this:
- Using Keytool and Jarsigner in the command-line. In this approach,
you first compile your application to an unsigned .apk. You must then sign
the .apk manually with your private key
using Jarsigner (or similar tool). If you do not have a suitable private key already,
you can run Keytool manually to generate your own keystore/key and then sign your
application with Jarsigner.
- Using the ADT Export Wizard. If you are developing in Eclipse with the ADT plugin,
you can use the Export Wizard to compile the application, generate a private key
(if necessary), and sign the .apk, all in a single process using the Export Wizard.
Signing Strategies
Some aspects of application signing may affect how you approach the development
of your application, especially if you are planning to release multiple
applications.
In general, the recommended strategy for all developers is to sign
all of your applications with the same certificate, throughout the expected
lifespan of your applications. There are several reasons why you should do so:
- Application upgrade – As you release upgrades to your
application, you will want to sign the upgrades with the same certificate, if you
want users to upgrade seamlessly to the new version. When the system is
installing an update to an application, if any of the certificates in the
new version match any of the certificates in the old version, then the
system allows the update. If you sign the version without using a matching
certificate, you will also need to assign a different package name to the
application — in this case, the user installs the new version as a
completely new application.
- Application modularity – The Android system allows applications that
are signed by the same certificate to run in the same process, if the
applications so requests, so that the system treats them as a single application.
In this way you can deploy your application in modules, and users can update
each of the modules independently if needed.
- Code/data sharing through permissions – The Android system provides
signature-based permissions enforcement, so that an application can expose
functionality to another application that is signed with a specified
certificate. By signing multiple applications with the same certificate and
using signature-based permissions checks, your applications can share code and
data in a secure manner.
Another important consideration in determining your signing strategy is
how to set the validity period of the key that you will use to sign your
applications.
- If you plan to support upgrades for a single application, you should ensure
that your key has a validity period that exceeds the expected lifespan of
that application. 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 application.
- If you will sign multiple distinct applications with the same key,
you should ensure that your key's validity period exceeds the expected
lifespan of all versions of all of the applications, including
dependent applications that may be added to the suite in the future.
- If you plan to publish your application(s) on Android Market, the
key you use to sign the application(s) must have a validity period
ending after 22 October 2033. The Market server enforces this requirement
to ensure that users can seamlessly upgrade Market applications when
new versions are available.
As you design your application, keep these points in mind and make sure to
use a
suitable certificate to sign your applications.
Basic Setup for Signing
To support the generation of a keystore and debug key, you should first make sure that
Keytool is available to the SDK build
tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure
that your JAVA_HOME environment variable is set and that it references a suitable JDK.
Alternatively, you can add the JDK version of Keytool to your PATH variable.
If you are developing on a version of Linux that originally came with GNU Compiler for
Java, make sure that the system is using the JDK version of Keytool, rather than the gcj
version. If Keytool is already in your PATH, it might be pointing to a symlink at
/usr/bin/keytool. In this case, check the symlink target to make sure that it points
to the Keytool in the JDK.
If you will release your application to the public, you will also need to have
the Jarsigner tool available on your machine. Both Jarsigner and Keytool are included
in the JDK.
Signing in Debug Mode
The Android build tools provide a debug signing mode that makes it easier for you
to develop and debug your application, while still meeting the Android system
requirement for signing your .apk when it is installed in the emulator or a device.
When you use debug mode, the SDK tools invoke Keytool to create a debug
keystore and key.
The SDK tools create the debug keystore/key with predetermined names/passwords;
- Keystore name – "debug.keystore"
- Keystore password – "android"
- Key alias – "androiddebugkey"
- Key password – "android"
- CN – "CN=Android Debug,O=Android,C=US"
If necessary, you can change the location/name of the debug keystore/key or
supply a custom debug keystore/key to use. In Eclipse/ADT, you can use
Windows > Prefs >
Android > Build. However, any custom debug
keystore/key must use the same keystore/key names and passwords as the default
debug key (as described above).
Note: You cannot release your application
to the public when signed with the debug certificate.
Eclipse Users
If you are developing in Eclipse/ADT and have set up Keytool as described
above, signing in debug mode is enabled by default. When you run or debug your
application, ADT signs the .apk with the debug certificate and installs it on
the emulator. No specific action on your part is needed, provided ADT has
access to Keytool.
Ant Users
If you use Ant to build your .apk files, debug signing mode
is enabled by using the debug option, assuming that you are using a
build.xml file generated by the
android tool. When you run ant debug to
compile your app, the build script generates a keystore/key and signs the .apk for you.
No other action on your part is needed. Read
Developing In Other IDEs: Building
in debug mode for more information.
Expiry of the Debug Certificate
The self-signed certificate used to sign your application in debug mode (the default on
Eclipse/ADT and Ant builds) will have an expiration date of 365 days from its creation date.
When the certificate expires, you will get a build error. On Ant builds, the error
looks like this:
debug:
[echo] Packaging bin/samples-debug.apk, and signing it with a debug key...
[exec] Debug Certificate expired on 8/4/08 3:43 PM
In Eclipse/ADT, you will see a similar error in the Android console.
To fix this problem, simply delete the debug.keystore file.
The default storage location for AVDs is in ~/.android/avd on OS X and Linux,
in C:\Documents and Settings\\.android\ on Windows XP, and in
C:\Users\\.android\ on Windows Vista.
The next time you build, the build tools will regenerate a new keystore and debug key.
Note that, if your development machine is using a non-Gregorian locale, the build
tools may erroneously generate an already-expired debug certificate, so that you get an
error when trying to compile your application. For workaround information, see the
troubleshooting topic
I can't compile my app because the build tools generated an expired debug
certificate.
Signing for Public Release
When your application is ready for release to other users, you must:
- Compile the application in release mode
- Obtain a suitable private key
- Sign the application with your private key
The sections below provide information about how to perform these steps.
If you use Eclipse with the ADT plugin, you can instead use the Export Wizard
to compile and sign an .apk with your private key. The Export Wizard even allows you to
generate a new keystore and private key in the process. Skip to
Compiling and signing with Eclipse ADT.
Compiling for release
To prepare your application for release, you must first compile it in release mode.
In release mode, the Android build tools compile your application as usual,
but without signing it with the debug key.
Note:
You can not release your application unsigned, or signed with the debug key.
Eclipse users
To export an unsigned .apk from Eclipse, right-click the project in the Package
Explorer and select Android Tools > Export Unsigned Application
Package. Then simply specify the file location for the unsigned .apk.
(Alternatively, open your AndroidManifest.xml file in Eclipse, open
the Overview tab, and click Export an unsigned .apk.)
You can also combine the compiling and signing steps with the Export Wizard. See
Compiling and signing with Eclipse ADT.
Ant users
If you are using Ant, all you need to do is specify the build target
"release" in the Ant command. For example, if you are running Ant from the
directory containing your build.xml file, the command would look like this:
$ ant release
The build script compiles the application .apk without signing it.
Obtaining a Suitable Private Key
In preparation for signing your application, you must first ensure that
you have a suitable private key with which to sign. A suitable private
key is one that:
The key may be self-signed. If you do not have a suitable key, you must
generate one using Keytool. Make sure that you have Keytool available, as described
in
Basic Setup.
To generate a self-signed key with Keytool, use the keytool
command and pass any of the options listed below (and any others, as
needed).
Note: Before you run Keytool, make sure to read
Securing Your Private Key for a discussion of how to keep
your key secure and why doing so is critically important to you and to users. In
particular, when you are generating your key, you should select strong passwords
for both the keystore and key.
| Keytool Option |
Description |
-genkey | Generate a key pair (public and private
keys) |
-v | Enable verbose output. |
-keystore <keystore-name>.keystore | A name
for the keystore containing the private key. |
-storepass <password> | A password for the
keystore. As a security precaution, do not include this option
in your command line unless you are working at a secure computer.
If not supplied, Keytool prompts you to enter the password. In this
way, your password is not stored in your shell history. |
-alias <alias_name> | An alias for the key. |
-keyalg <alg> | The encryption algorithm to use
when generating the key. Both DSA and RSA are supported. |
-dname <name> | A Distinguished Name that describes
who created the key. The value is used as the issuer and subject fields in the
self-signed certificate. Note that you do not need to specify this option
in the command line. If not supplied, Jarsigner prompts you to enter each
of the Distinguished Name fields (CN, OU, and so on). |
-validity <valdays> | The validity period for the
key, in days. Note: A value of 10000 or greater is recommended. |
-keypass <password> | The password for the key.
As a security precaution, do not include this option
in your command line unless you are working at a secure computer.
If not supplied, Keytool prompts you to enter the password. In this
way, your password is not stored in your shell history. |
Here's an example of a Keytool command that generates a private key:
$ keytool -genkey -v -keystore my-release-key.keystore
-alias alias_name -keyalg RSA -validity 10000
Running the example command above, Keytool prompts you to provide
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.keystore. The keystore and key are
protected by the passwords you entered. The keystore contains
a single key, valid for 10000 days. The alias is a name that you —
will use later, to refer to this keystore when signing your application.
For more information about Keytool, see the documentation at
https://java.sun.com/j2se/1.5.0/docs/tooldocs/#security
Signing your application
When you are ready to actually sign your .apk for release, you can do so
using the Jarsigner tool. Make sure that you have Jarsigner available on your
machine, as described in
Basic Setup. Also, make sure that
the keystore containing your private key is available.
To sign your application, you run Jarsigner, referencing both the
application's .apk and the keystore containing the private key with which to
sign the .apk. The table below shows the options you could use.
| Jarsigner Option |
Description |
-keystore <keystore-name>.keystore | The name of
the keystore containing your private key. |
-verbose | Enable verbose output. |
-storepass <password> | The password for the
keystore. As a security precaution, do not include this option
in your command line unless you are working at a secure computer.
If not supplied, Jarsigner prompts you to enter the password. In this
way, your password is not stored in your shell history. |
-keypass <password> | The password for the private
key. As a security precaution, do not include this option
in your command line unless you are working at a secure computer.
If not supplied, Jarsigner prompts you to enter the password. In this
way, your password is not stored in your shell history. |
Here's how you would use Jarsigner to sign an application package called
my_application.apk, using the example keystore created above.
$ jarsigner -verbose -keystore my-release-key.keystore
my_application.apk alias_name
Running the example command above, Jarsigner prompts you to provide
passwords for the keystore and key. It then modifies the .apk
in-place, meaning the .apk is now signed. Note that you can sign an
.apk multiple times with different keys.
To verify that your .apk is signed, you can use a command like this:
$ jarsigner -verify my_signed.apk
If the .apk is signed properly, Jarsigner prints "jar verified".
If you want more details, you can try one of these commands:
$ jarsigner -verify -verbose my_application.apk
or
$ jarsigner -verify -verbose -certs my_application.apk
The command above, with the -certs option added, will show you the
"CN=" line that describes who created the key.
Note: If you see "CN=Android Debug", this means the .apk was
signed with the debug key generated by the Android SDK. If you intend to release
your application, you must sign it with your private key instead of the debug
key.
For more information about Jarsigner, see the documentation at
https://java.sun.com/j2se/1.5.0/docs/tooldocs/#security
Compiling and signing with Eclipse ADT
When using Eclipse with ADT, you can use the Export Wizard to
export a signed .apk (and even create a new keystore,
if necessary). The Export Wizard performs all the interaction with
the Keytool and Jarsigner for you, which allows you to perform signing via a
graphical interface instead of the command-line.
Because the Export Wizard uses both Keytool and Jarsigner, you should
ensure that they are accessible on your computer, as described above
in the Basic Setup for Signing.
To create a signed .apk, right-click the project in the Package
Explorer and select Android Tools > Export Signed Application Package.
(Alternatively, open your AndroidManifest.xml file in Eclipse, open
the Overview tab, and click Use the Export Wizard.)
The window that appears will display any errors found while
attempting to export your application. If no errors are found, continue with the
Export Wizard, which will guide you through the process of signing your application,
including steps for selecting the private key with which to sign the .apk,
or creating a new keystore and private key.
When you complete the Export Wizard, you'll
have a signed .apk that's ready for distribution.
Securing Your Private Key
Maintaining the security of your private 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.
If a third party should manage to take your key without your knowledge or
permission, that person could sign and distribute applications that maliciously
replace your authentic applications or corrupt them. Such a person could also
sign and distribute applications under your identity that attack other
applications or the system itself, or corrupt or steal user data.
Your reputation as a developer entity depends on your securing your private
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.
- When you generate your key with Keytool, do not supply the
-storepass and -keypass options at the command line.
If you do so, your passwords will be available in your shell history,
which any user on your computer could access.
- Similarly, when signing your applications with Jarsigner,
do not supply the
-storepass and -keypass
options at the command line.
- 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.
