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> > <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—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\<user>\.android\</code> on Windows XP, and in 262 <code>C:\Users\<user>\.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