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

Author: joefernandez

docs/html/guide/publishing/app-signing.jd

@@ -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
 will continue to function normally.</li>
   <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
     <code>zipalign</code> tool to optimize the final APK package.</li>
 </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
 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
-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>
 
 <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
 <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 .apk with the debug certificate, runs {@code zipalign} on the
-package, then installs it on
+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 .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
 (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.
+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}guide/developing/building/building-cmdline.html#DebugMode">Building and Running Apps
 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
 <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>
+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>
 
 
 
@@ -399,11 +399,11 @@ 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
+<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, open
-the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p>
+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>
@@ -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
 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>.
-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>
 
 <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>
 
 <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>
+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>
@@ -459,6 +459,14 @@ the keystore containing your private key.</td>
 <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 &lt;password&gt;</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.
@@ -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.
 </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>
 
 <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>
+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>
+<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".
+<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>
@@ -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
 "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
 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://java.sun.com/j2se/1.5.0/docs/tooldocs/#security">
-http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p>
+<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.
+<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
@@ -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>
 
 <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
 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).
-If you're overriding an existing .apk, add the {@code -f} flag.</p>
+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
+<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>
 
@@ -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>
 
 <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
 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,
@@ -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
 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>
   <li>Select the project in the Package
@@ -563,7 +575,7 @@ Explorer and select <strong>File > Export</strong>.</li>
   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
+  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>