AI 147219: update app-signing doc to include a guide to export a signed APK from ADT

<li><a href="#debugmode">Signing in Debug Mode</a></li>

<li><a href="#releasemode">Signing for Public Release</a>

    <ol>

    <li><a href="#releasecompile">Compiling for Release</a></li>

    <li><a href="#cert">Obtaining a Suitable Private Key</a></li>

    <li><a href="#signapp">Signing Your Application</a></li>

    <li><a href="#releasecompile">Compiling for release</a></li>

    <li><a href="#cert">Obtaining a suitable private key</a></li>

    <li><a href="#signapp">Signing your application</a></li>

    <li><a href="#ExportWizard">Compiling and signing with Eclipse ADT</a></li>

    </ol>

</li>

<li><a href="#secure-key">Securing Your Private Key</a></li>

<p>The Android system requires that all installed applications be digitally

signed with a certificate whose private key is held by the application's

developer. The system uses the certificate as a means of identifying the author of

an application and establishing trust relationships between applications, rather

than for controlling which applications the user can install. The certificate

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>

that is not signed.</li>

  <li>You can use self-signed certificates to sign your applications. No certificate authority 

is needed.</li>

  <li>When you are ready to publish your application, you must sign it with a suitable private 

key. You can not publish an application that is signed with the default key generated 

  <li>When you are ready to release your application for end-users, you must sign it with a suitable private 

key. You can not publish an application that is signed with the debug key generated 

by the SDK tools. 

  </li>

  <li>The system tests a signer certificate's expiration date only at install time. If an 

run or debug it on an emulator or device.</p>

<p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin 

for Eclipse and the Ant build tool offer two signing modes — debug mode and release mode. 

for Eclipse and the Ant build tool offer two signing modes &mdash; <em>debug mode</em> 

and <em>release mode</em>. 

<ul>

<li>In debug mode, the build tools use the Keytool utility, included in the JDK, to create 

<li>While developing and testing, you can compile in debug mode. 

In debug mode, the build tools use the Keytool utility, included in the JDK, to create 

a keystore and key with a known alias and password. At each compilation, the tools then use 

the debug key to sign the application .apk file. Because the password is known, the tools 

don't need to prompt you for the keystore/key password each time you compile.</li>

<li>When your application is ready for release, you compile it in release signing mode. 

In this mode, the tools compile your .apk <em>without</em> signing it. You must then sign

the .apk manually &mdash; <span style="color:red">with your private key</span> &mdash; 

<li>When your application is ready for release, you must compile in release mode

and then sign the .apk <span style="color:red">with your private key</span>. 

There are two ways to do this:

  <ul>

    <li>Using Keytool and Jarsigner in the command-line. In this approach,

    you first compile your application to an <em>unsigned</em> .apk. You must then sign

    the .apk manually with your private key

    using Jarsigner (or similar tool). If you do not have a suitable private key already, 

    you can run Keytool manually to generate your own keystore/key and then sign your 

    application with Jarsigner.</li>

    <li>Using the ADT Export Wizard. If you are developing in Eclipse with the ADT plugin, 

    you can use the Export Wizard to compile the application, generate a private key 

    (if necessary), and sign the .apk, all in a single process using the Export Wizard.

    </li>

  </ul>

</li>

</ul>

<h2 id="strategies">Signing Strategies</h2>

lifespan of your applications. There are several reasons why you should do so: </p>

<ul>

<li>Application upgrade &mdash; As you release upgrades to your

<li>Application upgrade &ndash; As you release upgrades to your

application, you will want to sign the upgrades with the same certificate, if you

want users to upgrade seamlessly to the new version. When the system is 

installing an update to an application, if any of the certificates in the 

application — in this case, the user installs the new version as a 

completely new application. </li>

<li>Application modularity &mdash; The Android system allows applications that

<li>Application modularity &ndash; The Android system allows applications that

are signed by the same certificate to run in the same process, if the

applications so request, so that the system treats them as a single application.

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 &mdash; The Android system provides

<li>Code/data sharing through permissions &ndash; 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

<p>If you are developing on a version of Linux that originally came with GNU Compiler for 

Java, make sure that the system is using the JDK version of Keytool, rather than the gcj 

version. If Keytool is already in your PATH, it might be pointing to a symlink at 

/usr/bin/keytool. In this case, check the symlink target to make sure that it points 

<code>/usr/bin/keytool</code>. In this case, check the symlink target to make sure that it points 

to the Keytool in the JDK.</p>

<p>If you will release your application to the public, you will also need to have

<p>The SDK tools create the debug keystore/key with predetermined names/passwords;</p>

<ul>

<li>Keystore name &mdash; "debug.keystore"</li>

<li>Keystore password &mdash; "android"</li>

<li>Key alias &mdash; "androiddebugkey"</li>

<li>Key password &mdash; "android"</li>

<li>CN &mdash; "CN=Android Debug,O=Android,C=US"</li>

<li>Keystore name &ndash; "debug.keystore"</li>

<li>Keystore password &ndash; "android"</li>

<li>Key alias &ndash; "androiddebugkey"</li>

<li>Key password &ndash; "android"</li>

<li>CN &ndash; "CN=Android Debug,O=Android,C=US"</li>

</ul></p>

<p>If necessary, you can change the location/name of the debug keystore/key or

supply a custom debug keystore/key to use. In Eclipse/ADT, you can use

<strong>Windows</strong> &gt; <strong>Prefs</strong> &gt;

<strong>Android</strong> &gt; <strong>Build</strong>. However, any custom debug

keystore/key must use the same keystore/key names and passwords as the default

debug key (as described above).</p>

<p class="note"><strong>Note:</strong> You <em>cannot</em> release your application 

to the public when signed with the debug certificate.</p>

<h3>Eclipse Users</h3>

<p>If you are developing in Eclipse/ADT and have set up Keytool as described

above, signing in debug mode is enabled by default. When you run or debug your

application, ADT signs the .apk with the debug certificate and installs it on 

the emulator. No specific action on your part is needed, provided ADT has 

access to Keytool.</p>

<h3>Ant Users</h3>

<p>If you use Ant to build your .apk files, debug signing mode 

is enabled by default, assuming that you are using a build.xml file generated by the 

activitycreator tool included in the latest SDK. When you run Ant against build.xml to 

is enabled by using the <code>debug</code> option, 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. 

No specific action on your part is needed.</p>

<p>If necessary, you can change the location/name of the debug keystore/key or

supply a custom debug keystore/key to use. In Eclipse/ADT, you can use

<strong>Windows</strong> &gt; <strong>Prefs</strong> &gt;

<strong>Android</strong> &gt; <strong>Build</strong>. However, any custom debug

keystore/key must use the same keystore/key names and passwords as the default

debug key (as described above). </p>

No other action on your part is needed. Read 

<a href="{@docRoot}guide/developing/other-ide.html#DebugMode">Developing In Other IDEs: Building 

in debug mode</a> for more information.</p>

<p>Note that you <em>cannot</em> release your application to the public if it 

is signed with the debug certificate. </p>

<h3 id="debugexpiry">Expiry of the Debug Certificate</h3>

<p>In Eclipse/ADT, you will see a similar error in the Android console.</p>

<p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, 

the file is stored in <code>~/.android</code>. On Windows XP, the file is stored in <code>

C:\Documents and Settings\&lt;user&gt;\Local Settings\Application Data\Android</code>. 

On Windows Vista, the file is stored in <code>

C:\Users\&lt;user&gt;\AppData\Local\Android</code>.</p>

<p>To fix this problem, simply delete the <code>debug.keystore</code> file. 

The default storage location for AVDs is in <code>~/.android/avd</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.</p>

<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p>

I can't compile my app because the build tools generated an expired debug 

certificate</a>. </p>

<h2 id="releasemode">Signing for Public Release</h2>

<p>When your application is ready for release to other users, you must:</p>

<ol>

  <li>Compile the application in release mode</li>

<li>Obtain a suitable private key, and then</li>

  <li>Obtain a suitable private key</li>

  <li>Sign the application with your private key</li>

<li>Secure your private key</li>

</ol>

<p>The sections below provide information about these steps. </p>

<p>The sections below provide information about how to perform these steps.</p>

<h3 id="releasecompile">Compiling for Release</h3>

<p>If you use Eclipse with the ADT plugin, you can instead use the Export Wizard

to compile and sign an .apk with your private key. The Export Wizard even allows you to 

generate a new keystore and private key in the process. Skip to

<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p>

<h3 id="releasecompile">Compiling for release</h3>

<p>To prepare your application for release, you must first compile it in release mode. 

In release mode, the Android build tools compile your application as usual, 

but without signing it with the debug key.</p>

<p>If you are developing in Eclipse/ADT, right-click the project in the Package 

pane and select <strong>Android Tools</strong> > <strong>Export Application 

Package</strong>. You can then specify the file location for the unsigned .apk. 

Alternatively, you can follow the "Exporting the unsigned .apk" 

link in the Manifest Editor overview page. </p>

<p class="warning"><strong>Note:</strong>

You can not release your application unsigned, or signed with the debug key.</p>

<h4>Eclipse users</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 simply specify the file location for the unsigned .apk.

(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open 

the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p>

<p>You can also combine the compiling and signing steps with the Export Wizard. See 

<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p>

<h4>Ant users</h4>

<p>If you are using Ant, all you need to do is specify the build target 

"release" in the Ant command. For example, if you are running Ant from the 

<pre>$ ant release</pre>

<p>The build script compiles the application .apk without signing it. 

<p>The build script compiles the application .apk without signing it.</p>

<p>Note that you can not release your application unsigned, or signed with the debug key.</p>

<h3 id="cert">Obtaining a Suitable Private Key</h3>

command and pass any of the options listed below (and any others, as

needed). </p>

<p class="warning">Before you run Keytool, make sure to read 

<p class="warning"><strong>Note:</strong> 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

href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security">

http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p>

<h3 id="signapp">Signing Your Application</h3>

<h3 id="signapp">Signing your application</h3>

<p>When you are ready to actually sign your .apk for release, you can do so

using the Jarsigner tool. Make sure that you have Jarsigner available on your

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 

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>

.apk multiple times with different keys.</p>

<p>To verify that your .apk is signed, you can use a command like this:</p>

<p>The command above, with the <code>-certs</code> option added, will show you the 

"CN=" line that describes who created the key.</p>

<p class="note">Note: if you see "CN=Android Debug", this means the .apk was

<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>

<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security">

http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p>

<h3 id="ExportWizard">Compiling and signing with Eclipse ADT</h3>

<p>When using Eclipse with ADT, 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 perform signing via a

graphical interface instead of the command-line.

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>

<p>To create a signed .apk, right-click the project in the Package 

Explorer and select <strong>Android Tools > Export Signed Application Package</strong>.

(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open 

the <em>Overview</em> tab, and click <strong>Use the Export Wizard</strong>.)

The window that appears will display any errors found while 

attempting to export your application. If no errors are found, continue with the

Export Wizard, 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>

<p>When you complete the Export Wizard, you'll

have a signed .apk that's ready for distribution.</p>

<h2 id="secure-key">Securing Your Private Key</h2>

<p>Maintaining the security of your private key is of critical importance, both