Signing the Android Application Package (Visual Studio with Xamarin Android 4.2.5 and Earlier)

PDF for offline use

Let us know how you feel about this

Translation Quality


last updated: 2017-03


This guide explains how to sign an Android application package using Visual Studio with Xamarin Android 4.2.5 and earlier. 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 a private key and zipalign it so that it is ready for Android to run. This process is accomplished by using 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 APKZipalign 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 keytool from the Java SDK. The following snippet is an example of how to use keytool (replace <my-filename> 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 key called publishingdoc that will be stored in the file xample.keystore:

$ 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 – list option:

$ keytool -list -keystore xample.keystore

Sign the APK

Because versions of Xamarin.Android prior to version 4.2.6 lack the Publish Android Application option, the APK might be signed in this order:

  1. Create the .apk files.
  2. Sign the .apk files.
  3. Zipalign the .apk files.

To create the APK file, select the menu option Build > Package name, as shown in the following screenshot:

Build Package menu item

This will create two .apk files in the bin/Release folder, as shown in the following screenshot:

Created APK files

The file mono.samples.helloworld.apk is an unsigned APK, whereas the file mono.samples.helloworld-Signed.apk is signed by using the debug keystore. Because of this, it is not possible to publish mono.samples.helloworld-Signed.apk.

There are two strategies for obtaining a signed APK when using Visual Studio:

  • Manually Signing the APK – This technique involves manually signing the APK at the command line. This is more secure, but requires a little more effort. The amount of effort exerted can be mitigated by using a simple Powershell script. For more imformation about this process, see Manually Signing the APK.

  • Permanently Use A Different Keystore – By using this technique, the project file is altered to replace the debug keystore with a private keystore. This method is simpler, but poses a security risk. This strategy is described next.

Permanently Use A Different Keystore

To use a different keystore for Release builds involves modifying the Xamarin.Android .csproj file and adding an MSBuild condition:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">

The values of the elements in the PropertyGroup are explained in the following list:

  • AndroidSigningKeystore – This should hold the path and file name of the keystore.

  • AndroidSigningStorePass – This holds the password of the keystore.

  • AndroidSigningKeyAlias – This contains the name of the key in the keystore that will be used to sign the application.

  • AndroidSigningKeyPass – This is the password for the key alias.

As an example, using the keystore that was created above, the MSBuild condition would look as follows:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">

Use this technique with caution as it does store the password for the private key in a plain text file that is easily read by anyone that has access to the source code. This is a potential security risk.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.