| page.title=Signing Your Applications |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>Signing quickview</h2> |
| |
| <ul> |
| <li>All Android apps <em>must</em> be signed</a></li> |
| <li>You can sign with a self-signed key</li> |
| <li>How you sign your apps is critical — read this document carefully</li> |
| <li>Determine your signing strategy early in the development process</li> |
| </ul> |
| |
| <h2>In this document</h2> |
| |
| <ol> |
| <li><a href="#overview">Overview</a></li> |
| <li><a href="#strategies">Signing Strategies</a></li> |
| <li><a href="#setup">Basic Setup for Signing</a></li> |
| <li><a href="#debugmode">Signing in Debug Mode</a></li> |
| <li><a href="#releasemode">Signing for Public Release</a> |
| <ol> |
| <li><a href="#releasecompile">Compiling for Release</a></li> |
| <li><a href="#cert">Obtaining a Suitable Private Key</a></li> |
| <li><a href="#signapp">Signing Your Application</a></li> |
| </ol> |
| </li> |
| <li><a href="#secure-key">Securing Your Private Key</a></li> |
| |
| </ol> |
| |
| <h2>See also</h2> |
| |
| <ol> |
| <li><a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a></li> |
| <li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| <p>This document provides information about signing your Android applications prior to publishing them for mobile device users.</p> |
| |
| <h2 id="overview">Overview</h2> |
| |
| <p>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.</p> |
| |
| <p>The important points to understand about signing Android applications are:</p> |
| |
| <ul> |
| <li>All applications <em>must</em> be signed. The system will not install an application |
| that is not signed.</li> |
| <li>You can use self-signed certificates to sign your applications. No certificate authority |
| is needed.</li> |
| <li>When you are ready to publish your application, you must sign it with a suitable private |
| key. You can not publish an application that is signed with the default key generated |
| by the SDK tools. |
| </li> |
| <li>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.</li> |
| <li>You can use standard tools — Keytool and Jarsigner — to generate keys and |
| sign your application .apk files.</li> |
| </ul> |
| |
| <p>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.</p> |
| |
| <p>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. |
| |
| <ul> |
| <li>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.</li> |
| |
| <li>When your application is ready for release, you compile it in release signing mode. |
| In this mode, the tools compile your .apk <em>without</em> signing it. You must then sign |
| the .apk manually — <span style="color:red">with your private key</span> — |
| 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.</li> |
| </ul> |
| |
| <h2 id="strategies">Signing Strategies</h3> |
| |
| <p>Some aspects of application signing may affect how you approach the development |
| of your application, especially if you are planning to release multiple |
| applications. </p> |
| |
| <p>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: </p> |
| |
| <ul> |
| <li>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. </li> |
| |
| <li>Application modularity — The Android system allows applications that |
| are signed by the same certificate to run in the same process, if the |
| applications so request, 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.</li> |
| |
| <li>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. </li> |
| |
| </ul> |
| |
| <p>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.</p> |
| |
| <ul> |
| <li>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.</li> |
| |
| <li>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 <em>all versions of all of the applications</em>, including |
| dependent applications that may be added to the suite in the future. </li> |
| |
| <li>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. </li> |
| </ul> |
| |
| <p>As you design your application, keep these points in mind and make sure to |
| use a <a href="#cert">suitable certificate</a> to sign your applications. </p> |
| |
| <h2 id="setup">Basic Setup for Signing</h2> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>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. </p> |
| |
| <h2 id="debugmode">Signing in Debug Mode</h2> |
| |
| <p>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. </p> |
| |
| <p>The SDK tools create the debug keystore/key with predetermined names/passwords;</p> |
| <ul> |
| <li>Keystore name — "debug.keystore"</li> |
| <li>Keystore password — "android"</li> |
| <li>Key alias — "androiddebugkey"</li> |
| <li>Key password — "android"</li> |
| <li>CN — "CN=Android Debug,O=Android,C=US"</li> |
| </ul></p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>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 |
| <strong>Windows</strong> > <strong>Prefs</strong> > |
| <strong>Android</strong> > <strong>Build</strong>. However, any custom debug |
| keystore/key must use the same keystore/key names and passwords as the default |
| debug key (as described above). </p> |
| |
| <p>Note that you <em>cannot</em> release your application to the public if it |
| is signed with the debug certificate. </p> |
| |
| <h3 id="debugexpiry">Expiry of the Debug Certificate</h3> |
| |
| <p>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.</p> |
| |
| <p>When the certificate expires, you will get a build error. On Ant builds, the error |
| looks like this:</p> |
| |
| <pre>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</pre> |
| |
| <p>In Eclipse/ADT, you will see a similar error in the Android console.</p> |
| |
| <p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, |
| the file is stored in <code>~/.android</code>. On Windows XP, the file is stored in <code> |
| C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. |
| On Windows Vista, the file is stored in <code> |
| C:\Users\<user>\AppData\Local\Android</code>.</p> |
| |
| <p>The next time you build, the build tools will regenerate a new keystore and debug key.</p> |
| |
| <p>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 <a href="{@docRoot}guide/appendix/faq/troubleshooting.html#signingcalendar"> |
| I can't compile my app because the build tools generated an expired debug |
| certificate</a>. </p> |
| |
| <h2 id="releasemode">Signing for Public Release</h2> |
| |
| <p>When your application is ready for release to other users, you must:</p> |
| <ol> |
| <li>Compile the application in release mode</li> |
| <li>Obtain a suitable private key, and then</li> |
| <li>Sign the application with your private key</li> |
| <li>Secure your private key</li> |
| </ol> |
| |
| <p>The sections below provide information about these steps. </p> |
| |
| <h3 id="releasecompile">Compiling for Release</h3> |
| |
| <p>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. </p> |
| |
| <p>If you are developing in Eclipse/ADT, right-click the project in the Package |
| pane and select <strong>Android Tools</strong> > <strong>Export Application |
| Package</strong>. 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. </p> |
| |
| <p>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:</p> |
| |
| <pre>$ ant release</pre> |
| |
| <p>The build script compiles the application .apk without signing it. |
| |
| <p>Note that you can not release your application unsigned, or signed with the debug key.</p> |
| |
| <h3 id="cert">Obtaining a Suitable Private Key</h3> |
| |
| <p>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:</p> |
| |
| <ul> |
| <li>Is in your possession</li> |
| <li>Represents the personal, corporate, or organizational entity to be identified |
| with the application</li> |
| <li>Has a validity period that exceeds the expected lifespan of the application |
| or application suite. A validity period of more than 25 years is recommended. |
| <p>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. |
| </p></li> |
| <li>Is not the debug key generated by the Android SDK tools. </li> |
| </ul> |
| |
| <p>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 <a href="#setup">Basic Setup</a>.</p> |
| |
| <p>To generate a self-signed key with Keytool, use the <code>keytool</code> |
| command and pass any of the options listed below (and any others, as |
| needed). </p> |
| |
| <p class="warning">Before you run Keytool, make sure to read |
| <a href="#secure-key">Securing Your Private Key</a> 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.</p> |
| |
| <table> |
| <tr> |
| <th>Keytool Option</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td><code>-genkey</code></td><td>Generate a key pair (public and private |
| keys)</td> |
| </tr> |
| <tr> |
| <td><code>-v</code></td><td>Enable verbose output.</td> |
| </tr> |
| <tr> |
| <td><code>-keystore <keystore-name>.keystore</code></td><td>A name |
| for the keystore containing the private key.</td> |
| </tr> |
| <tr> |
| <td><code>-storepass <password></code></td><td><p>A password for the |
| keystore.</p><p>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.</p></td> |
| </tr> |
| <tr> |
| <td><code>-alias <alias_name></code></td><td>An alias for the key.</td> |
| </tr> |
| <tr> |
| <td><code>-keyalg <alg></code></td><td>The encryption algorithm to use |
| when generating the key. Both DSA and RSA are supported.</td> |
| </tr> |
| <tr> |
| <td><code>-dname <name></code></td><td><p>A Distinguished Name that describes |
| who created the key. The value is used as the issuer and subject fields in the |
| self-signed certificate. </p><p>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).</p></td> |
| </tr> |
| <tr> |
| <td><code>-validity <valdays></code></td><td><p>The validity period for the |
| key, in days. </p><p><strong>Note:</strong> A value of 10000 or greater is recommended.</p></td> |
| </tr> |
| <tr> |
| <td><code>-keypass <password></code></td><td><p>The password for the key.</p> |
| <p>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.</p></td> |
| </tr> |
| </table> |
| |
| |
| <p>Here's an example of a Keytool command that generates a private key:</p> |
| |
| <pre>$ keytool -genkey -v -keystore my-release-key.keystore |
| -alias alias_name -keyalg RSA -validity 10000</pre> |
| |
| <p>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 |
| <code>my-release-key.keystore</code>. 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. </p> |
| |
| <p>For more information about Keytool, see the documentation at |
| <a |
| href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> |
| http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> |
| |
| <h3 id="signapp">Signing Your Application</h3> |
| |
| <p>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 <a href="#setup">Basic Setup</a>. Also, make sure that |
| the keystore containing your private key is available.</p> |
| |
| <p>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. <p> |
| |
| <table> |
| <tr> |
| <th>Jarsigner Option</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td><code>-keystore <keystore-name>.keystore</code></td><td>The name of |
| the keystore containing your private key.</td> |
| </tr> |
| <tr> |
| <td><code>-verbose</code></td><td>Enable verbose output.</td> |
| </tr> |
| <tr> |
| <td><code>-storepass <password></code></td><td><p>The password for the |
| keystore. </p><p>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.</p></td> |
| </tr> |
| <tr> |
| <td><code>-keypass <password></code></td><td><p>The password for the private |
| key. </p><p>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.</p></td> |
| </tr> |
| </table> |
| |
| <p>Here's how you would use Jarsigner to sign an application package called |
| <code>my_application.apk</code>, using the example keystore created above. |
| </p> |
| |
| <pre>$ jarsigner -verbose -keystore my-release-key.keystore |
| my_application.apk alias_name</pre> |
| |
| <p>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.</p> |
| |
| <p>To verify that your .apk is signed, you can use a command like this:</p> |
| |
| <pre>$ jarsigner -verify my_signed.apk</pre> |
| |
| <p>If the .apk is signed properly, Jarsigner prints "jar verified". |
| If you want more details, you can try one of these commands:</p> |
| |
| <pre>$ jarsigner -verify -verbose my_application.apk</pre> |
| |
| <p>or</p> |
| |
| <pre>$ jarsigner -verify -verbose -certs my_application.apk</pre> |
| |
| <p>The command above, with the <code>-certs</code> option added, will show you the |
| "CN=" line that describes who created the key.</p> |
| |
| <p class="note">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.</p> |
| |
| <p>For more information about Jarsigner, see the documentation at |
| <a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> |
| http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> |
| |
| <h2 id="secure-key">Securing Your Private Key</h2> |
| |
| <p>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. </p> |
| |
| <p>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. </p> |
| |
| <p>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: </p> |
| |
| <ul> |
| <li>Select strong passwords for the keystore and key.</li> |
| <li>When you generate your key with Keytool, <em>do not</em> supply the |
| <code>-storepass</code> and <code>-keypass</code> 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.</li> |
| <li>Similarly, when signing your applications with Jarsigner, |
| <em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code> |
| options at the command line. </li> |
| <li>Do not give or lend anyone your private key, and do not let unauthorized |
| persons know your keystore and key passwords.</li> |
| </ul> |
| |
| <p>In general, if you follow common-sense precautions when generating, using, |
| and storing your key, it will remain secure. </p> |