• Protect the app's data using encryption
• Use Android's Keystore to generate and store cryptographic keys

The Android Keystore system (tutorial, documentation) provides mechanisms for securing storing and for generating the cryptographic keys needed by an app. Its role as a security container is guaranteed by the fact that the keys cannot be extracted from the application's process and from the device.

Why do we need this?

• user authentication
• use the keys to secure data stored in internal storage or shared preferences
• hold the keys needed for the communication between the app and a remote device/server, e.g. if we encrypt the communication between the app and a wearable device.

The Android M (Marshmallow, API Level 23) release introduced several security related improvements and features: runtime permissions, different SSL library and updates for its Keystore API, which is now supporting also symmetric keys in addition to the asymmetric available from API 18. The way we generate these keys also changed from this level, now using KeyGenParameterSpec instead of the KeyPairGeneratorSpec.

Terminology and classes related to the Keystore system, some of them from Java Cryptography API:

• Provider
  • implementation of the Java Security API features: algorithms, key related operations
  • although we can have multiple providers, we need to use only one when creating the keystore
  • “AndroidKeyStore” is the provider introduced in API 18
  • we must specify a provider when using the Android Keystore system
• KeyPairGenerator - generates the keys based on a given algorithm and using a given provider.
• Cipher - cipher transformations
  • used for encryption, decryption, signing
  • the transformation is configured by specifying the algorithm or the combination of algorithm + mode + padding
• SecretKey — a symmetric key
• Certificate - represents certificates and also provides the public key
• PrivateKey — the key from the asymmetric algorithms
• Alias - the name of the key as we identify it inside the keystore. We provide this alias when storing the key and when retrieving it.

1. Obtain a Keystore instance with a given Provider. In our examples we will use the “AndroidKeyStore” provider.
2. Call one of the load methods, depending if we use a password for the keystore or not. If we use no password we can just call load(null). This password is unrelated to the device password if a LockScreen is setup.

 keyStore = KeyStore.getInstance("AndroidKeyStore");
 keyStore.load(inputStream, password);

To obtain the keys:

• getKey(alias, password) - the private key or the secret key
• getCertificate(alias).getPublicKey() - the public key
• containsAlias - to check if a key with a given alias exists in the keystore

If you have not provided a password to the keystore, when you get the keys just provide null as the password parameter.

To generate the keys (API > 23):

1. Obtain a KeyPairGenerator with a given algorithm and provider (list of supported algorithms)
2. Create a KeyGenParameterSpec for configuring all the parameters need for the keys (e.g. size, dates, purpose)
   • ! we can limit the usage of a key by providing a specific purpose (available purposes are defined in Builder docs)
3. Provide the key specification to the key generator using one of the initialize methods
4. Obtain a KeyPair object by calling the KeyPairGenerator's generateKeyPair method

// (1)
KeyPairGenerator generator = KeyPairGenerator.getInstance("RSA", "AndroidKeyStore");
// instead of using hardcoded strings, we can also use the KeyProperties.KEY_ALGORITHM_* variables.
 
// (2) create keys only used for signing
KeyGenParameterSpec keyGenParameterSpec = new KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_SIGN)
                .setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
                .setSignaturePaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
                .build();
// (3)                   
generator.initialize(keyGenParameterSpec);
// (4)
generator.generateKeyPair();

To store the keys:

• No need to do call anything explicitly, they are automatically saved by the generateKeyPair() of the KeyPairGenerator.

Using the keys obtained from the Keystore, we can perform cryptographic transformations on our data using the Cipher class.

In the following example we encrypt and decrypt data using a symmetric key algorithm. For an asymmetric-key algorithm the code is similar, it differs just the initialization of the Cipher and that we provide the public key for encryption and the private one for decryption.

// The KeyPairGenerator was configured with the spec:
// * KeyProperties.KEY_ALGORITHM_AES (symmetric-key algorithm)
// * KeyProperties.BLOCK_MODE_GCM
// * KeyProperties.ENCRYPTION_PADDING_NONE
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding"); //<-- provide the same configuration!
 
// Encrypt
cipher.init(Cipher.ENCRYPT_MODE, secretKey);
byte[] bytes = cipher.doFinal(data);
String encodedData = Base64.encodeToString(bytes, Base64.DEFAULT);
 
// Decrypt
cipher.init(Cipher.DECRYPT_MODE, secretKey);
byte[] encryptedData = Base64.decode(encodedData, Base64.DEFAULT);
String data = new String(cipher.doFinal(encryptedData));

In this lab we create an app that stores our pins and/or passwords. It must have the following features and UI components:

• Allow the user to input the description (purpose) of the pin/password
• Allow the user to input the pin/password
• A button to save the input data
• A button to show the description and the value of the saved pin/password
  • optional - save more than one description & pin pair and show them in a list

Target API >= 23.

To improve the app's security allow access to the app only if the device is protected by a Lock screen. Don't allow the use of the app unless it is set.

• Use the KeyguardManager system service
  • system services are obtained using the Context's method getSystemService and providing it a string representing the service, in this case the Context.KEYGUARD_SERVICE constant.
  • for API >=23 use KeyguardManager.isDeviceSecure method
• Show an Alert Dialog (tutorial) informing the users that they need to setup their Lock screen.
  • for the setPositiveButton send an implicit intent with the action DevicePolicyManager.ACTION_SET_NEW_PASSWORD
  • for the setNegativeButton close the app (call finish())

If you skip this task, the decryption might throw an Exception (see solution).

• Generate a pair of asymmetric keys with the following configuration:
  • purposes: ENCRYPT, DECRYPT
  • RSA
  • key size 2048
  • encryption paddings: RSA_PCKS1
• Generate the keys only once, not every time you start the app (check if the keys exist using the containsAlias method provided by the KeyStore
• Use the AndroidKeyStore provider when configuring the KeyStore

• When the user presses the “Save” button encrypt the data provided by the user and store them as SharedPreferences
• Initialize the Cipher with the following algorithm/mode/padding string: “RSA/ECB/PKCS1Padding”

• When the user presses the “Show pin” button load the data from SharedPreferences and decrypt it

• Save more than one description & pin pair and show them in a list.

If you generate the keys with a certain parameter configuration and then you change it, you need to clear the application's data in order for the encryption/decryption to work because you reuse the keys already existing in the keystore. You can also uninstall the app in order to clear the data. Running the app from the android studio's run button won't clear the app's data.

• Android Cryptography Guide
• Keystore tutorial
• Secure data in Android — Encryption in Android (Part 1)
• Lecture 5 - Cryptographic Providers Section