linkArmadillo - Encrypted Shared Preference

Armadillo Logo

A shared preference implementation for secret data providing confidentiality, integrity and authenticity. Per default uses AES-GCM, BCrypt and HKDF as cryptographic primitives.

Download Build Status Javadocs Coverage Status Maintainability

Important Notice: If you migrate to v0.6.0 and use a user password and default key stretching function migration is needed due to a security issue. See migration guide in the changelog for v0.6.0


linkSecurity Summary

linkQuick Start

Add the following to your dependencies (add jcenter to your repositories if you haven't)

1compile 'at.favre.lib:armadillo:x.y.z'

A very minimal example

1SharedPreferences preferences = Armadillo.create(context, "myPrefs")

2 .encryptionFingerprint(context)

3 .build();


5preferences.edit().putString("key1", "stringValue").commit();

6String s = preferences.getString("key1", null);

linkAdvanced Example

The following example shows some of the configurations available to the developer:

1String userId = ...

2SharedPreferences preferences = Armadillo.create(context, "myCustomPreferences")

3 .password("mySuperSecretPassword".toCharArray()) //use user provided password

4 .securityProvider(Security.getProvider("BC")) //use bouncy-castle security provider

5 .keyStretchingFunction(new PBKDF2KeyStretcher()) //use PBKDF2 as user password kdf

6 .contentKeyDigest(Bytes.from(getAndroidId(context)).array()) //use custom content key digest salt

7 .secureRandom(new SecureRandom()) //provide your own secure random for salt/iv generation

8 .encryptionFingerprint(context, userId.getBytes(StandardCharsets.UTF_8)) //add the user id to fingerprint

9 .supportVerifyPassword(true) //enables optional password validation support `.isValidPassword()`

10 .enableKitKatSupport(true) //enable optional kitkat support

11 .enableDerivedPasswordCache(true) //enable caching for derived password making consecutive getters faster

12 .build();

A xml file named like f1a4e61ffb59c6e6a3d6ceae9a20cb5726aade06.xml will be created with the resulting data looking something like that after the first put operation:

1<?xml version='1.0' encoding='utf-8' standalone='yes' ?>


3 <!-- storage random salt -->

4 <string name="585d6f0f415682ace841fb50d5980d60ed23a2ef">riIPjrL2WRfoh8QJXu7fWk4GGeAKlQoJl9ofABHZKlc=</string>

5 <!-- 'key1':'stringValue' -->

6 <string name="152b866fd2d63899678c21f247bb6df0d2e38072">AAAAABD/8an1zfovjJB/2MFOT9ncAAAAJaf+Z9xgzwXzp1BqTsVMnRZxR/HfRcO8lEhyKpL17QmZ5amwAYQ=</string>



linkKitKat Support

Unfortunately Android SDK 19 (KITKAT) does not fully support AES GCM mode. Therefore a backwards compatible implementation of AES using CBC with Encrypt-then-MAC can be used to support this library on older devices. This should provide the same security strength as the GCM version, however the support must be enabled manually:

1SharedPreferences preferences = Armadillo.create(context, "myCustomPreferences")

2 .enableKitKatSupport(true)

3 ...

4 .build();

In this mode, if on a KitKat device the backwards-compatible implementation is used, the default AES-GCM version otherwise. Upgrading to a newer OS version the content should still be decryptable, while newer content will then be encrypted with the AES-GCM version.


linkDesign Choices

linkUser provided Passwords

A high entropy value not known to any system but the user is a good and strong base for a cryptographic key. Unfortunately user-based passwords are often weak (low-entropy). To mitigate that fact and help preventing easy brute-forcing key derivation functions with key stretching properties are used. These functions calculate pseudo-random data from it's source material which requires mandatory work.

The following implementations are available:

It is possible to provide any KDF implementation to the storage with providing a custom KeyStretchingFunction implementation.

Note, if you use key stretching put/get operations will get very slow (depeding on the work factor of course), so consider accessing the store in a background thread.

linkEncryption Fingerprint

This store bases part of it's security on so called fingerprinting. That basically means, during runtime entropy from e.g. the device, system or other parts are used to create a cryptographic key with which the data is encrypted. It basically is encryption with a semi-secret key.

This has the following benefits:

This store has a default implementation of EncryptionFingerprint which can only use generic data. In detail the following properties are incorporated:

linkEnhancing the Strength of the Encryption Fingerprint

The security of this mechanism increases considerably if the user adds it's own data. Here are some suggestions:

linkKey Derivation Process

The cryptographic key used to encrypt the data is composed of the following parts:

screenshot key derivation

The concatenated key material will be derived and stretched to the desired length with HKDF derivation function.

linkPersistence Profile


The key is hashed with HKDF (which uses Hmac with Sha512 internally) expanded to a 20 byte hash which will be encoded with base16 (hex). The key generation is salted by the encryption fingerprint, so different shared preferences will generate different hashes for the same keys.


The diagram below illustrates the used data format. To disguise the format a little bit it will be obfuscated by a simple xor cipher.

screenshot gallery

The resulting data will be encoded with base64 and looks like this in the shared preferences xml:

1<?xml version='1.0' encoding='utf-8' standalone='yes' ?>


3 <string name="39e3e4f83dda81c44f8a9063196b28b3d5091fca">hwbchXlqDAQcig6q3UWxdbOb2wouDGGwjUGNIzREiy0=</string>

4 <string name="62ef41ac992322bdd669e96799c12a66a2cce111">AAAAABAAajtOaVCq5yqu1TPxgLu2AAAAqUTxgPcAM6lyNTGgy7ZAoCjqcCdtxT6T</string>


linkDigital Signatures

linkSigned Commits

All tags and commits by me are signed with git with my private key:

1GPG key ID: 4FDF85343912A3AB

2Fingerprint: 2FB392FB05158589B767960C4FDF85343912A3AB


Assemble the lib with the following command

1./gradlew :armadillo:assemble

The .aar files can then be found in /armadillo/build/outputs/aar folder

linkLibraries & Credits

linkSimilar Projects:

linkFurther Reading


Copyright 2017 Patrick Favre-Bulle

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Armadillo - Encrypted Shared PreferenceFeaturesSecurity SummaryQuick StartAdvanced ExampleKitKat SupportDescriptionDesign ChoicesUser provided PasswordsEncryption FingerprintEnhancing the Strength of the Encryption FingerprintKey Derivation ProcessPersistence ProfileKeyContentDigital SignaturesSigned CommitsBuildLibraries & CreditsSimilar Projects:Further ReadingLicense



Patrick Favre-Bulle 2020