Revealing Android Keystore — Initialization

The encryption and decryption part is generally the same as in our previous code. The difference is in how we generate the key. This time, let’s make it a little cleaner and create an interface for encryption/decryption.

interface CipherManager {
    @Throws(Exception::class)
    fun encrypt(inputText: String): String

    @Throws(Exception::class)
    fun decrypt(data: String): String
}

Again, consider working directly with ByteArrays.

Let’s create the implementation class and define some constants.

class CipherManagerImpl : CipherManager {

    @Throws(Exception::class)
    override fun encrypt(inputText: String): String {
        TODO("Not yet implemented")
    }

    @Throws(Exception::class)
    override fun decrypt(data: String): String {
        TODO("Not yet implemented")
    }

    companion object {
        private const val ANDROID_KEY_STORE = "AndroidKeyStore"
        private const val AES_ALGORITHM = KeyProperties.KEY_ALGORITHM_AES
        private const val BLOCK_MODE = KeyProperties.BLOCK_MODE_CBC
        private const val PADDING = KeyProperties.ENCRYPTION_PADDING_PKCS7
        private const val TRANSFORMATION = "$AES_ALGORITHM/$BLOCK_MODE/$PADDING"
    }
}

Using this approach you can have other implementations too. In the constants sections everything is like before despite ANDROID_KEY_STORE, which is the provider name we pass to get our Keystore instance.

private val keyStore = KeyStore.getInstance(ANDROID_KEY_STORE).apply {
    load(null) // With load function we initialize our keystore
}

Generating Secure Keys with KeyGenerator

KeyGenerator is a class, well it’s obvious that it’s a class for generating cryptographic keys. However, it’s used for symmetric key generation. To generate asymmetric keys you should take a look at KeyPairGenerator which generates a pair of public and private keys.

private val keyAlias = "aes_key_alias" // TODO - Should be secure

@Throws(Exception::class)
private fun createKey(): SecretKey {
    @Throws(Exception::class)
    private fun createKey(): SecretKey {
        val keyGenParameterSpec = KeyGenParameterSpec.Builder(
            keyAlias,
            KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
        )
            .setBlockModes(BLOCK_MODE)
            .setEncryptionPaddings(PADDING)
            .setUserAuthenticationRequired(false)
            .setRandomizedEncryptionRequired(true)
            .build()

        return KeyGenerator.getInstance(AES_ALGORITHM).apply {
            init(keyGenParameterSpec)
        }.generateKey()
    }
}

Before creating our KeyGenerator we create a KeyGenParameterSpec. In simpler words, it’s a class using which we customize the key generation by passing different parameters to it. Let’s analyze it line by line.

You can use it for both KeyGenerator and KeyPairGenerator, but only since API 23+. Before that, for KeyPairGenerator you should have used KeyPairGenParameterSpec. We do not have symmetric keys until API 23.

We utilize the KeyGenParameterSpec.Builder to build our KeyGenParameterSpec. That Builder requires two arguments: an alias name and a purpose. Threat the alias name as a unique identifier assigned to the generated key within the Android Keystore. Later we’ll use it to get our key from the Keystore.

Notice how we don’t need to manually generate any key material. Isn’t that perfect? In case of SecretKeySpec if someone obtains the key material, they can generate the same key in their devices and use it. But in Android Keystore the key material never enters the application process. Even if someone gets our alias, they can’t create the same key on their devices because the key material will be different. Still, consider keeping your alias somewhere safe 🙂

Let’s continue. The second parameter of KeyGenParameterSpec.Builder means for what purpose we use our key. Simply just pass PURPOSE_ENCRYPT or PURPOSE_DECRYPT.

Next, we invoke multiple builder methods. We specify our block mode and padding. Let’s talk a little about the other two functions:

setUserAuthenticationRequired(false) — This method is used to specify whether user authentication is required to use the key. When set to true, it means that the key can only be used after the user has been authenticated through methods like a PIN, password, or biometric authentication (e.g., fingerprint or face recognition). By default, the key is authorized to be used regardless of whether the user has been authenticated. So we actually don’t need this function in the scope of this article. I wrote it just to let you know that there’s a such thing too.

setRandomizedEncryptionRequired(true) — According to docs: Sets whether encryption using this key must be sufficiently randomized to produce different ciphertexts for the same plaintext every time. But didn’t we already get a different ciphertext each time using a random IV? Well, that’s not the case with Android Keystore. What if someone uses some fixed value instead of randomly generating the IV? To prevent such cases, the Android Keystore provider is not allowing the use of custom IV values. This function indicates whether you can use your own IV or not.

However, even passing false to this function we will get java.security.InvalidAlgorithmParameterException: Caller-provided IV not permitted exception. Cipher automatically generates a random IV each time under the hood.

All the functions of KeyGenParameterSpec.Builder you can find here.

Lastly, we get our KeyGenerator instance, initialize it by passing our KeyGenParameterSpec as an argument, and call generateKey(). The key is being securely stored in the Android Keystore System.

Later, to perform encryption/decryption, we should check if that key already exists.

@Throws(Exception::class)
private fun getOrCreateKey(): SecretKey {
    val existingKey = keyStore.getEntry(keyAlias, null) as? KeyStore.SecretKeyEntry
    return existingKey?.secretKey ?: createKey()
}

We retrieve our key via its alias and use, if it exists, otherwise, we create a new one.