cherypick from mr2: Ib7e08e719b6b9c9b1e8116e6e2a77611f046b276
Switch APK signing from MD5WithRSA to SHA1WithRSA. While we're at it, remove duplicates of app-signing.jd. Change-Id: I3b5441bc61107a4f6d9b67366517785e6792cf9e
This commit is contained in:
Alex Klyubin
@@ -466,7 +466,7 @@ the keystore containing your private key.</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 MD5withRSA}.</td>
|
||||
Use the value {@code SHA1withRSA}.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>-digestalg</code></td><td>The message digest algorithim to use in processing the entries
|
||||
@@ -492,7 +492,7 @@ way, your password is not stored in your shell history.</p></td>
|
||||
<code>my_application.apk</code>, using the example keystore created above.
|
||||
</p>
|
||||
|
||||
<pre>$ jarsigner -verbose -sigalg MD5withRSA -digestalg SHA1 -keystore my-release-key.keystore
|
||||
<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
|
||||
|
||||
@@ -1,618 +0,0 @@
|
||||
page.title=Signing Your Applications
|
||||
@jd:body
|
||||
|
||||
<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>
|
||||
<li><a href="#secure-key">Securing Your Private Key</a></li>
|
||||
|
||||
</ol>
|
||||
|
||||
<h2>See also</h2>
|
||||
|
||||
<ol>
|
||||
<li><a href="{@docRoot}tools/publishing/versioning.html">Versioning Your Applications</a></li>
|
||||
<li><a href="{@docRoot}tools/publishing/preparing.html">Preparing to Publish</a></li>
|
||||
</ol>
|
||||
|
||||
</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 will have to 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>
|
||||
|
||||
<ul>
|
||||
<li>Application upgrade – As you release updates to your application, you
|
||||
will want to continue to sign the updates with the same certificate or set of
|
||||
certificates, if you want users 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 will also need to 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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<h2 id="setup">Basic Setup for Signing</h2>
|
||||
|
||||
<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>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>
|
||||
|
||||
<h2 id="debugmode">Signing in Debug Mode</h2>
|
||||
|
||||
<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>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>
|
||||
|
||||
<h3>Eclipse Users</h3>
|
||||
|
||||
<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>
|
||||
|
||||
<h3>Ant Users</h3>
|
||||
|
||||
<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="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>
|
||||
|
||||
<p>When the certificate expires, you will get a build error. On Ant builds, the error
|
||||
looks like this:</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>
|
||||
|
||||
<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.
|
||||
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>The next time you build, the build tools will regenerate a new keystore and debug key.</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="releasemode">Signing in Release Mode</h2>
|
||||
|
||||
<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>
|
||||
</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>
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
</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>
|
||||
|
||||
<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 MD5withRSA}.</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 MD5withRSA -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>
|
||||
|
||||
|
||||
<h3 id="align">4. Align the final APK package</h3>
|
||||
|
||||
<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>
|
||||
|
||||
<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>For more information, read about the
|
||||
<a href="{@docRoot}tools/help/zipalign.html">zipalign</a> tool.
|
||||
|
||||
|
||||
<h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3>
|
||||
|
||||
<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>
|
||||
|
||||
<p>To create a signed and aligned APK in Eclipse:</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="secure-key">Securing Your Private Key</h2>
|
||||
|
||||
<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>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>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>
|
||||
|
||||
<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>
|
||||
</ul>
|
||||
|
||||
<p>In general, if you follow common-sense precautions when generating, using,
|
||||
and storing your key, it will remain secure. </p>
|
||||
@@ -1,618 +0,0 @@
|
||||
page.title=Signing Your Applications
|
||||
@jd:body
|
||||
|
||||
<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>
|
||||
<li><a href="#secure-key">Securing Your Private Key</a></li>
|
||||
|
||||
</ol>
|
||||
|
||||
<h2>See also</h2>
|
||||
|
||||
<ol>
|
||||
<li><a href="{@docRoot}tools/publishing/versioning.html">Versioning Your Applications</a></li>
|
||||
<li><a href="{@docRoot}tools/publishing/preparing.html">Preparing to Publish</a></li>
|
||||
</ol>
|
||||
|
||||
</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 will have to 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>
|
||||
|
||||
<ul>
|
||||
<li>Application upgrade – As you release updates to your application, you
|
||||
will want to continue to sign the updates with the same certificate or set of
|
||||
certificates, if you want users 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 will also need to 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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<h2 id="setup">Basic Setup for Signing</h2>
|
||||
|
||||
<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>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>
|
||||
|
||||
<h2 id="debugmode">Signing in Debug Mode</h2>
|
||||
|
||||
<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>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>
|
||||
|
||||
<h3>Eclipse Users</h3>
|
||||
|
||||
<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>
|
||||
|
||||
<h3>Ant Users</h3>
|
||||
|
||||
<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="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>
|
||||
|
||||
<p>When the certificate expires, you will get a build error. On Ant builds, the error
|
||||
looks like this:</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>
|
||||
|
||||
<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.
|
||||
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>The next time you build, the build tools will regenerate a new keystore and debug key.</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="releasemode">Signing in Release Mode</h2>
|
||||
|
||||
<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>
|
||||
</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>
|
||||
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
</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>
|
||||
|
||||
<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 MD5withRSA}.</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 MD5withRSA -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>
|
||||
|
||||
|
||||
<h3 id="align">4. Align the final APK package</h3>
|
||||
|
||||
<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>
|
||||
|
||||
<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>For more information, read about the
|
||||
<a href="{@docRoot}tools/help/zipalign.html">zipalign</a> tool.
|
||||
|
||||
|
||||
<h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3>
|
||||
|
||||
<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>
|
||||
|
||||
<p>To create a signed and aligned APK in Eclipse:</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="secure-key">Securing Your Private Key</h2>
|
||||
|
||||
<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>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>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>
|
||||
|
||||
<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>
|
||||
</ul>
|
||||
|
||||
<p>In general, if you follow common-sense precautions when generating, using,
|
||||
and storing your key, it will remain secure. </p>
|
||||
Reference in New Issue
Block a user