David Mays

Creating Keystores and Signing Android Apps

January 30, 2017

As a security measure, Android requires that apps be signed in order to be installed. Signing an app first requires creating keystores. A keystore is a storage mechanism for security certificates. A public key certificate is used to sign an APK before deployment to services like the Google Play Store.  Signing the APK in this fashion allows Google to provide a high level of certainty that future updates to your APK of the same app come from you and not some malicious  third party.

Considerations

There are some things you will need to consider before first deploying your Android app. Primary among these is the expected lifespan of your app.  You will not be able to deploy the same app signed by another key at any point in the near future. Android, as well as Google Play, enforces the use of the same key for updates to an APK. If you need to sign your app with another key for any reason, you will have to deploy the app with a new package name.  Any ratings your app had on Google Play will be lost. You will also lose touch with your user base unless you have notified them in some way to expect the existing app to be obsolete.

Creating keystores

After you have decided on an app’s lifespan, you’ll want to generate your keystore. Java includes a tool for just this purpose: keytoolkeytool is located in your Java JDK installation and should be on your path for the purposes of this article. keytool will quickly generate a public/private key pair and store them in a keystore for you after you answer a few simple questions.

keytool has a number of commands. The most common command used for signing Android builds -genkeypair, commonly abbreviated -genkey. The other commands may be useful to you, but uncommonly so. Again, there are lots of options for this keytool command. The primary -genkey options we are concerned with are in the table below with a brief description:

-keystore               Filename of the generated keystore
-alias               Keypair alias name
-keyalg               Algorithm used to generate keypair
-keysize               Keypair size, in bits
-validity               Keypair validity duration, in days

 

In other words, running the command

keytool -genkey -v -keystore release.keystore -alias example -keyalg RSA -keysize 2048 -validity 10000

would result in a keystore file called release.keystore which contained an RSA-2048 public/private keypair by the alias name of example and validity of 10,000 days (more than 27 years).

Before running this command, you’ll want to decide on strong passwords for the keystore and key. You’ll need both of these passwords to sign an APK — they can be the same password if you’re into that kind of thing. The tool will also collect some metadata like your name and organization, but all of that is optional.

Related: Backgrounding Instead of Finishing the Root Activity on Android

Signing your APK

  • Sign with Gradle

After running the command you’ll be the proud owner of a brand new Java Keystore.  You probably want to set up your project to use the keystore to sign your APK, so let’s have a look at that.

If you’re using gradle to build your Android project, you will create a android.signingConfig and associate it with one or more android.buildTypes. The two passwords, keystore name, and alias name will all be needed in order to sign an APK. You can handle this in at least a few different ways. The simplest is to enter the relevant information directly into your gradle build script:

android {  
    signingConfigs {  
        release {  
            storeFile 'config.keystore'  
            storePassword 'storePassword'  
            keyAlias 'example'  
            keyPassword 'keyPassword'  
        }
    }  
    buildTypes {  
        release {  
            signingConfig signingConfigs.release  
        }
    }  
  }

If you want to control access to the passwords you can move the information out of the build.gradle file and put it in your local environment or in a properties file to load at build time.  To maintain security and control of the information, it’s likely that you would not want to check the keystore properties file into your source control.

Here is an example [from Google] of how to load the information from a file that would be located in your app’s root directory with the project level build.gradle file:

def keystorePropertiesFile = rootProject.file("keystore.properties")  
def keystoreProperties = new Properties()  
keystoreProperties.load(new FileInputStream(keystorePropertiesFile))

android {  
    signingConfigs {  
        release {  
            keyAlias keystoreProperties['keyAlias']  
            keyPassword keystoreProperties['keyPassword']  
            storeFile file(keystoreProperties['storeFile'])  
            storePassword keystoreProperties['storePassword']  
        }
    }  
}

keystore.properties would contain (in this example):

storeFile=release.keystore  
storePassword=myStorePassword  
keyAlias=example  
keyPassword=mykeyPassword

If you prefer the environment variable method, create a script to add the variables to your environment and try something like this:

signingConfigs {  
    release {  
        def keyfile = System.getenv("KEYSTORE_FILENAME")  
        storeFile file(keyfile != null ? keyfile : "release.keystore")  
        storePassword System.getenv("KEYSTORE_PASSWORD")  
        keyAlias System.getenv("KEY_ALIAS")  
        keyPassword System.getenv("KEY_PASSWORD")  
    }
}

There are some trade-offs to both of these methods. Figure out what works best for your organization’s methodology and use that one. For the environment variable method, for example, you have to load these variables into your environment somehow. This is less than ideal if you want to generate a signed APK with Android Studio.

  • Sign manually

If you prefer to sign your APK manually instead of as part of the build process, you’ll want to use apksigner, located at {ANDROID_SDK_DIRECTORY}/build-tools/{BUILD_TOOLS_VERSION}/apksigner for build-tools revision 24.0.3 or higher. apksigner uses the public/private key pair stored in your app’s keystore to generate a public key certificate. apksigner then attaches that certificate to the APK. After this is accomplished, the APK is associated with that private key in a unique way. The Android gradle plugin will handle this for you if you configure your build.gradle file with all of the necessary information, as shown above.

You’ll want to zipalign your APK, zipalign will ensure that your app’s uncompressed data starts at a predictable offset inside the APK. zipaligned APKs are required to publish to the Google Play store.

zipalign -v -p 4 app-flavor-buildtype-unsigned.apk app-flavor-buildtype-unsigned-aligned.apk

After your APK is zipaligned, sign it using apksigner:

apksigner sign --ks release.keystore --out app-flavor-buildtype.apk app-flavor-buildtype-unsigned-aligned.apk

You will be prompted at the command line to enter the password for your keystore.

If your keystore and key passwords differ, you’re in for a treat! Using the command above, you will be asked for the keystore password, but will not be asked for the key password. Entering either password results in exceptions and you won’t be having a good time. You’ll need to tell apksigner that you want to specify each password individually. Apparently, this is supposed to be the default behavior, but it hasn’t worked for me. To force apksigner to ask you for the keystore and key password independently, use the --ks-pass and --key-pass options. Following each option with stdin will tell apksigner to capture the password from you at the command line.

apksigner sign --ks example.keystore --ks-pass stdin --key-pass stdin --out app-signed.apk app.apk

I hope this has educated you a bit more about how creating keystores and signing an Android APK works.

Published January 30, 2017
David Mays

Software Engineer at Stable Kernel

Tags:

    • Hi there,

      This post assumes that you have your android sdk `build-tools` directory in your path. You can add it to your path or use an explicit path to the `apksigner` tool. You can use the `which` command on mac and linux machines (`which apksigner`) and `where` on windows (at least, that’s what stack overflow tells me) to find out if an executable is in your path and where it is.

      Thanks!

Leave a Reply

Your email address will not be published. Required fields are marked *