Signing the Android Application Package (Visual Studio with Xamarin Android 4.2.6 to 6.1)
- PDF for offline use:
Let us know how you feel about this.
last updated: 2016-11
This guide explains how to sign an Android application package using Visual Studio with Xamarin Android 4.2.6 to 6.1. If you are using Visual Studio with Xamarin Android 7.0 or later, see Part 2 - Signing the Android Application Package.
Signing the APK
After the application has been built for release, the resulting APK (Android application package) must be signed with private key and zipalign it so that it is ready for Android to run. This process is accomplished by the following steps:
- Create a Private Key – This step needs to be performed only once. A private key is necessary to digitally sign the APK. After the private key has been prepared, this step can be skipped for future release builds.
- Sign the APK – This step involves signing the APK with the private key that was created in the previous step.
- Zipalign the APK – Zipalign is an optimization process that is performed on an application. It enables Android to interact more efficiently with the APK at runtime. Xamarin.Android conducts a check at runtime, and will not allow the application to run if the APK has not been zipaligned.
Create a Private Keystore
A keystore is a database of security certificates that is created by using the program keytool from the Java SDK. A keystore is critical to publishing a Xamarin.Android application, as Android will not run applications that have not been digitally signed.
During development, Xamarin.Android uses a debug keystore to sign the application, which allows the application to be deployed directly to the emulator or to devices configured to use debuggable applications. However, this keystore is not recognized as a valid keystore for the purposes of distributing applications.
For this reason, a private keystore must be created and used for signing applications. This is a step that should only be performed once, as the same key will be used for publishing updates and can then be used to sign other applications.
It is important to protect this keystore. If it is lost, then it will not be possible to publish updates to the application with Google Play. The only solution to the problem caused by a lost keystore would be to create a new keystore, re-sign the APK with the new key, and then submit a new application. Then the old application would have to be removed from Google Play. Likewise, if this new keystore is compromised or publically distributed, then it is possible for unofficial or malicious versions of an application to be distributed.
Create a New Keystore
Creating a new keystore requires the command line tool
from the Java SDK. The following snippet is an example of how to use
<my-filename.keystore> with the
file name for the keystore and
<key-name> with the
name of the key within the keystore):
$ keytool -genkeypair -v -keystore <filename.keystore> -alias <key-name> -keyalg RSA -keysize 2048 -validity 10000
The first thing that keytool will ask for is the password
for the keystore. Then it will ask for some information to help with
creating the key. The following snippet is an example of creating a new
publishingdoc that will be stored in the file
$ keytool -genkeypair -v -keystore xample.keystore -alias publishingdoc -keyalg RSA -keysize 2048 -validity 10000 Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: Ham Chimpanze What is the name of your organizational unit? [Unknown]: NASA What is the name of your organization? [Unknown]: NASA What is the name of your City or Locality? [Unknown]: Cape Canaveral What is the name of your State or Province? [Unknown]: Florida What is the two-letter country code for this unit? [Unknown]: US Is CN=Ham Chimpanze, OU=NASA, O=NASA, L=Cape Canaveral, ST=Florida, C=US correct? [no]: yes Generating 2,048 bit RSA key pair and self-signed certificate (SHA1withRSA) with a validity of 10,000 days for: CN=Ham Chimpanze, OU=NASA, O=NASA, L=Cape Canaveral, ST=Florida, C=US Enter key password for <publishingdoc> (RETURN if same as keystore password): Re-enter new password: [Storing xample.keystore]
To list the keys that are stored in a keystore, use the
keytool with the
$ keytool -list -keystore xample.keystore
Sign the APK
To publish an application, the build configuration must first be changed to Release. Next, select the project in the Solution Explorer, then select Publish Android App… in the Tools > Android menu, as shown in the following screenshot:
If the Publish Android App… menu option is grayed out, verify that the app project configuration is set to Release (Mono Shared Runtime is not selected and debugging is disabled) and make sure the project is selected in the Solution Explorer. After selecting this menu item, use the Publish Android Application dialog to select a key from a keystore and to provide the password:
After clicking Next, the Select destination dialog appears. This dialog is used to name the signed APK and to specify the directory where the APK should be created:
When the Publish button is clicked, Visual Studio compiles the APK, signs it with the key specified, and then runs the zipalign tool against the APK, all in one step.
At this point, Visual Studio has compiled the Xamarin.Android application into an APK that is ready for distribution. The default location for the APK is placed in the app's project folder.
After the application package has been signed for release, it must be published. The following sections describe several ways to publish an application.