Home | History | Annotate | Download | only in publishing
      1 page.title=Signing Your Applications
      2 @jd:body
      3 
      4 <div id="qv-wrapper">
      5 <div id="qv">
      6 
      7 <h2>In this document</h2>
      8 
      9 <ol>
     10 <li><a href="#overview">Signing Overview</a>
     11   <ol>
     12   	<li><a href="#debug-mode">Signing in Debug Mode</a></li>
     13   	<li><a href="#release-mode">Signing in Release Mode</a></li>
     14   	<li><a href="#wear-apps">Signing Android Wear Apps</a></li>
     15   </ol>
     16 </li>
     17 <li><a href="#studio">Signing Your App in Android Studio</a>
     18   <ol>
     19   	<li><a href="sign-auto">Automatically Signing Your App</a></li>
     20   </ol>
     21 </li>
     22 <li><a href="#adt">Signing Your App with the ADT plugin for Eclipse</a></li>
     23 <li><a href="#considerations">Signing Considerations</a></li>
     24 <li><a href="#secure-key">Securing Your Private Key</a></li>
     25 <li><a href="#expdebug">Expiry of the Debug Certificate</a></li>
     26 <li><a href="#signing-manually">Signing Your App Manually</a></li>
     27 </ol>
     28 
     29 <h2>See also</h2>
     30 
     31 <ol>
     32 <li><a href="{@docRoot}tools/publishing/versioning.html">Versioning Your Applications</a></li>
     33 <li><a href="{@docRoot}tools/publishing/preparing.html">Preparing to Publish</a></li>
     34 </ol>
     35 
     36 </div>
     37 </div>
     38 
     39 
     40 <p>Android requires that all apps be digitally signed with a certificate before they can be
     41 installed. Android uses this certificate to identify the author of an app, and the certificate
     42 does not need to be signed by a certificate authority. Android apps often use self-signed
     43 certificates. The app developer holds the certificate's private key.</p>
     44 
     45 
     46 <h2 id="overview">Signing Overview</h2>
     47 
     48 <p>You can sign an app in debug or release mode. You sign your app in debug mode during development
     49 and in release mode when you are ready to distribute your app. The Android SDK generates a
     50 certificate to sign apps in debug mode. To sign apps in release mode, you need to generate
     51 your own certificate.</p>
     52 
     53 <h3 id="debug-mode">Signing in Debug Mode</h3>
     54 
     55 <p>In debug mode, you sign your app with a debug certificate generated by the Android SDK tools.
     56 This certificate has a private key with a known password, so you can run and debug your app
     57 without typing the password every time you make a change to your project.</p>
     58 
     59 <p>Android Studio and the ADT plugin for Eclipse sign your app in debug mode automatically when
     60 you run or debug your project from the IDE.</p>
     61 
     62 <p>You can run and debug an app signed in debug mode on the emulator and on devices connected
     63 to your development manchine through USB, but you cannot distribute an app signed in debug
     64 mode.</p>
     65 
     66 <p>For more information about how to build and run apps in debug mode, see
     67 <a href="{@docRoot}tools/building/index.html">Building and Running</a>.</p>
     68 
     69 <h3 id="release-mode">Signing in Release Mode</h3>
     70 
     71 <p>In release mode, you sign your app with your own certificate:</p>
     72 
     73 <ol>
     74 <li><em>Create a keystore.</em> A <strong>keystore</strong> is a binary file that contains a
     75 set of private keys. You must keep your keystore in a safe and secure place.</li>
     76 <li><em>Create a private key.</em> A <strong>private key</strong> represents the entity to
     77 be identified with the app, such as a person or a company.</li>
     78 <li><em>Build your project</em>. Generate an unsigned APK for your app.</li>
     79 <li><em>Sign your app.</em> Use your private key to generate a signed version of your APK.</li>
     80 </ol>
     81 
     82 <p>After you complete this process, you can distribute your app and publish it on Google Play.</p>
     83 
     84 <p class="warning"><strong>Warning:</strong> Keep your keystore and private key in a safe and
     85 secure place, and ensure that you have secure backups of them. If you publish an app to Google
     86 Play and then lose the key with which you signed your app, you will not be able to publish
     87 any updates to your app, since you must always sign all versions of your app with the same
     88 key.</p>
     89 
     90 <p>The rest of this document provides detailed instructions about how to generate a private
     91 key and sign your apps in release mode with Android Studio and with the ADT plugin for Eclipse.</p>
     92 
     93 <h3 id="wear-apps">Signing Android Wear Apps</h3>
     94 
     95 <p>When publishing Android Wear apps, you package the wearable app inside of a handheld app,
     96 because users cannot browse and install apps directly on the wearable. Both apps must be signed.
     97 For more information on packaging and signing Android Wear apps, see
     98 <a href="{@docRoot}training/wearables/apps/packaging.html">Packaging Wearable Apps</a>.</p>
     99 
    100 
    101 <h2 id="studio">Signing Your App in Android Studio</h2>
    102 
    103 <p>To sign your app in release mode in Android Studio, follow these steps:</p>
    104 
    105 <ol>
    106 <li>On the menu bar, click <strong>Build</strong> &gt; <strong>Generate Signed APK</strong>.</li>
    107 <li><p>On the <em>Generate Signed APK Wizard</em> window, click <strong>Create new</strong> to create
    108 a new keystore.</p><p>If you already have a keystore, go to step 4.</p></li>
    109 <li><p>On the <em>New Key Store</em> window, provide the required information as shown
    110 in figure 1.</p><p>Your key should be valid for at least 25 years, so you can sign app updates
    111 with the same key through the lifespan of your app.</p>
    112 <img src="{@docRoot}images/tools/signstudio2.png" alt=""
    113      width="416" height="364" style="margin-top:15px"/>
    114 <p class="img-caption"><strong>Figure 1</strong>. Create a new keystore in Android Studio.</p>
    115 </li>
    116 <li><p>On the <em>Generate Signed APK Wizard</em> window, select a keystore, a private key, and enter
    117 the passwords for both. Then click <strong>Next</strong>.</p>
    118 <img src="{@docRoot}images/tools/signstudio1.png" alt=""
    119      width="349" height="232" style="margin-top:15px"/>
    120 <p class="img-caption"><strong>Figure 2</strong>. Select a private key in Android Studio.</p>
    121 </li>
    122 <li><p>On the next window, select a destination for the signed APK and click
    123 <strong>Finish</strong>.</p>
    124 <img src="{@docRoot}images/tools/signstudio3.png" alt=""
    125      width="350" height="175" style="margin-top:15px"/>
    126 <p class="img-caption"><strong>Figure 3</strong>. Generate a signed APK in Android Studio.</p>
    127 </li>
    128 </ol>
    129 
    130 <h3 id="sign-auto">Automatically Signing Your App</h3>
    131 
    132 <p>In Android Studio, you can configure your project to sign your release APK automatically
    133 during the build process:</p>
    134 
    135 <ol>
    136 <li>On the project browser, right click on your app and select <strong>Open Module
    137 Settings</strong>.</li>
    138 <li>On the <em>Project Structure</em> window, select your app's module under <em>Modules</em>.</li>
    139 <li>Click on the <strong>Signing</strong> tab.</li>
    140 <li><p>Select your keystore file, enter a name for this signing configuration (as you may create
    141 more than one), and enter the required information.</p>
    142 <img src="{@docRoot}images/tools/signstudio10.png" alt=""
    143      width="623" height="372" style="margin-top:15px"/>
    144 <p class="img-caption"><strong>Figure 4</strong>. Create a signing configuration in Android Studio.</p>
    145 </li>
    146 <li>Click on the <strong>Build Types</strong> tab.</li>
    147 <li>Select the <strong>release</strong> build.</li>
    148 <li><p>Under <em>Signing Config</em>, select the signing configuration you just created.</p>
    149 <img src="{@docRoot}images/tools/signstudio11.png" alt=""
    150      width="623" height="372" style="margin-top:15px"/>
    151 <p class="img-caption"><strong>Figure 5</strong>. Select a signing configuration in Android Studio.</p>
    152 </li>
    153 <li>Click <strong>OK</strong>.</li>
    154 </ol>
    155 
    156 <p>You can also specify your signing settings in Gradle configuration files. For more information,
    157 see <a href="{@docRoot}sdk/installing/studio-build.html#configureSigning">Signing settings</a>.</p>
    158 
    159 
    160 <h2 id="adt">Signing Your App with the ADT Plugin for Eclipse</h2>
    161 
    162 <p>To sign your app in release mode in ADT, follow these steps:</p>
    163 
    164 <ol>
    165 <li>Select the project in the Package Explorer and select <strong>File</strong> >
    166 <strong>Export</strong>.</li>
    167 <li>On the <em>Export</em> window, select <strong>Export Android Application</strong> and click
    168 <strong>Next</strong>.</li>
    169 <li>On the <em>Export Android Application</em> window, select the project you want to sign and
    170 click <strong>Next</strong>.</li>
    171 <li>
    172 <p>On the next window, enter the location to create a keystore and a keystore password. If you
    173 already have a keystore, select <strong>Use existing keystore</strong>, enter your keystore's
    174 location and password, and go to step 6.</p>
    175 <img src="{@docRoot}images/tools/signadt3.png" alt=""
    176      width="488" height="270" style="margin-top:15px"/>
    177 <p class="img-caption"><strong>Figure 6</strong>. Select a keystore in ADT.</p>
    178 </li>
    179 <li><p>On the next window, provide the required information as shown in figure 5.<p>
    180 <p>Your key should be valid for at least 25 years, so you can sign app updates with the same key
    181 through the lifespan of your app.</p>
    182 <img src="{@docRoot}images/tools/signadt4.png" alt=""
    183      width="488" height="448" style="margin-top:15px"/>
    184 <p class="img-caption"><strong>Figure 7</strong>. Create a private key in ADT.</p>
    185 </li>
    186 <li><p>On the next window, select the location to export the signed APK.</p>
    187 <img src="{@docRoot}images/tools/signadt5.png" alt=""
    188      width="488" height="217" style="margin-top:15px"/>
    189 <p class="img-caption"><strong>Figure 8</strong>. Export the signed APK in ADT.</p>
    190 </li>
    191 </ol>
    192 
    193 
    194 <h2 id="considerations">Signing Considerations</h2>
    195 
    196 <p>You should sign all of your apps with the same certificate throughout the expected lifespan
    197 of your applications. There are several reasons why you should do so:</p>
    198 
    199 <ul>
    200 <li>App upgrade: When the system is installing an update to an app, it compares the certificate(s)
    201 in the new version with those in the existing version. The system allows the update if the
    202 certificates match. If you sign the new version with a different certificate, you must assign a
    203 different package name to the application&mdash;in this case, the user installs the new version as
    204 a completely new application.</li>
    205 <li>App modularity: Android allows apps signed by the same certificate to run in the same process,
    206 if the applications so requests, so that the system treats them as a single application. In this
    207 way you can deploy your app in modules, and users can update each of the modules independently.</li>
    208 <li>Code/data sharing through permissions: Android provides signature-based permissions
    209 enforcement, so that an app can expose functionality to another app that is signed with a
    210 specified certificate. By signing multiple apps with the same certificate and using
    211 signature-based permissions checks, your apps can share code and data in a secure manner.</li>
    212 </ul>
    213 
    214 <p>If you plan to support upgrades for an app, ensure that your key has a validity
    215 period that exceeds the expected lifespan of that app. A validity period of 25 years or more is
    216 recommended. When your key's validity period expires, users will no longer be able to seamlessly
    217 upgrade to new versions of your application.</p>
    218 
    219 <p>If you plan to publish your apps on Google Play, the key you use to sign these apps must have
    220 a validity period ending after 22 October 2033. Google Play enforces this requirement to ensure
    221 that users can seamlessly upgrade apps when new versions are available.</p>
    222 
    223 
    224 <h2 id="secure-key">Securing Your Private Key</h2>
    225 
    226 <p>Maintaining the security of your private key is of critical importance, both to you and to
    227 the user. If you allow someone to use your key, or if you leave your keystore and passwords in
    228 an unsecured location such that a third-party could find and use them, your authoring identity
    229 and the trust of the user are compromised.</p>
    230 
    231 <p>If a third party should manage to take your key without your knowledge or permission, that
    232 person could sign and distribute apps that maliciously replace your authentic apps or corrupt
    233 them. Such a person could also sign and distribute apps under your identity that attack
    234 other apps or the system itself, or corrupt or steal user data.</p>
    235 
    236 <p>Your private key is required for signing all future versions of your app. If you lose or
    237 misplace your key, you will not be able to publish updates to your existing appn. You cannot
    238 regenerate a previously generated key.</p>
    239 
    240 <p>Your reputation as a developer entity depends on your securing your private key properly, at
    241 all times, until the key is expired. Here are some tips for keeping your key secure:</p>
    242 
    243 <ul>
    244 <li>Select strong passwords for the keystore and key.</li>
    245 <li>Do not give or lend anyone your private key, and do not let unauthorized persons know your
    246 keystore and key passwords.</li>
    247 <li>Keep the keystore file containing your private key in a safe, secure place.</li>
    248 </ul>
    249 
    250 <p>In general, if you follow common-sense precautions when generating, using, and storing
    251 your key, it will remain secure.</p>
    252 
    253 
    254 <h2 id="expdebug">Expiry of the Debug Certificate</h2>
    255 
    256 <p>The self-signed certificate used to sign your application in debug mode has an expiration date
    257 of 365 days from its creation date. When the certificate expires, you will get a build error.</p>
    258 
    259 <p>To fix this problem, simply delete the <code>debug.keystore</code> file. The default storage
    260 location is in <code>~/.android/</code> on OS X and Linux, in <code>C:\Documents and
    261 Settings\&lt;user&gt;\.android\</code> on Windows XP, and in
    262 <code>C:\Users\&lt;user&gt;\.android\</code> on Windows Vista and Windows 7.</p>
    263 
    264 <p>The next time you build, the build tools will regenerate a new keystore and debug key.</p>
    265 
    266 <p>Note that, if your development machine is using a non-Gregorian locale, the build tools may
    267 erroneously generate an already-expired debug certificate, so that you get an error when trying
    268 to compile your application. For workaround information, see the troubleshooting topic
    269 <a href="{@docRoot}resources/faq/troubleshooting.html#signingcalendar">I can't compile my app
    270 because the build tools generated an expired debug certificate</a>.</p>
    271 
    272 
    273 <h2 id="signing-manually">Signing Your App Manually</h2>
    274 
    275 <p>You do not need Android Studio or the ADT plugin for Eclipse to sign your app. You can sign
    276 your app from the command line using standard tools from the Android SDK and the JDK. To sign
    277 an app in release mode from the command line:</p>
    278 
    279 <ol>
    280 <li>
    281   <p>Generate a private key using
    282   <code><a href="http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html">keytool</a></code>.
    283   For example:</p>
    284 <pre>
    285 $ keytool -genkey -v -keystore my-release-key.keystore
    286 -alias alias_name -keyalg RSA -keysize 2048 -validity 10000
    287 </pre>
    288   <p>This example prompts you for passwords for the keystore and key, and to provide the
    289   Distinguished Name fields for your key. It then generates the keystore as a file called
    290   <code>my-release-key.keystore</code>. The keystore contains a single key, valid for 10000 days.
    291   The alias is a name that you will use later when signing your app.</p>
    292 </li>
    293 <li style="margin-top:18px">
    294   <p>Compile your app in release mode to obtain an unsigned APK.</p>
    295 </li>
    296 <li style="margin-top:18px">
    297   <p>Sign your app with your private key using
    298   <code><a href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html">jarsigner</a></code>:
    299   </p>
    300 <pre>
    301 $ jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1
    302 -keystore my-release-key.keystore my_application.apk alias_name
    303 </pre>
    304   <p>This example prompts you for passwords for the keystore and key. It then modifies the APK
    305   in-place to sign it. Note that you can sign an APK multiple times with different keys.</p>
    306 </li>
    307 <li style="margin-top:18px">
    308   <p>Verify that your APK is signed. For example:</p>
    309 <pre>
    310 $ jarsigner -verify -verbose -certs my_application.apk
    311 </pre>
    312 </li>
    313 <li style="margin-top:18px">
    314   <p>Align the final APK package using
    315   <code><a href="{@docRoot}tools/help/zipalign.html">zipalign</a></code>.</p>
    316 <pre>
    317 $ zipalign -v 4 your_project_name-unaligned.apk your_project_name.apk
    318 </pre>
    319   <p><code>zipalign</code> ensures that all uncompressed data starts with a particular byte
    320   alignment relative to the start of the file, which reduces the amount of RAM consumed by an
    321   app.</p>
    322 </li>
    323 </ol>
    324