at.favre.lib.armadillo

Class Armadillo.Builder

java.lang.Object

at.favre.lib.armadillo.Armadillo.Builder

Enclosing class:

Armadillo

public static final class Armadillo.Builder
extends java.lang.Object

Builder pattern for creating the configuration for an ArmadilloSharedPreferences instance

Method Summary

Modifier and Type	Method and Description
Armadillo.Builder	addAdditionalDecryptionProtocolConfig(EncryptionProtocolConfig config) Add new EncryptionProtocolConfig to be added to the supported decryption-config list.
ArmadilloSharedPreferences	build() Build a SharedPreferences instance
Armadillo.Builder	clearAdditionalDecryptionProtocolConfigs() Clear additionalDecryptionConfigs list.
Armadillo.Builder	compress() Compresses the content with Gzip before encrypting and writing it to shared preference.
Armadillo.Builder	compress(at.favre.lib.armadillo.Compressor compressor) Compresses the content with given compressor before encrypting and writing it to shared preference.
Armadillo.Builder	contentKeyDigest(byte[] salt) The content key digest is responsible for hashing the key in the key-value pair of a shared preference.
Armadillo.Builder	contentKeyDigest(int contentKeyOutLength) The content key digest is responsible for hashing the key in the key-value pair of a shared preference.
Armadillo.Builder	contentKeyDigest(StringMessageDigest stringMessageDigest) The content key digest is responsible for hashing the key in the key-value pair of a shared preference.
Armadillo.Builder	cryptoProtocolVersion(int version) Per default the crypto/data format version is '0', but if the behavior is changed by e.g.
Armadillo.Builder	dataObfuscatorFactory(DataObfuscator.Factory dataObfuscatorFactory) Set your own data obfuscation implementation.
Armadillo.Builder	enableDerivedPasswordCache(boolean enable) Per default every put and get operation, when using a user provided password, requires the full expensive key derivation function (KDF) to derive the key.
Armadillo.Builder	enableKitKatSupport(boolean enable) Manually enable kitkatSupport.
Armadillo.Builder	encryptionFingerprint(byte[] fingerprint) The encryption fingerprint is in important security measure.
Armadillo.Builder	encryptionFingerprint(android.content.Context context) The encryption fingerprint is in important security measure.
Armadillo.Builder	encryptionFingerprint(android.content.Context context, byte[] additionalData) The encryption fingerprint is in important security measure.
Armadillo.Builder	encryptionFingerprint(android.content.Context context, java.lang.String... additionalData) The encryption fingerprint is in important security measure.
Armadillo.Builder	encryptionFingerprint(EncryptionFingerprint fingerprint) The encryption fingerprint is in important security measure.
Armadillo.Builder	encryptionKeyStrength(int keyStrength) Set the key length for the symmetric encryption.
Armadillo.Builder	keyStretchingFunction(KeyStretchingFunction keyStretchingFunction) Set a different key derivation function for provided password.
Armadillo.Builder	password(char[] password) Provide a user password used for encrypting all of values of the SharedPreferences.
Armadillo.Builder	recoveryPolicy(boolean throwRuntimeException, boolean removeBrokenContent) The recovery policy defines how to behave when a value cannot be decrypted.
Armadillo.Builder	recoveryPolicy(RecoveryPolicy recoveryPolicy) The recovery policy defines how to behave when a value cannot be decrypted.
Armadillo.Builder	secureRandom(java.security.SecureRandom secureRandom) Provide your own SecureRandom implementation.
Armadillo.Builder	securityProvider(java.security.Provider provider) Set the security provider for most cryptographic primitives (symmetric encryption, pbkdf2, ...).
Armadillo.Builder	supportVerifyPassword(boolean supported) Enabling support verify password allows you to use ArmadilloSharedPreferences.isValidPassword() to verify the validity of the user-provided password used to initialise Armadillo.
Armadillo.Builder	symmetricEncryption(AuthenticatedEncryption authenticatedEncryption) Set your own implementation of AuthenticatedEncryption.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

encryptionFingerprint

public Armadillo.Builder encryptionFingerprint(android.content.Context context)

The encryption fingerprint is in important security measure. When no user password is provided, it is the most important source of entropy to derive the key for the encryption.

Set the default fingerprint using sources explained in EncryptionFingerprintFactory.

Parameters:

context - used to gather sources from the Android OS

Returns:

builder

encryptionFingerprint

public Armadillo.Builder encryptionFingerprint(android.content.Context context,
                                               byte[] additionalData)

The encryption fingerprint is in important security measure. When no user password is provided, it is the most important source of entropy to derive the key for the encryption.

Set the default fingerprint using sources explained in {@link EncryptionFingerprintFactory with addtional custom data. Setting this is highly recommended as it makes it more difficult for an attacker calculate the key the more random the input is.

See the README.md for explainating on what to use as additionalData.

Parameters:

context - used to gather sources from the Android OS

additionalData - provided additional custom data

Returns:

builder

encryptionFingerprint

public Armadillo.Builder encryptionFingerprint(android.content.Context context,
                                               java.lang.String... additionalData)

The encryption fingerprint is in important security measure. When no user password is provided, it is the most important source of entropy to derive the key for the encryption.

Set the default fingerprint using sources explained in EncryptionFingerprintFactory with addtional custom data. Setting this is highly recommended as it makes it more difficult for an attacker calculate the key the more random the input is.

This is the same as {@link #encryptionFingerprint(Context, byte[])} but accepts strings instead of a byte array.

See the README.md for explainating on what to use as additionalData.

Parameters:

context - used to gather sources from the Android OS

additionalData - provided additional custom data

Returns:

builder

encryptionFingerprint

public Armadillo.Builder encryptionFingerprint(EncryptionFingerprint fingerprint)

The encryption fingerprint is in important security measure. When no user password is provided, it is the most important source of entropy to derive the key for the encryption.

Provide a fully custom fingerprint implementation (or instance). Use this if you don't agree with the default implementation.

Note: Only set if you know what you are doing.

Parameters:

fingerprint - fully custom instance

Returns:

builder

encryptionFingerprint

public Armadillo.Builder encryptionFingerprint(byte[] fingerprint)

The encryption fingerprint is in important security measure. When no user password is provided, it is the most important source of entropy to derive the key for the encryption.

Provide a fully custom fingerprint byte array. Use this if you don't agree with the default implementation.

Note: Only set if you know what you are doing.

Parameters:

fingerprint - fully custom byte array containing the fingerprint

Returns:

builder

contentKeyDigest

public Armadillo.Builder contentKeyDigest(byte[] salt)

The content key digest is responsible for hashing the key in the key-value pair of a shared preference. E.g. if the key is "name" and the value "Bob", the key "name" will be hashed before it is persisted to disk.

This method will alter the salt used for that hash. Setting this is highly recommended, since it will change the default hashes of the key (so that somebody else's "name" key, won't hash to the exact same output). Recommended value: use the AndroidID, as it will be different on every app install from SDK 26+. See Settings.Secure#ANDROID_ID.

Note that changing the salt will make old data inaccessible, since the key won't match anymore.

Parameters:

salt - to be used for content key hash (should be > 16 byte)

Returns:

builder

contentKeyDigest

public Armadillo.Builder contentKeyDigest(int contentKeyOutLength)

The content key digest is responsible for hashing the key in the key-value pair of a shared preference. E.g. if the key is "name" and the value "Bob", the key "name" will be hashed before it is persisted to disk.

This is a more advanced setting. Per default a hash will be Armadillo.CONTENT_KEY_OUT_BYTE_LENGTH bytes long. If you think that is too long (wasting space) or too small (not enough entropy) modify the length with this config.

Note: Only set if you know what you are doing.

Parameters:

contentKeyOutLength - to be used for content key hash

Returns:

builder

contentKeyDigest

public Armadillo.Builder contentKeyDigest(StringMessageDigest stringMessageDigest)

The content key digest is responsible for hashing the key in the key-value pair of a shared preference. E.g. if the key is "name" and the value "Bob", the key "name" will be hashed before it is persisted to disk.

Use this to set a fully custom implementation of the digest.

Note: Only set if you know what you are doing.

Parameters:

stringMessageDigest - custom implementation

Returns:

builder

encryptionKeyStrength

public Armadillo.Builder encryptionKeyStrength(int keyStrength)

Set the key length for the symmetric encryption.

Currently there are 2 options:

• HIGH - is (or comparable) to AES with 128 bit key length
• VERY HIGH - is (or comparable) to AES with 256 bit key length

Note: Usually there is no real advantage to set it to VERY HIGH as HIGH (128 bit key length) is fully secure for the foreseeable future. VERY HIGH only adds more security margin for possible quantum computer attacks (but if you are a user which is threatened by these kinds of attacks you probably require higher degrees af protection).

Parameters:

keyStrength - HIGH (default) or VERY HIGH

Returns:

builder

securityProvider

public Armadillo.Builder securityProvider(java.security.Provider provider)

Set the security provider for most cryptographic primitives (symmetric encryption, pbkdf2, ...). Per default the default provider is used and this should be fine in most cases. Note: Only set if you know what you are doing.

Parameters:

provider - JCA provider

Returns:

builder

symmetricEncryption

public Armadillo.Builder symmetricEncryption(AuthenticatedEncryption authenticatedEncryption)

Set your own implementation of AuthenticatedEncryption. Use this if setting the security provider with securityProvider(Provider) is not enough customization. With this a any symmetric encryption algorithm might be used. Note: Only set if you know what you are doing.

Parameters:

authenticatedEncryption - to be used by the shared preferences

Returns:

builder

keyStretchingFunction

public Armadillo.Builder keyStretchingFunction(KeyStretchingFunction keyStretchingFunction)

Set a different key derivation function for provided password. Per default ArmadilloBcryptKeyStretcher is used. There is also a implementation PBKDF2 (see PBKDF2KeyStretcher. If you want to use a different function (e.g. scrypt) set the implementation here.

If you want to disable the key stretching feature you might use FastKeyStretcher here.

Parameters:

keyStretchingFunction - to be used by the shared preferences

Returns:

builder

dataObfuscatorFactory

public Armadillo.Builder dataObfuscatorFactory(DataObfuscator.Factory dataObfuscatorFactory)

Set your own data obfuscation implementation. Data obfuscation is used to disguise the persistence data format. See HkdfXorObfuscator for the default obfuscation technique. Note: Only set if you know what you are doing.

Parameters:

dataObfuscatorFactory - that creates a obfuscator with given key

Returns:

builder

secureRandom

public Armadillo.Builder secureRandom(java.security.SecureRandom secureRandom)

Provide your own SecureRandom implementation. Per default a no-provider constructor is used for SecureRandom which is the currently recommended way (https://tersesystems.com/blog/2015/12/17/the-right-way-to-use-securerandom/) Note: Only set if you know what you are doing.

Parameters:

secureRandom - implementation

Returns:

builder

recoveryPolicy

public Armadillo.Builder recoveryPolicy(boolean throwRuntimeException,
                                        boolean removeBrokenContent)

The recovery policy defines how to behave when a value cannot be decrypted.

Parameters:

throwRuntimeException - if a exception will be thrown (out of the '.get*()' method)

removeBrokenContent - if the content should be automatically be removed

Returns:

builder

recoveryPolicy

public Armadillo.Builder recoveryPolicy(RecoveryPolicy recoveryPolicy)

The recovery policy defines how to behave when a value cannot be decrypted. Use this if you want a more fine-grained strategy. This is not meant for migration however.

Parameters:

recoveryPolicy - a custom implementation

Returns:

builder

password

public Armadillo.Builder password(char[] password)

Provide a user password used for encrypting all of values of the SharedPreferences.

The password is treated as weak and is therefore subject to be stretched by the provided key derivation function with key stretching property (see keyStretchingFunction(KeyStretchingFunction). A side-effect is that putting or reading content is expensive and should not be done on the main thread.

A null password or zero length password will be treated as if no user-provided password was set.

If you want to be able to verify the password, set supportVerifyPassword(boolean) to true and use ArmadilloSharedPreferences.isValidPassword() to verify. By default, support verify password is disabled.

Parameters:

password - provided by user

Returns:

builder

supportVerifyPassword

public Armadillo.Builder supportVerifyPassword(boolean supported)

Enabling support verify password allows you to use ArmadilloSharedPreferences.isValidPassword() to verify the validity of the user-provided password used to initialise Armadillo. In order to verify the password, a known value is stored encrypted with the password the first time that Armadillo is initialised. When ArmadilloSharedPreferences.isValidPassword() is called, it tries to decrypt this value and compares it to the original value. If the values match the validation succeeds, otherwise, it fails. By default, support verify password is disabled.

Parameters:

supported - true to supported password verification, false otherwise

Returns:

builder

cryptoProtocolVersion

public Armadillo.Builder cryptoProtocolVersion(int version)

Per default the crypto/data format version is '0', but if the behavior is changed by e.g. setting a different key-stretching function or contentKey digest, a custom crypto protocol version can be set, to be able to migrate the data.

The protocol version will be used as additional associated data with the authenticated encryption.

Note: Only set if you know what you are doing.

Parameters:

version - to persist with the data

Returns:

builder

enableDerivedPasswordCache

public Armadillo.Builder enableDerivedPasswordCache(boolean enable)

Per default every put and get operation, when using a user provided password, requires the full expensive key derivation function (KDF) to derive the key. This can add up to multiple seconds if you get/put multiple values consecutively. Default is false.

To make get* calls faster, you can enable this cache, which caches the derived password. This will not speed up put* operations since every time a new salt will be created making it impossible to cache. The disadvantage is that the derived password stays in cache , therefor in memory for way longer, making it easier to read when the device is used with instrumentation tool like FRIDA (this is a more specific attack, since when the attacker has full access to the device, there is not much you can do).

Summary

• Improves performance of consecutive get calls when using expensive key stretching function and user password
• Slightly reduces security strenght, since the stretched bytes are kept in memory for longer

See DerivedPasswordCache for details of the implementation.

Parameters:

enable - caching

Returns:

builder

compress

public Armadillo.Builder compress()

Compresses the content with Gzip before encrypting and writing it to shared preference. This only makes sense if bigger structural data is persisted like long xml or json.

Returns:

builder

compress

public Armadillo.Builder compress(at.favre.lib.armadillo.Compressor compressor)

Compresses the content with given compressor before encrypting and writing it to shared preference.

Parameters:

compressor - to set

Returns:

builder

addAdditionalDecryptionProtocolConfig

public Armadillo.Builder addAdditionalDecryptionProtocolConfig(EncryptionProtocolConfig config)

Add new EncryptionProtocolConfig to be added to the supported decryption-config list. That means, if you have encrypted data with an older encryption config you may add it here to be able to decrypt it again. These configs are however never used for encryption.

To match configs EncryptionProtocolConfig.protocolVersion is used, therefore if you add a config here it must match the persisted protocolVersion (Armadillo default is Armadillo.DEFAULT_PROTOCOL_VERSION)

This may be used for migration of encryption protocols.

Parameters:

config - to be added to the list

Returns:

builder

clearAdditionalDecryptionProtocolConfigs

public Armadillo.Builder clearAdditionalDecryptionProtocolConfigs()

Clear additionalDecryptionConfigs list. See also addAdditionalDecryptionProtocolConfig(EncryptionProtocolConfig).

Returns:

builder

enableKitKatSupport

public Armadillo.Builder enableKitKatSupport(boolean enable)

Manually enable kitkatSupport. Unfortunately Android SDK 19 (KITKAT) does not fully support AES GCM mode. Therefore a backwards compatible implementation of AES (see AesCbcEncryption) which uses CBC + Encrypt-then-mac which should have a similar security strength.

The backwards compatible implementation will only be used if Build.VERSION#SDK_INT is lower or equal to 19, the default version otherwise. Additionally this implementation will be added to the additionalDecryptionConfigs so you can still decrypt the old content after upgrading to lollipop and above (uses protocol-version Armadillo.KITKAT_PROTOCOL_VERSION to mark.

Parameters:

enable - kitkat support

Returns:

builder

build

public ArmadilloSharedPreferences build()

Build a SharedPreferences instance

Returns:

shared preference with given properties