Android Application Development : Signing and Publishing Your Application (part 2)

6. Obtaining a Signing Certificate and API Key

Before you can publish your application to Android Market and have every Android user in the world download it, you first must sign your application. In fact, you’ve been signing your application all along, because the Android Software Development Kit generates a debug signature that is used every time you run your application from Eclipse. The catch is that you cannot use the debug signature to publish your application to the world at large; you must generate a new signature.

If you’re familiar with other mobile development environments (J2ME, Symbian, BREW, etc.), you’re probably an old hand at signing applications. But if you’re new to developing mobile applications, you may be asking yourself what all this signing stuff is for, anyway. Android uses application signing for only one purpose: to ensure that applications that claim to be from the same developer actually are. Applications from the same developer have special capabilities, discussed in the next section.

Google has stated that one of its intentions with Android was to minimize the hassle of getting applications signed. You don’t have to go to a central signing authority to get a signing certificate; you can create the certificate yourself. Once you generate the certificate, you can sign your application using the jarsigner tool that comes with the Java JDK. Once again, you don’t need to apply for or get anyone’s approval. As you’ll see, it’s about as straightforward as signing can be.

6.1. Getting a Signing Certificate for an Application You Are Going to Ship

To sign your application, you are going to create an encrypted signing certificate and use it to sign your application. You can sign every Android application you develop with the same signing certificate. You can create as many signing certificates as you want, but you really need only one for all your applications. And using one certificate for all your applications lets you do some things that you couldn’t do otherwise:

Simplify upgrades

Signing certificates are tied to the application package name, so if you change the signing certificate you use with subsequent versions of your application, you’ll have to change the package name, too. Changing certificates is manageable, but messy.

Multiple applications per process

When all your applications share the same signing certificate, they can run in the same Linux process. You can use this to separate your application into smaller modules (each one an Android application) that together make up the larger application. If you were to do that, you could update the modules separately and they could still communicate freely.

Code/data sharing

Android lets you enable or restrict access to parts of your application based on the requester’s signing certificate. If all your applications share the same certificate, it’s easy for you to reuse parts of one application in another.

One of the things you’ll be asked when you generate a key pair and certificate is the validity period you desire for the certificate. Google recommends that you set it for at least 25 years, and in fact, if you’re going to use Android Market to distribute your application, it requires a validity date at least until October 22, 2033 (25 years to the day from when they opened Android Market) for your certificate.

6.1.1. Generating a key pair (public and private keys) and a signing certificate

To generate a pair of public/private keys, use a tool called keytool, which came with the Sun JDK when you installed it onto your development computer. keytool asks you for some information and uses that to generate the pair of keys:

• A private key that will be kept in a keystore on your computer, secured with passwords. You will use the private key to sign your application, and if you need a Map API Key for your application, you will use the MD5 fingerprint of the signing certificate to generate the Map API Key.^[1]

  ^[1] If you’re not familiar with MD5, you can find many references on the Internet. For our purposes, you can think of it as a hash algorithm that creates a 128-bit fingerprint of an arbitrarily long string. It is often used to validate downloaded files on the Internet, and here it is a way of conveniently validating and condensing a signing certificate so it can be easily verified and compared by Google Maps.

• A public key that Android can use to decrypt your signing certificate. You will send the public key along with your published application so that it can be made available in the runtime environment. Signing certificates are actually checked only at install time, so once installed, your application is good to run, even if the certificate or keys expire.

keytool is pretty straightforward. From your operating system’s command line, enter something like:

$ keytool -genkey -v -keystore microjobs.keystore -alias mjkey -keyalg RSA
							-validity 10000

This asks keytool to generate a key pair and self-signed certificate (-genkey) in verbose mode (-v), so you get all the information, and put it in a keystore called microjobs.key⁠store (-keystore). It also says that in the future you want to refer to that key by the name mjkey (-alias), and that keytool should use the RSA algorithm for generating public/private key pairs (-keyalg). Finally, we say that we’d like the key to be valid for 10,000 days (-validity), or about 27 years.

keytool will prompt you for some things it uses to build the key pair and certificate:

• A password to be used in the future when you want to access the keystore

• Your first and last names

• Your organizational unit (the name for your division of your company, or something like “self” if you aren’t developing for a company)

• Your organization name (the name of your company, or anything else you want to use)

• The name of your city or locality

• The name of your state or province

• The two-letter country code where you are located

keytool will then echo all this information back to you to make sure it’s accurate, and if you confirm the information, will generate the key pair and certificate. It will then ask you for another password to use for the key itself (and give you the option of using the same password you used for the keystore). Using that password, keytool will store the key pair and certificate in the keystore.

You can get more information about security, key pairs, and the keytool utility on Sun’s website at http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security.

6.2. Getting a Signing Certificate While Debugging

When you’re creating and debugging your application that uses a MapView, or when you’re running a demo application like MJAndroid, you still need a valid Map API Key to get map tiles from Google Maps, and you need the fingerprint of your debug signing certificate to obtain a Map API Key. You can’t just use the apiKey that we have coded into the MJAndroid source files, because it is tied to the signing certificate that was generated by our debug environment. Your debug environment will generate its own, different signing certificate for you to use, so you need to obtain a Map API Key to match.

There are two steps to getting the key:

6.2.1. Getting the MD5 fingerprint of your Debug signing certificate

When the Android SDK automatically generates a Debug signing certificate for you, it places it in a keystore called debug.keystore. The trick is to find this keystore. At least for the current version of the SDK, as this is being written, the location is operating system dependent:

• Under Linux and Mac OS X, it is in the .android subdirectory under your home directory: ~/.android/debug.keystore.

• Under Windows Vista, it’s a little harder to find; it’s under your personal Application Data directory: C:\Users\your_username\AppData\Local\Android\de⁠bug.key⁠store.

• Windows XP is similar to Vista: C:\Documents and Settings\your_username\Local Settings\Application Data\Android\debug.keystore (unlike Vista, you will need to use a quoted string for the XP shell).

Once you’ve found debug.keystore, keytool can give you the MD5 fingerprint of your Debug signing certificate. Under Linux or OS X you’d type:

$ keytool -list -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass
							android -keypass android

					  

For Vista or XP, just substitute the correct location in the -keystore option. keytool prints the date the Debug signing certificate was created and the MD5 fingerprint. As an interesting note, Debug signing certificates are good for 365 days after creation.

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

Now that you have the MD5 fingerprint of your Debug Signing Certificate, you can use it to get a valid Map API Key for your system.

6.2.2. Getting a Map API Key from Google

Now that you have a signing certificate to use for your application, you can apply to Google for a Map API Key. Map API Keys are tied to a signing certificate, so obviously the Map API Key you get will work only with applications signed with the same certificate (another good reason for sticking with the same certificate for all your applications). Getting the key is pretty easy, and it’s free.

When an application that contains a MapView runs, it requests map “tiles” from Google Maps via the Internet. As part of that request, it sends the Map API Key that was obtained when the developer signed up with Google, as well as the MD5 fingerprint of the application’s signing certificate. Google Maps checks to see that the key is registered to a developer, and then checks to see that the Map API Key matches the one on file for applications with that signing certificate fingerprint. If they match, it sends the requested tiles. If they don’t match, no tiles are sent.

So we’re going to need the MD5 fingerprint of the signing certificate that we just created. Fortunately, keytool can get that for us:

$ keytool -list -alias mjkey -keystore microjobs.keystore

keytool asks for the passwords to the keystore (and key, if they’re different), and prints out the MD5 fingerprint in hexadecimal. Use your mouse to copy the fingerprint so you can paste it into the Google page later.

Now you can go to the Google Map API Key website at http://code.google.com/android/maps-api-signup.html to actually get the Map API Key. The Terms of Service are shown in a text box. Read them, and if appropriate, click on the checkbox that indicates you accept. Paste the MD5 fingerprint into the form, click the “Generate API key” button, and the website will ask you to log into your Google account. If you don’t have a Google account, you can quickly create one on the spot.

Once you log in, the website returns the Map API Key, which can be used with any application that uses the signing certificate whose fingerprint you entered. It’s a long alphanumeric string, so you will want to copy it into your clipboard and paste it into the XML layout file for your Map Activity.

As an example, the XML layout file for MJAndroid’s Map Activity (called MicroJobs) has the following section defining the MapView and the API Key that matches our debug environment:

<com.google.android.maps.MapView
    android:id="@+id/mapmain"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:clickable="true"
    android:apiKey="0P18K0TAE0dO2GifdtbuScgEGLWe3p4CYUQngMg"
/>

Of course, you will have to substitute your own apiKey for ours.

7. Signing Your Application

We’re almost ready to sign your application, but first you need to create an unsigned version that you can sign with your signature certificate. To do that, in the Package Explorer window of Eclipse, right-click on your project name. You’ll get a long pop-up menu; toward the bottom, click on Android Tools. You should see another menu that includes the item you want: “Export Unsigned Application Package...”. This item takes you to a File Save dialog box, where you can pick the place to save the unsigned version of your apk file. It doesn’t matter where you put it—just pick a place you can remember.

Now that you have an unsigned version of your apk file, we can go ahead and sign it using jarsigner. Open a terminal or command window in the directory where you stored the unsigned apk file. Here’s the line we used to sign MJAndroid, using the key we generated earlier in the keystore microjobs.keystore:

$ jarsigner -verbose -keystore microjobs.keystore MJAndroid.apk mjkey

Congratulations! You now have a signed version of your application that can be loaded and run on any Android device. But before you send it in to Android Market, there’s one more intervening step....

8. Retesting Your Application

If everything went smoothly, your application is now signed and will function just as well as it did before you went through this process. But to be sure things went smoothly, it is wise to retest your application, again testing on real Android devices where possible. You really don’t want thousands of people downloading a broken application attributed to you, so just to be safe, retest on as many Android devices as you can get your hands on.

9. Publishing on Android Market

After you’re satisfied that your application runs as expected on real Android devices, you’re ready to upload to Android Market, Google’s service for publishing and downloading Android applications. The procedure is pretty straightforward:

9.1. Signing Up As an Android Developer

Go to Google’s website at http://market.android.com/publish, and fill out the forms provided. As this is written, Android Market is still in beta, and you will be asked to:

• Use your Google account to log in (if you don’t have a Google account, you can get one for free by following the Create Account link on the login page).

• Agree to the Android Market Terms of Service.

• Pay a one-time fee of $25 (payable by credit card via Google Checkout; again, if you don’t have an account set up, you can do so quickly).

The forms ask for a minimal amount of information—your name, phone number, etc.—and you are signed up.

9.2. Uploading Your Application

Now you can go to http://market.android.com/publish/Home to upload your application. To identify and categorize your application, you will be asked for the following:

Application apk file Name and Location

The apk file of your application, signed with your private signature certificate.

Title and Description

These are very important, because they are the core of your marketing message to potential users. Try to make the title descriptive and catchy at the same time, and describe the application in a way that will make your target market want to download it.

Application Type

There are currently two choices: Applications or Games.

Category

The allowable list of categories varies depending on Application Type. The currently available categories for Applications are: Communications, Demo, Entertainment, Finance, Lifestyle, Multimedia, News & Weather, Productivity, Reference, Shopping, Social, Software Libraries, Tools, and Travel. For Games, the currently available categories include: Arcade & Action, Brain & Puzzle, Cards & Casino, and Casual.

Price

This must be “Free” under the beta version of Android Market. Google has said they will enable charging for applications in the near future (maybe by the time you read this).

Geography

You can limit where your application is available, or choose to make it available everywhere.

Finally, you are asked to confirm that your application meets the Android Content Guidelines and that it does not knowingly violate any export laws. After that, you can upload your apk file, and within a few days your application will appear on the Android Market online catalog, accessible from any connected Android device. There is currently no way to access Android Market directly from your PC or Mac, so you’ll have to use your Android phone to find out when your application is available for download.