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

Merge "docs: Fix for jarsigner and JDK7; specify signature and digest algorithim" into ics-mr1

Browse Source
This commit is contained in:
Joe Fernandez
2012-04-02 17:17:45 -07:00
committed by Android (Google) Code Review
parent dfa3b8fa4a 82870452aa
commit 1cbd69fbab
1 changed files with 49 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -66,7 +66,7 @@ on an emulator or a device if it is not signed.</li>
application's signer certificate expires after the application is installed, the application application's signer certificate expires after the application is installed, the application
will continue to function normally.</li> will continue to function normally.</li>
<li>You can use standard tools &mdash; Keytool and Jarsigner &mdash; to generate keys and <li>You can use standard tools &mdash; Keytool and Jarsigner &mdash; to generate keys and
sign your application .apk files.</li> sign your application {@code .apk} files.</li>
<li>After you sign your application for release, we recommend that you use the <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> <code>zipalign</code> tool to optimize the final APK package.</li>
</ul> </ul>
@@ -186,9 +186,9 @@ to the Keytool in the JDK.</p>
<p>The Android build tools provide a debug signing mode that makes it easier for you <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 to develop and debug your application, while still meeting the Android system
requirement for signing your .apk. requirement for signing your APK.
When using debug mode to build your app, the SDK tools invoke Keytool to automatically create 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 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> 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> <p>The SDK tools create the debug keystore/key with predetermined names/passwords:</p>
@@ -215,19 +215,19 @@ to the public when signed with the debug certificate.</p>
<p>If you are developing in Eclipse/ADT (and have set up Keytool and Jarsigner as described above in <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>), <a href="#setup">Basic Setup for Signing</a>),
signing in debug mode is enabled by default. When you run or debug your signing in debug mode is enabled by default. When you run or debug your
application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the application, ADT signs the {@code .apk} file with the debug certificate, runs {@code zipalign} on
package, then installs it on the package, then installs it on
the selected emulator or connected device. No specific action on your part is needed, the selected emulator or connected device. No specific action on your part is needed,
provided ADT has access to Keytool.</p> provided ADT has access to Keytool.</p>
<h3>Ant Users</h3> <h3>Ant Users</h3>
<p>If you are using Ant to build your .apk files, debug signing mode <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 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 (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 <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. 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. The script then also aligns the APK with the <code>zipalign</code> tool.
No other action on your part is needed. Read No other action on your part is needed. Read
<a href="{@docRoot}guide/developing/building/building-cmdline.html#DebugMode">Building and Running Apps <a href="{@docRoot}guide/developing/building/building-cmdline.html#DebugMode">Building and Running Apps
on the Command Line</a> for more information.</p> on the Command Line</a> for more information.</p>
@@ -383,8 +383,8 @@ will use later, to refer to this keystore when signing your application. </p>
<p>For more information about Keytool, see the documentation at <p>For more information about Keytool, see the documentation at
<a <a
href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html">
http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html</a></p>
@@ -399,11 +399,11 @@ You can not release your application unsigned, or signed with the debug key.</p>
<h4>With Eclipse</h4> <h4>With Eclipse</h4>
<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package <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 Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application
Package</strong>. Then specify the file location for the unsigned .apk. Package</strong>. Then specify the file location for the unsigned APK.
(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open (Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, select
the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p> 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 <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> <a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p>
@@ -414,11 +414,11 @@ the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)<
with the <code>ant</code> command. For example, if you are running Ant from the 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> directory containing your {@code build.xml} file, the command would look like this:</p>
<pre>ant release</pre> <pre>$ ant release</pre>
<p>By default, the build script compiles the application .apk without signing it. The output file <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>&lt;your_project_name></em>-unsigned.apk</code>. in your project {@code bin/} will be <code><em>&lt;your_project_name></em>-unsigned.apk</code>.
Because the application .apk is still unsigned, you must manually sign it with your private Because the application APK is still unsigned, you must manually sign it with your private
key and then align it using {@code zipalign}.</p> key and then align it using {@code zipalign}.</p>
<p>However, the Ant build script can also perform the signing <p>However, the Ant build script can also perform the signing
@@ -443,8 +443,8 @@ machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that
the keystore containing your private key is available.</p> the keystore containing your private key is available.</p>
<p>To sign your application, you run Jarsigner, referencing both the <p>To sign your application, you run Jarsigner, referencing both the
application's .apk and the keystore containing the private key with which to 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> sign the APK. The table below shows the options you could use. </p>
<table> <table>
<tr> <tr>
@@ -459,6 +459,14 @@ the keystore containing your private key.</td>
<td><code>-verbose</code></td><td>Enable verbose output.</td> <td><code>-verbose</code></td><td>Enable verbose output.</td>
</tr> </tr>
<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 &lt;password&gt;</code></td><td><p>The password for the <td><code>-storepass &lt;password&gt;</code></td><td><p>The password for the
keystore. </p><p>As a security precaution, do not include this option keystore. </p><p>As a security precaution, do not include this option
in your command line unless you are working at a secure computer. in your command line unless you are working at a secure computer.
@@ -478,19 +486,23 @@ way, your password is not stored in your shell history.</p></td>
<code>my_application.apk</code>, using the example keystore created above. <code>my_application.apk</code>, using the example keystore created above.
</p> </p>
<pre>$ jarsigner -verbose -keystore my-release-key.keystore <pre>$ jarsigner -verbose -sigalg MD5withRSA -digestalg SHA1 -keystore my-release-key.keystore
my_application.apk alias_name</pre> my_application.apk alias_name</pre>
<p>Running the example command above, Jarsigner prompts you to provide <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 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 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> <pre>$ jarsigner -verify my_signed.apk</pre>
<p>If the .apk is signed properly, Jarsigner prints "jar verified". <p>If the APK is signed properly, Jarsigner prints "jar verified".
If you want more details, you can try one of these commands:</p> If you want more details, you can try one of these commands:</p>
<pre>$ jarsigner -verify -verbose my_application.apk</pre> <pre>$ jarsigner -verify -verbose my_application.apk</pre>
@@ -502,19 +514,19 @@ 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 <p>The command above, with the <code>-certs</code> option added, will show you the
"CN=" line that describes who created the key.</p> "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 <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 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 your application, you must sign it with your private key instead of the debug
key.</p> key.</p>
<p>For more information about Jarsigner, see the documentation at <p>For more information about Jarsigner, see the documentation at
<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> <a href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html">
http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html</a></p>
<h3 id="align">4. Align the final APK package</h3> <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. <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, 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 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 a performance optimization when installed on a device. When aligned, the Android
@@ -524,16 +536,16 @@ of the data from the package. The benefit is a reduction in the amount of
RAM consumed by the running application.</p> RAM consumed by the running application.</p>
<p>The <code>zipalign</code> tool is provided with the Android SDK, inside the <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> <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> <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 <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 byte-alignment (don't use anything other than 4). The first file argument is
your signed .apk (the input) and the second file is the destination .apk file (the output). your signed {@code .apk} file (the input) and the second file is the destination {@code .apk} file
If you're overriding an existing .apk, add the {@code -f} flag.</p> (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 <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}. 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> If you sign it after using {@code zipalign}, it will undo the alignment.</p>
@@ -544,7 +556,7 @@ If you sign it after using {@code zipalign}, it will undo the alignment.</p>
<h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3> <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 <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, export a <em>signed</em> APK (and even create a new keystore,
if necessary). The Export Wizard performs all the interaction with 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 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, instead of performing the manual procedures to compile, sign,
@@ -554,7 +566,7 @@ Because the Export Wizard uses both Keytool and Jarsigner, you should
ensure that they are accessible on your computer, as described above ensure that they are accessible on your computer, as described above
in the <a href="#setup">Basic Setup for Signing</a>.</p> in the <a href="#setup">Basic Setup for Signing</a>.</p>
<p>To create a signed and aligned .apk in Eclipse:</p> <p>To create a signed and aligned APK in Eclipse:</p>
<ol> <ol>
<li>Select the project in the Package <li>Select the project in the Package
@@ -563,7 +575,7 @@ Explorer and select <strong>File > Export</strong>.</li>
and click <strong>Next</strong>. and click <strong>Next</strong>.
<p>The Export Android Application wizard now starts, which will <p>The Export Android Application wizard now starts, which will
guide you through the process of signing your application, guide you through the process of signing your application,
including steps for selecting the private key with which to sign the .apk including steps for selecting the private key with which to sign the APK
(or creating a new keystore and private key).</p> (or creating a new keystore and private key).</p>
<li>Complete the Export Wizard and your application will be compiled, <li>Complete the Export Wizard and your application will be compiled,
signed, aligned, and ready for distribution.</li> signed, aligned, and ready for distribution.</li>