Digital signatures When you are running your applications using the adb, you are running in debug
B.2 Digital signatures When you are running your applications using the adb, you are running in debug
mode. In debug mode your applications are automatically digitally signed by the SDK using a self-signed debug key that is stored in the debug.keystore file (this file is in the .android subdirectory of the user’s home directory by default).
The Android platform requires digital signatures on every .apk package (every appli- cation archive file). Without a digital signature, an .apk is not allowed to run. The debug key and store are conveniences included for you, so that you do not have to worry about
Digital signatures
digital signatures while developing applications using the SDK. When you are ready to go beyond debug mode and run outside the adb, you need to sign your application with
a non-debug key (the debug key is not allowed outside debug mode). Here we are going to cover basic examples of using the Java to create your own key and keystore. We will also include an example of using such a key to sign your .apk files with the Java tool. These are standard Java tools included with the Sun Java SDK; for spe- cific information about these tools, see the Sun documentation for your platform: http: //java.sun.com/javase/6/docs/technotes/tools/index.html - security.
B.2.1 Keytool An example of using the keytool command to create your own self-signed private key
is the following: keytool -genkey -v -keystore my-release-key.keystore -alias my_key -keyalg
➥ RSA -validity 10000 This command generates a key (-genkey) in verbose mode (-v) using a keystore file
named my-release-key.keystore and an alias of my_key with the RSA cryptographic algo- rithm and a validity period of 10000 days. Every key in a keystore requires an alias. We will use the alias next when referring to the key within the keystore while demonstrating how to sign an .apk file. Also note that we are using a very long time period for the key. The Android documentation recommends at least a 25-year key life, and the Android Market currently requires a key that does not expire until after October 22, 2033.
The keytool command will prompt you for a key password and organizational information when creating a key. You should use accurate information (it is possible for your users to view this later), and you should use a strong password. Once you cre- ate your key, you also need to be very careful to store it securely and keep the pass- word private. (If your key is lost or compromised, your identity can be misused, and the trust relationships to your key via your applications can be abused.)
B.2.2 Jarsigner Once you have a private key, you can use it to sign your application files. Signing your
files is done using the jarsigner tool. Before you can use the jarsigner tool, you need to export your project as an unsigned .apk archive. To export your project using the Eclipse/ADT environment, right-click and select the Android Tools > Export Unsigned Application Package option, as shown in figure B.1.
Once you have an unsigned archive file, then you can use the jarsigner tool to sign it with your key, as shown here:
jarsigner -verbose -keystore my-release-key.keystore RestaurantFinder.apk ➥ my_key
This command tells the jarsigner tool to use the previously defined keystore file (my- release-key.keystore) for the particular .apk, using the specified key (designated by the key alias my_key).
A PPENDIX B Signing and installing applications on an Android device
Figure B.1 Using Android Tools from the Eclipse/ADT environment to export an unsigned application archive package
Once you enter this command and use the correct password, jarsigner will create a few metadata files (a manifest, for example) and will digitally sign each file in the archive with your key, as shown here:
Enter Passphrase for keystore: ***************
adding: META-INF/MANIFEST.MF adding: META-INF/TOTSP_KE.SF adding: META-INF/TOTSP_KE.RSA
signing: res/anim/scaler.xml signing: res/drawable/no_review_image.png signing: res/drawable/restaurant_icon.png signing: res/layout/review_criteria.xml signing: res/layout/review_detail.xml signing: res/layout/review_list.xml signing: res/layout/spinner_view.xml signing: res/layout/spinner_view_dropdown.xml signing: AndroidManifest.xml signing: resources.arsc signing: classes.dex
Jarsigner is the last step; after your archive is signed with your key, it’s ready to be installed on a device and tested outside debug mode. You can use the adb tools to
Cleaning up for distribution
install a signed .apk archive (adb install [path_to_apk]), or you can optionally use the very handy APK Installer application that is available in the Android Market ( http://www.android.com/market/ ).
The APK Installer tool lets you install archives that are copied onto your SD card, as opposed to using the adb. Once you plug your device in via USB, you can elect to mount the device (following the on-device screen instructions) and copy files to it. This works like any USB drive, and you can drag your .apk onto your phone. With an .apk archive on your SD card, you can then browse to it from the APK Installer and select Install—it will take care of the rest.
The streamlined process we have outlined here, creating a key and signing your applications with it, is the bare minimum that you need to install an application on an Android device in non-debug mode. For more detailed information you should review the Android documentation in this area ( http://code.google.com/android/devel/ sign-publish.html - signing).
Once you are familiar with signing your applications, the next thing you need to do is perform some final cleanup before actual distribution to end users.