7.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.

7.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.

7.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 .

7.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:

7.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.

What Happens When My Debug Signing Certificate Expires? After your certificate expires, you'll get a build error whenever you try to build your application. The error will be displayed on the Android console (one of the tabs in the bottom pane of the Java and DDMS Perspectives), and it will say something like: 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 To fix it, just delete your debug.keystore file (see the earlier list for its location in different host operating systems). The next time you build, the Android SDK will generate a new debug.keystore with a new Debug signing certificate, and your application can build and run.

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.

7.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 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.