diff options
author | Ricardo Cervera <rcervera@google.com> | 2014-08-07 16:00:13 +0000 |
---|---|---|
committer | Android (Google) Code Review <android-gerrit@google.com> | 2014-08-06 23:54:36 +0000 |
commit | edcf7c51676e3b4d0481dcdc9c2e128f7f4f2e5d (patch) | |
tree | b9e5b9c61dc7caf0b33bb32c3d7495f6f0faca7b /docs/html | |
parent | 8e115e6460f5bfe5e682dda6e816b9d8c84bc525 (diff) | |
parent | 7383f1708e9c3a15e63a64c316cbb34f4f863d24 (diff) | |
download | frameworks_base-edcf7c51676e3b4d0481dcdc9c2e128f7f4f2e5d.zip frameworks_base-edcf7c51676e3b4d0481dcdc9c2e128f7f4f2e5d.tar.gz frameworks_base-edcf7c51676e3b4d0481dcdc9c2e128f7f4f2e5d.tar.bz2 |
Merge "docs: Simplify and update the Signing page. Bug: 16296405" into klp-modular-docs
Diffstat (limited to 'docs/html')
-rw-r--r-- | docs/html/images/tools/signadt3.png | bin | 0 -> 34419 bytes | |||
-rw-r--r-- | docs/html/images/tools/signadt4.png | bin | 0 -> 50022 bytes | |||
-rw-r--r-- | docs/html/images/tools/signadt5.png | bin | 0 -> 31228 bytes | |||
-rw-r--r-- | docs/html/images/tools/signstudio1.png | bin | 0 -> 21020 bytes | |||
-rw-r--r-- | docs/html/images/tools/signstudio10.png | bin | 0 -> 30143 bytes | |||
-rw-r--r-- | docs/html/images/tools/signstudio11.png | bin | 0 -> 40485 bytes | |||
-rw-r--r-- | docs/html/images/tools/signstudio2.png | bin | 0 -> 29041 bytes | |||
-rw-r--r-- | docs/html/images/tools/signstudio3.png | bin | 0 -> 18203 bytes | |||
-rw-r--r-- | docs/html/tools/publishing/app-signing.jd | 793 |
9 files changed, 243 insertions, 550 deletions
diff --git a/docs/html/images/tools/signadt3.png b/docs/html/images/tools/signadt3.png Binary files differnew file mode 100644 index 0000000..3f5650b --- /dev/null +++ b/docs/html/images/tools/signadt3.png diff --git a/docs/html/images/tools/signadt4.png b/docs/html/images/tools/signadt4.png Binary files differnew file mode 100644 index 0000000..2adfff0 --- /dev/null +++ b/docs/html/images/tools/signadt4.png diff --git a/docs/html/images/tools/signadt5.png b/docs/html/images/tools/signadt5.png Binary files differnew file mode 100644 index 0000000..e1861e8 --- /dev/null +++ b/docs/html/images/tools/signadt5.png diff --git a/docs/html/images/tools/signstudio1.png b/docs/html/images/tools/signstudio1.png Binary files differnew file mode 100644 index 0000000..374e04f --- /dev/null +++ b/docs/html/images/tools/signstudio1.png diff --git a/docs/html/images/tools/signstudio10.png b/docs/html/images/tools/signstudio10.png Binary files differnew file mode 100644 index 0000000..5b9ae6d --- /dev/null +++ b/docs/html/images/tools/signstudio10.png diff --git a/docs/html/images/tools/signstudio11.png b/docs/html/images/tools/signstudio11.png Binary files differnew file mode 100644 index 0000000..0bf0d51 --- /dev/null +++ b/docs/html/images/tools/signstudio11.png diff --git a/docs/html/images/tools/signstudio2.png b/docs/html/images/tools/signstudio2.png Binary files differnew file mode 100644 index 0000000..5e8e416 --- /dev/null +++ b/docs/html/images/tools/signstudio2.png diff --git a/docs/html/images/tools/signstudio3.png b/docs/html/images/tools/signstudio3.png Binary files differnew file mode 100644 index 0000000..f25bf00 --- /dev/null +++ b/docs/html/images/tools/signstudio3.png diff --git a/docs/html/tools/publishing/app-signing.jd b/docs/html/tools/publishing/app-signing.jd index 1de1fd7..53e6e65 100644 --- a/docs/html/tools/publishing/app-signing.jd +++ b/docs/html/tools/publishing/app-signing.jd @@ -4,33 +4,26 @@ page.title=Signing Your Applications <div id="qv-wrapper"> <div id="qv"> -<h2>Quickview</h2> - -<ul> -<li>All Android apps <em>must</em> be signed</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="#signing">Signing Process</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 Release Mode</a> - <ol> - <li><a href="#cert">Obtain a suitable private key</a></li> - <li><a href="#releasecompile">Compile the application in release mode</a></li> - <li><a href="#signapp">Sign your application with your private key</a></li> - <li><a href="#align">Align the final APK package</a></li> - <li><a href="#ExportWizard">Compile and sign with Eclipse ADT</a></li> - </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> @@ -43,588 +36,288 @@ page.title=Signing Your Applications </div> </div> -<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 Android system uses the -certificate as a means of identifying the author of an application and establishing trust -relationships between applications. The certificate is not used to control 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 -on an emulator or a device if it is not signed.</li> - <li>To test and debug your application, the build tools sign your application with a special debug - key that is created by the Android SDK build tools.</li> - <li>When you are ready to release your application for end-users, you must sign it with a suitable - private key. You cannot publish an application that is signed with the debug key generated - by the SDK tools.</li> - <li>You can use self-signed certificates to sign your applications. No certificate authority is - needed.</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 {@code .apk} files.</li> - <li>After you sign your application for release, we recommend that you use the - <code>zipalign</code> tool to optimize the final APK package.</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 <a href="#setup">set up signing</a> for your application before you can -run it or debug it on an emulator or device.</p> - -<h2 id="signing">Signing Process</h3> - -<p>The Android build process signs your application differently depending on which build mode you -use to build your application. There are two build modes: <em>debug mode</em> and <em>release -mode</em>. You use debug mode when you are developing and testing your application. You use -release mode when you want to build a release version of your application that you can -distribute directly to users or publish on an application marketplace such as Google Play.</p> - -<p>When you build in <em>debug mode</em> the Android SDK build tools use the Keytool utility -(included in the JDK) to create a debug key. Because the SDK build tools created the debug key, -they know the debug key's alias and password. Each time you compile your application in debug mode, -the build tools use the debug key along with the Jarsigner utility (also included in the JDK) to -sign your application's <code>.apk</code> file. Because the alias and password are known to the SDK -build tools, the tools don't need to prompt you for the debug key's alias and password each time -you compile.</p> - -<p>When you build in <em>release mode</em> you use your own private key to sign your application. If -you don't have a private key, you can use the Keytool utility to create one for you. When you -compile your application in release mode, the build tools use your private key along with the -Jarsigner utility to sign your application's <code>.apk</code> file. Because the certificate and -private key you use are your own, you must provide the password for the keystore and key alias.</p> - -<p>The debug signing process happens automatically when you run or debug your application using -Eclipse with the ADT plugin. Debug signing also happens automatically when you use the Ant build -script with the <code>debug</code> option. You can automate the release signing process by using the -Eclipse Export Wizard or by modifying the Ant build script and building with the -<code>release</code> option.</p> - -<h2 id="strategies">Signing Strategies</h2> - -<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> +<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> -<ul> -<li>Application upgrade – As you release updates to your application, you -must continue to sign the updates with the same certificate or set of certificates, -if you want users to be able to upgrade seamlessly to the new version. When -the system is installing an update to an application, it compares the -certificate(s) in the new version with those in the existing version. If the -certificates match exactly, including both the certificate data and order, then -the system allows the update. If you sign the new version without using matching -certificates, you must also 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 requests, 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> +<h2 id="overview">Signing Overview</h2> -<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> +<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> -<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 Google Play, the -key you use to sign the application(s) must have a validity period -ending after 22 October 2033. Google Play enforces this requirement -to ensure that users can seamlessly upgrade applications when -new versions are available. </li> -</ul> +<h3 id="debug-mode">Signing in Debug Mode</h3> -<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> +<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> -<h2 id="setup">Basic Setup for Signing</h2> +<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>Before you begin, make sure that the Keytool utility and Jarsigner utility are available to -the SDK build tools. Both of these tools are available in the JDK. In most cases, you can tell -the SDK build tools how to find these utilities by setting your <code>JAVA_HOME</code> environment -variable so it references a suitable JDK. Alternatively, you can add the JDK version of Keytool and -Jarsigner to your <code>PATH</code> variable.</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>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 <code>PATH</code>, it might be pointing to a symlink at -<code>/usr/bin/keytool</code>. In this case, check the symlink target to be sure it points -to the Keytool in the JDK.</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> -<h2 id="debugmode">Signing in Debug Mode</h2> +<h3 id="release-mode">Signing in Release Mode</h3> -<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 using debug mode to build your app, the SDK tools invoke Keytool to automatically create -a debug keystore and key. This debug key is then used to automatically sign the APK, so -you do not need to sign the package with your own key.</p> +<p>In release mode, you sign your app with your own certificate:</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>If necessary, you can change the location/name of the debug keystore/key or -supply a custom debug keystore/key to use. However, any custom debug -keystore/key must use the same keystore/key names and passwords as the default -debug key (as described above). (To do so in Eclipse/ADT, go to -<strong>Windows</strong> > <strong>Preferences</strong> > -<strong>Android</strong> > <strong>Build</strong>.) </p> - -<p class="caution"><strong>Caution:</strong> You <em>cannot</em> release your application -to the public when signed with the debug 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> -<h3>Eclipse Users</h3> +<p>After you complete this process, you can distribute your app and publish it on Google Play.</p> -<p>If you are developing in Eclipse/ADT (and have set up Keytool and Jarsigner as described above in -<a href="#setup">Basic Setup for Signing</a>), -signing in debug mode is enabled by default. When you run or debug your -application, ADT signs the {@code .apk} file with the debug certificate, runs {@code zipalign} on -the package, then installs it on -the selected emulator or connected device. No specific action on your part is needed, -provided ADT has access to Keytool.</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> -<h3>Ant Users</h3> +<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> -<p>If you are using Ant to build your {@code .apk} file, debug signing mode -is enabled by using the <code>debug</code> option with the <code>ant</code> command -(assuming that you are using a <code>build.xml</code> file generated by the -<code>android</code> tool). When you run <code>ant debug</code> to -compile your app, the build script generates a keystore/key and signs the APK for you. -The script then also aligns the APK with the <code>zipalign</code> tool. -No other action on your part is needed. Read -<a href="{@docRoot}tools/building/building-cmdline.html#DebugMode">Building and Running Apps -on the Command Line</a> for more information.</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> -<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> +<h2 id="studio">Signing Your App in Android Studio</h2> -<p>When the certificate expires, you will get a build error. On Ant builds, the error -looks like this:</p> +<p>To sign your app in release mode in Android Studio, follow these steps:</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> +<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> -<p>In Eclipse/ADT, you will see a similar error in the Android console.</p> +<h3 id="sign-auto">Automatically Signing Your App</h3> -<p>To fix this problem, simply delete the <code>debug.keystore</code> file. -The default storage location for AVDs 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>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>The next time you build, the build tools will regenerate a new keystore and debug key.</p> +<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> -<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="adt">Signing Your App with the ADT Plugin for Eclipse</h2> -<h2 id="releasemode">Signing in Release Mode</h2> +<p>To sign your app in release mode in ADT, follow these steps:</p> -<p>When your application is ready for release to other users, you must:</p> <ol> - <li><a href="#cert">Obtain a suitable private key</a></li> - <li><a href="#releasecompile">Compile the application in release mode</a></li> - <li><a href="#signapp">Sign your application with your private key</a></li> - <li><a href="#align">Align the final APK package</a></li> +<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> -<p>If you are developing in Eclipse with the ADT plugin, you can use the Export Wizard -to perform the compile, sign, and align procedures. The Export Wizard even allows you to -generate a new keystore and private key in the process. So if you use Eclipse, you can -skip to <a href="#ExportWizard">Compile and sign with Eclipse ADT</a>.</p> - +<h2 id="considerations">Signing Considerations</h2> -<h3 id="cert">1. Obtain 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> +<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>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 Google Play, 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> +<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>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"><strong>Warning:</strong> Keep your private key secure. -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> - -<p class="warning"><strong>Warning:</strong> Keep the keystore file you generate with Keytool -in a safe, secure place. You must use the same key to sign future versions of your application. If -you republish your app with a new key, Google Play will consider it a new app. For more information -on settings that must remain constant over the life of your app, see the Android Developer Blog post -<a href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">Things -That Cannot Change</a>.</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>-alias <alias_name></code></td><td>An alias for the key. Only -the first 8 characters of the alias are used.</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>-keysize <size></code></td><td>The size of each generated key -(bits). If not supplied, Keytool uses a default key size of 1024 bits. In -general, we recommend using a key size of 2048 bits or higher. </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>-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. 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>-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>-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. 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 -keysize 2048 -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://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html"> -http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html</a></p> - - - -<h3 id="releasecompile">2. Compile the application in release mode</h3> - -<p>In order to release your application to users, you must compile it in release mode. -In release mode, the compiled application is not signed by default and you will need -to sign it with your private key.</p> - -<p class="caution"><strong>Caution:</strong> -You can not release your application unsigned, or signed with the debug key.</p> - -<h4>With Eclipse</h4> - -<p>To export an <em>unsigned</em> APK from Eclipse, right-click the project in the Package -Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application -Package</strong>. Then specify the file location for the unsigned APK. -(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, select -the <strong>Manifest</strong> tab, and click <strong>Export an unsigned APK</strong>.)</p> - -<p>Note that you can combine the compiling and signing steps with the Export Wizard. See -<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> - -<h4>With Ant</h4> - -<p>If you are using Ant, you can enable release mode by using the <code>release</code> option -with the <code>ant</code> command. For example, if you are running Ant from the -directory containing your {@code build.xml} file, the command would look like this:</p> - -<pre>$ ant release</pre> - -<p>By default, the build script compiles the application APK without signing it. The output file -in your project {@code bin/} will be <code><em><your_project_name></em>-unsigned.apk</code>. -Because the application APK is still unsigned, you must manually sign it with your private -key and then align it using {@code zipalign}.</p> - -<p>However, the Ant build script can also perform the signing -and aligning for you, if you have provided the path to your keystore and the name of -your key alias in the project's {@code ant.properties} file. With this information provided, -the build script will prompt you for your keystore and alias password when you perform -<code>ant release</code>, it will sign the package and then align it. The final output -file in {@code bin/} will instead be -<code><em><your_project_name></em>-release.apk</code>. With these steps -automated for you, you're able to skip the manual procedures below (steps 3 and 4). -To learn how to specify your keystore and alias in the {@code ant.properties} file, -see <a href="{@docRoot}tools/building/building-cmdline.html#ReleaseMode"> -Building and Running Apps on the Command Line</a>.</p> - - - -<h3 id="signapp">3. Sign your application with your private key</h3> - -<p>When you have an application package that is ready to be signed, you can do sign it -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>-sigalg</code></td><td>The name of the signature algorithim to use in signing the APK. -Use the value {@code SHA1withRSA}.</td> -</tr> -<tr> -<td><code>-digestalg</code></td><td>The message digest algorithim to use in processing the entries -of an APK. Use the value {@code SHA1}.</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 -sigalg SHA1withRSA -digestalg SHA1 -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 class="caution"><strong>Caution:</strong> As of JDK 7, the default signing algorithim has -changed, requiring you to specify the signature and digest algorithims ({@code -sigalg} and {@code --digestalg}) when you sign an APK.</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"><strong>Note:</strong> 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://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html"> -http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html</a></p> - +<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> -<h3 id="align">4. Align the final APK package</h3> +<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> -<p>Once you have signed the APK with your private key, run <code>zipalign</code> on the file. -This tool ensures that all uncompressed data starts with a particular byte alignment, -relative to the start of the file. Ensuring alignment at 4-byte boundaries provides -a performance optimization when installed on a device. When aligned, the Android -system is able to read files with {@code mmap()}, even if -they contain binary data with alignment restrictions, rather than copying all -of the data from the package. The benefit is a reduction in the amount of -RAM consumed by the running application.</p> -<p>The <code>zipalign</code> tool is provided with the Android SDK, inside the -<code>tools/</code> directory. To align your signed APK, execute:</p> - -<pre>$ zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre> - -<p>The {@code -v} flag turns on verbose output (optional). {@code 4} is the -byte-alignment (don't use anything other than 4). The first file argument is -your signed {@code .apk} file (the input) and the second file is the destination {@code .apk} file -(the output). If you're overriding an existing APK, add the {@code -f} flag.</p> +<h2 id="secure-key">Securing Your Private Key</h2> -<p class="caution"><strong>Caution:</strong> Your input APK must be signed with your -private key <strong>before</strong> you optimize the package with {@code zipalign}. -If you sign it after using {@code zipalign}, it will undo the alignment.</p> +<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>For more information, read about the -<a href="{@docRoot}tools/help/zipalign.html">zipalign</a> tool. +<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> -<h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3> +<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> -<p>If you are using Eclipse with the ADT plugin, you can use the Export Wizard to -export a <em>signed</em> APK (and even create a new keystore, -if necessary). The Export Wizard performs all the interaction with -the Keytool and Jarsigner for you, which allows you to sign the package using a GUI -instead of performing the manual procedures to compile, sign, -and align, as discussed above. Once the wizard has compiled and signed your package, -it will also perfom package alignment with {@code zipalign}. -Because the Export Wizard uses both Keytool and Jarsigner, you should -ensure that they are accessible on your computer, as described above -in the <a href="#setup">Basic Setup for Signing</a>.</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>To create a signed and aligned APK in Eclipse:</p> +<p>In general, if you follow common-sense precautions when generating, using, and storing +your key, it will remain secure.</p> -<ol> - <li>Select the project in the Package -Explorer and select <strong>File > Export</strong>.</li> - <li>Open the Android folder, select Export Android Application, - and click <strong>Next</strong>. - <p>The Export Android Application wizard now starts, which will - guide you through the process of signing your application, - including steps for selecting the private key with which to sign the APK - (or creating a new keystore and private key).</p> - <li>Complete the Export Wizard and your application will be compiled, - signed, aligned, and ready for distribution.</li> -</ol> +<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> -<h2 id="secure-key">Securing Your Private Key</h2> +<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>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>The next time you build, the build tools will regenerate a new keystore and debug key.</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>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> -<p>Your private key is required for signing all future versions of your application. If you lose or -misplace your key, you will not be able to publish updates to your existing application. 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> +<h2 id="signing-manually">Signing Your App Manually</h2> -<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> -<li>Keep the keystore file containing your private key that you <a href="#cert">generate with the -Keytool</a> in a safe, secure place.</li> -</ul> +<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> -<p>In general, if you follow common-sense precautions when generating, using, -and storing your key, it will remain secure. </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> |