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 system uses the certificate as a means of identifying the author of an application and establishing trust relationships between applications, rather than for controlling 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:
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.
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:
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.
As you design your application, keep these points in mind and make sure to use a suitable certificate to sign your applications.
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.
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.
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 for you and installs it on the emulator. No specific action on your part is needed, provided ADT has access to Keytool.
If you use Ant to build your .apk files, debug signing mode is enabled by default, assuming that you are using a build.xml file generated by the activitycreator tool included in the latest SDK. When you run Ant against build.xml to compile your app, the build script generates a keystore/key and signs the .apk for you. No specific action on your part is needed.
Note that you can not release your application to the public if it is signed only with the debug key.
When your application is ready for release to other users, you must:
The sections below provide information about these steps.
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.
If you are developing in Eclipse/ADT, right-click the project in the Package pane and select Android Tools > Export Application Package. You can then specify the file location for the unsigned .apk. Alternatively, you can follow the "Exporting the unsigned .apk" link in the Manifest Editor overview page.
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.
Note that you can not release your application unsigned, or signed with the debug 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:
If you plan to publish your application(s) on Android Market, note that a validity period ending after 22 October 2033 is a requirement. You can not upload an application if it is signed with a key whose validity expires before that date.
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).
Before you run Keytool, make sure to read Securing Your 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. |
-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 9500 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 9500
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 9500 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 http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security
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 http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security
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:
-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.-storepass and -keypass
options at the command line. In general, if you follow common-sense precautions when generating, using, and storing your key, it will remain secure.
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. On Linux/Mac OSX,
the file is stored in ~/.android. OOn Windows XP, the file is stored in
C:\Documents and Settings\<user>\Local Settings\Application Data\Android.
On Windows Vista, the file is stored in
C:\Users\<user>\AppData\Local\Android.
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.