| page.title=Signing Your Applications |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>In this document</h2> |
| |
| <ol> |
| <li><a href="#overview">Signing Overview</a> |
| <ol> |
| <li><a href="#debug-mode">Signing in Debug Mode</a></li> |
| <li><a href="#release-mode">Signing in Release Mode</a></li> |
| <li><a href="#wear-apps">Signing Android Wear Apps</a></li> |
| </ol> |
| </li> |
| <li><a href="#studio">Signing Your App in Android Studio</a> |
| <ol> |
| <li><a href="sign-auto">Automatically Signing Your App</a></li> |
| </ol> |
| </li> |
| <li><a href="#adt">Signing Your App with the ADT plugin for Eclipse</a></li> |
| <li><a href="#considerations">Signing Considerations</a></li> |
| <li><a href="#secure-key">Securing Your Private Key</a></li> |
| <li><a href="#expdebug">Expiry of the Debug Certificate</a></li> |
| <li><a href="#signing-manually">Signing Your App Manually</a></li> |
| </ol> |
| |
| <h2>See also</h2> |
| |
| <ol> |
| <li><a href="{@docRoot}tools/publishing/versioning.html">Versioning Your Applications</a></li> |
| <li><a href="{@docRoot}tools/publishing/preparing.html">Preparing to Publish</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| |
| <p>Android requires that all apps be digitally signed with a certificate before they can be |
| installed. Android uses this certificate to identify the author of an app, and the certificate |
| does not need to be signed by a certificate authority. Android apps often use self-signed |
| certificates. The app developer holds the certificate's private key.</p> |
| |
| |
| <h2 id="overview">Signing Overview</h2> |
| |
| <p>You can sign an app in debug or release mode. You sign your app in debug mode during development |
| and in release mode when you are ready to distribute your app. The Android SDK generates a |
| certificate to sign apps in debug mode. To sign apps in release mode, you need to generate |
| your own certificate.</p> |
| |
| <h3 id="debug-mode">Signing in Debug Mode</h3> |
| |
| <p>In debug mode, you sign your app with a debug certificate generated by the Android SDK tools. |
| This certificate has a private key with a known password, so you can run and debug your app |
| without typing the password every time you make a change to your project.</p> |
| |
| <p>Android Studio and the ADT plugin for Eclipse sign your app in debug mode automatically when |
| you run or debug your project from the IDE.</p> |
| |
| <p>You can run and debug an app signed in debug mode on the emulator and on devices connected |
| to your development manchine through USB, but you cannot distribute an app signed in debug |
| mode.</p> |
| |
| <p>For more information about how to build and run apps in debug mode, see |
| <a href="{@docRoot}tools/building/index.html">Building and Running</a>.</p> |
| |
| <h3 id="release-mode">Signing in Release Mode</h3> |
| |
| <p>In release mode, you sign your app with your own certificate:</p> |
| |
| <ol> |
| <li><em>Create a keystore.</em> A <strong>keystore</strong> is a binary file that contains a |
| set of private keys. You must keep your keystore in a safe and secure place.</li> |
| <li><em>Create a private key.</em> A <strong>private key</strong> represents the entity to |
| be identified with the app, such as a person or a company.</li> |
| <li><em>Build your project</em>. Generate an unsigned APK for your app.</li> |
| <li><em>Sign your app.</em> Use your private key to generate a signed version of your APK.</li> |
| </ol> |
| |
| <p>After you complete this process, you can distribute your app and publish it on Google Play.</p> |
| |
| <p class="warning"><strong>Warning:</strong> Keep your keystore and private key in a safe and |
| secure place, and ensure that you have secure backups of them. If you publish an app to Google |
| Play and then lose the key with which you signed your app, you will not be able to publish |
| any updates to your app, since you must always sign all versions of your app with the same |
| key.</p> |
| |
| <p>The rest of this document provides detailed instructions about how to generate a private |
| key and sign your apps in release mode with Android Studio and with the ADT plugin for Eclipse.</p> |
| |
| <h3 id="wear-apps">Signing Android Wear Apps</h3> |
| |
| <p>When publishing Android Wear apps, you package the wearable app inside of a handheld app, |
| because users cannot browse and install apps directly on the wearable. Both apps must be signed. |
| For more information on packaging and signing Android Wear apps, see |
| <a href="{@docRoot}training/wearables/apps/packaging.html">Packaging Wearable Apps</a>.</p> |
| |
| |
| <h2 id="studio">Signing Your App in Android Studio</h2> |
| |
| <p>To sign your app in release mode in Android Studio, follow these steps:</p> |
| |
| <ol> |
| <li>On the menu bar, click <strong>Build</strong> > <strong>Generate Signed APK</strong>.</li> |
| <li><p>On the <em>Generate Signed APK Wizard</em> window, click <strong>Create new</strong> to create |
| a new keystore.</p><p>If you already have a keystore, go to step 4.</p></li> |
| <li><p>On the <em>New Key Store</em> window, provide the required information as shown |
| in figure 1.</p><p>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.</p> |
| <img src="{@docRoot}images/tools/signstudio2.png" alt="" |
| width="416" height="364" style="margin-top:15px"/> |
| <p class="img-caption"><strong>Figure 1</strong>. Create a new keystore in Android Studio.</p> |
| </li> |
| <li><p>On the <em>Generate Signed APK Wizard</em> window, select a keystore, a private key, and enter |
| the passwords for both. Then click <strong>Next</strong>.</p> |
| <img src="{@docRoot}images/tools/signstudio1.png" alt="" |
| width="349" height="232" style="margin-top:15px"/> |
| <p class="img-caption"><strong>Figure 2</strong>. Select a private key in Android Studio.</p> |
| </li> |
| <li><p>On the next window, select a destination for the signed APK and click |
| <strong>Finish</strong>.</p> |
| <img src="{@docRoot}images/tools/signstudio3.png" alt="" |
| width="350" height="175" style="margin-top:15px"/> |
| <p class="img-caption"><strong>Figure 3</strong>. Generate a signed APK in Android Studio.</p> |
| </li> |
| </ol> |
| |
| <h3 id="sign-auto">Automatically Signing Your App</h3> |
| |
| <p>In Android Studio, you can configure your project to sign your release APK automatically |
| during the build process:</p> |
| |
| <ol> |
| <li>On the project browser, right click on your app and select <strong>Open Module |
| Settings</strong>.</li> |
| <li>On the <em>Project Structure</em> window, select your app's module under <em>Modules</em>.</li> |
| <li>Click on the <strong>Signing</strong> tab.</li> |
| <li><p>Select your keystore file, enter a name for this signing configuration (as you may create |
| more than one), and enter the required information.</p> |
| <img src="{@docRoot}images/tools/signstudio10.png" alt="" |
| width="623" height="372" style="margin-top:15px"/> |
| <p class="img-caption"><strong>Figure 4</strong>. Create a signing configuration in Android Studio.</p> |
| </li> |
| <li>Click on the <strong>Build Types</strong> tab.</li> |
| <li>Select the <strong>release</strong> build.</li> |
| <li><p>Under <em>Signing Config</em>, select the signing configuration you just created.</p> |
| <img src="{@docRoot}images/tools/signstudio11.png" alt="" |
| width="623" height="372" style="margin-top:15px"/> |
| <p class="img-caption"><strong>Figure 5</strong>. Select a signing configuration in Android Studio.</p> |
| </li> |
| <li>Click <strong>OK</strong>.</li> |
| </ol> |
| |
| <p>You can also specify your signing settings in Gradle configuration files. For more information, |
| see <a href="{@docRoot}sdk/installing/studio-build.html#configureSigning">Signing settings</a>.</p> |
| |
| |
| <h2 id="adt">Signing Your App with the ADT Plugin for Eclipse</h2> |
| |
| <p>To sign your app in release mode in ADT, follow these steps:</p> |
| |
| <ol> |
| <li>Select the project in the Package Explorer and select <strong>File</strong> > |
| <strong>Export</strong>.</li> |
| <li>On the <em>Export</em> window, select <strong>Export Android Application</strong> and click |
| <strong>Next</strong>.</li> |
| <li>On the <em>Export Android Application</em> window, select the project you want to sign and |
| click <strong>Next</strong>.</li> |
| <li> |
| <p>On the next window, enter the location to create a keystore and a keystore password. If you |
| already have a keystore, select <strong>Use existing keystore</strong>, enter your keystore's |
| location and password, and go to step 6.</p> |
| <img src="{@docRoot}images/tools/signadt3.png" alt="" |
| width="488" height="270" style="margin-top:15px"/> |
| <p class="img-caption"><strong>Figure 6</strong>. Select a keystore in ADT.</p> |
| </li> |
| <li><p>On the next window, provide the required information as shown in figure 5.<p> |
| <p>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.</p> |
| <img src="{@docRoot}images/tools/signadt4.png" alt="" |
| width="488" height="448" style="margin-top:15px"/> |
| <p class="img-caption"><strong>Figure 7</strong>. Create a private key in ADT.</p> |
| </li> |
| <li><p>On the next window, select the location to export the signed APK.</p> |
| <img src="{@docRoot}images/tools/signadt5.png" alt="" |
| width="488" height="217" style="margin-top:15px"/> |
| <p class="img-caption"><strong>Figure 8</strong>. Export the signed APK in ADT.</p> |
| </li> |
| </ol> |
| |
| |
| <h2 id="considerations">Signing Considerations</h2> |
| |
| <p>You should sign all of your apps with the same certificate throughout the expected lifespan |
| of your applications. There are several reasons why you should do so:</p> |
| |
| <ul> |
| <li>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 application—in this case, the user installs the new version as |
| a completely new application.</li> |
| <li>App modularity: Android allows apps 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 app in modules, and users can update each of the modules independently.</li> |
| <li>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 apps with the same certificate and using |
| signature-based permissions checks, your apps can share code and data in a secure manner.</li> |
| </ul> |
| |
| <p>If you plan to support upgrades for an app, ensure that your 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 application.</p> |
| |
| <p>If you plan to publish your apps on Google Play, the key you use to sign these apps 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.</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 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.</p> |
| |
| <p>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 appn. You cannot |
| regenerate a previously generated key.</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>Do not give or lend anyone your private key, and do not let unauthorized persons know your |
| keystore and key passwords.</li> |
| <li>Keep the keystore file containing your private key in a safe, secure place.</li> |
| </ul> |
| |
| <p>In general, if you follow common-sense precautions when generating, using, and storing |
| your key, it will remain secure.</p> |
| |
| |
| <h2 id="expdebug">Expiry of the Debug Certificate</h2> |
| |
| <p>The self-signed certificate used to sign your application in debug mode has an expiration date |
| of 365 days from its creation date. When the certificate expires, you will get a build error.</p> |
| |
| <p>To fix this problem, simply delete the <code>debug.keystore</code> file. The default storage |
| location is in <code>~/.android/</code> on OS X and Linux, in <code>C:\Documents and |
| Settings\<user>\.android\</code> on Windows XP, and in |
| <code>C:\Users\<user>\.android\</code> on Windows Vista and Windows 7.</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}resources/faq/troubleshooting.html#signingcalendar">I can't compile my app |
| because the build tools generated an expired debug certificate</a>.</p> |
| |
| |
| <h2 id="signing-manually">Signing Your App Manually</h2> |
| |
| <p>You do not need Android Studio or the ADT plugin for Eclipse to sign your app. You can sign |
| your app from the command line using standard tools from the Android SDK and the JDK. To sign |
| an app in release mode from the command line:</p> |
| |
| <ol> |
| <li> |
| <p>Generate a private key using |
| <code><a href="http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html">keytool</a></code>. |
| For example:</p> |
| <pre> |
| $ keytool -genkey -v -keystore my-release-key.keystore |
| -alias alias_name -keyalg RSA -keysize 2048 -validity 10000 |
| </pre> |
| <p>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 |
| <code>my-release-key.keystore</code>. The keystore contains a single key, valid for 10000 days. |
| The alias is a name that you will use later when signing your app.</p> |
| </li> |
| <li style="margin-top:18px"> |
| <p>Compile your app in release mode to obtain an unsigned APK.</p> |
| </li> |
| <li style="margin-top:18px"> |
| <p>Sign your app with your private key using |
| <code><a href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html">jarsigner</a></code>: |
| </p> |
| <pre> |
| $ jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 |
| -keystore my-release-key.keystore my_application.apk alias_name |
| </pre> |
| <p>This example prompts you for passwords for the keystore and key. It then modifies the APK |
| in-place to sign it. Note that you can sign an APK multiple times with different keys.</p> |
| </li> |
| <li style="margin-top:18px"> |
| <p>Verify that your APK is signed. For example:</p> |
| <pre> |
| $ jarsigner -verify -verbose -certs my_application.apk |
| </pre> |
| </li> |
| <li style="margin-top:18px"> |
| <p>Align the final APK package using |
| <code><a href="{@docRoot}tools/help/zipalign.html">zipalign</a></code>.</p> |
| <pre> |
| $ zipalign -v 4 your_project_name-unaligned.apk your_project_name.apk |
| </pre> |
| <p><code>zipalign</code> ensures that all uncompressed data starts with a particular byte |
| alignment relative to the start of the file, which reduces the amount of RAM consumed by an |
| app.</p> |
| </li> |
| </ol> |