Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Original author: smain
  Merged from: //branches/cupcake/...
  Original author: android-build

Automated import of CL 147225
This commit is contained in:
Scott Main
2009-04-21 14:29:14 -07:00
committed by The Android Open Source Project
parent 12af87bb36
commit 1362dad293
1 changed files with 126 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
docs/html/guide/publishing/app-signing.jd
View File

@@ -22,9 +22,10 @@ page.title=Signing Your Applications
<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>
@@ -47,9 +48,9 @@ page.title=Signing Your Applications
<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>
@@ -61,8 +62,8 @@ 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
@@ -78,20 +79,32 @@ For this reason, you must set up signing for your application before you will be
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 &mdash; 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;
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>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>
@@ -105,7 +118,7 @@ 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>
<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
@@ -115,13 +128,13 @@ certificate, you will also need to assign a different package name to the
application &mdash; 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
@@ -167,7 +180,7 @@ Alternatively, you can add the JDK version of Keytool to your PATH variable.</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 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
@@ -180,38 +193,46 @@ in the JDK. </p>
to develop and debug your application, while still meeting the Android system
requirement for signing your .apk when it is installed in the emulator or a device.
When you use debug mode, the SDK tools invoke Keytool to create a debug
keystore and key. </p>
keystore and key.</p>
<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>
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>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>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>
@@ -227,11 +248,11 @@ looks like this:</p>
<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>
@@ -242,29 +263,45 @@ troubleshooting topic <a href="{@docRoot}guide/appendix/faq/troubleshooting.html
I&nbsp;can't&nbsp;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>Sign the application with your private key</li>
<li>Secure your private key</li>
<li>Compile the application in release mode</li>
<li>Obtain a suitable private key</li>
<li>Sign the application with 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>
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
@@ -272,9 +309,8 @@ directory containing your build.xml file, the command would look like this:</p>
<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>
@@ -303,7 +339,7 @@ in <a href="#setup">Basic Setup</a>.</p>
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
@@ -378,7 +414,8 @@ will use later, to refer to this keystore when signing your application. </p>
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
@@ -425,9 +462,9 @@ way, your password is not stored in your shell history.</p></td>
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>
@@ -445,7 +482,7 @@ If you want more details, you can try one of these commands:</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>
@@ -454,6 +491,32 @@ 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