CacheWord

1. Secrets Management: how the secret key material for your app is generated, stored, and accessed
2. Passphrase Caching: store the passphrase in memory to avoid constantly prompting the user

• Strong key derivation (PBKDF2)
• Secure secret storage (AES-256 GCM)
• Persistent notification: informs the user the app data is unlocked
• Configurable timeout: after a specified time of inactivity the app locks itself
• Manual clearing: the user can forcibly lock the application
• Uses Android's Keystore on 4.x if available - Not Yet Implemented

Setup

Project Properties > Android > (Library) Add

android.library.reference.1=../CacheWord/cachewordlib

manifestmerger.enabled=true

• Android support library v4 (android-support-v4.jar; included)
• SQLCipher for Android >= v3.0.2 (included)

Integration

• Initialization Activity
• Login Activity
• Any Activity that handles sensitive data
• Encryption/Decryption wrappers
• SQLCipher Database Helper
• IOCipher Virtual File System

1. Implement the ICacheWordSubscriber interface
2. Instantiate a CacheWordHandler to assist the component

1. onCacheWordUninitialized
2. This event is called when CacheWord determines there is no saved state. Usually this occurs the first time the user runs your app. At this point there should be no sensitive data stored, because there is no secret to encrypt it with.
3. In this event you should prompt the user to create a password and the pass the new password to CacheWord with setCachedSecrets().
4. This event could also be triggered after the Application's data is cleared or reset.
5. onCacheWordLocked
6. This event signifies the secrets are unavailable or have become unavailable. It is triggered when the secrets expiration timeout is reached, or the user manually locks CacheWord.
7. You should clear all UI components and data structures containing sensitive information and perhaps show a dedicated lock screen.
8. At this stage your app should prompt the user for the passphrase and give it to CacheWord with setCachedSecrets()
9. onCacheWordOpened
10. This event is triggered when CacheWord has received valid credentials via the setCachedSecrets() method.
11. At this stage in your app you may call getCachedSecrets() to retrieve the unencrypted secrets from CacheWord.
    
    

public class MyActivity extends Activity implements ICacheWordSubscriber
{

    ...

    @Override
    public void onCacheWordUninitialized() {
        startCreatePassphraseActivity();
    }


    @Override
    public void onCacheWordLocked() {
        clearUi();
        startPassphrasePromptActivity();
    }

    @Override
    public void onCacheWordOpened() {
        decryptDataAndPopulateUi(mCacheWord.getEncryptionKey());
    }

    ...
}

class YourClass implements ICacheWordSubscriber
{
        ...
        private CacheWordHandler mCacheWord;
        ...
        public YourClass() {
            ...
            mCacheWord = new CacheWordHandler(mContext, this);
            mCacheWord.connectToService()
            ...
        }

        // Called when your object no longer wants to be notified of CacheWord events
        public goodbyeYourClass() {
            mCacheWord.disconnect()
        }
        ...
}

Common Usage Questions

• Whether to show a persistent unlocked notification
• Display options for the notification (title, message, icon, etc)
• Intent executed when the notification is clicked
• Timeout length after your app leaves the foreground
• Vibration on successful unlock
• PBKDF2 Calibration settings and minimum iteration count

Security Design Notes

• Hide all crypto decisions
• Use secure defaults
• Provide support classes for commonly used libraries that consume secret key material (e.g., SQLCipher)

• Sane cache timeouts
• Password hashing using a strong KDF (PBKDF2, and hopefully scrypt soon)
• Adaptive KDF iterations

• Aggressive zeroizing
• Using native memory (non-VM) when possible to void the GC (?)
• Never store the password in any form on disk (even a hash)

1. Run the password through PBKDF2 with a random 16 byte salt
2. Generate a random 256 bit AES key with a random 96 bit IV
3. Use the derived key to encrypt the generated key in GCM mode
4. Write the ciphertext, iv, salt, and a version tag to disk (SharedPreferences)

1. Read the ciphertext, iv, salt, and version tag from disk
2. Run the password through PBKDF2 with the salt
3. Attempt to decrypt the ciphertext with the derived key and read iv

It would seem logical to collect and store the password in an object of type java.lang.String. However, here's the caveat: Objects of type String are immutable, i.e., there are no methods defined that allow you to change (overwrite) or zero out the contents of a String after usage. This feature makes String objects unsuitable for storing security sensitive information such as user passwords. You should always collect and store security sensitive information in a char array instead.

[...]Some transient data may be kept in mutable data structures, such as char arrays, and cleared immediately after use. Clearing data structures has reduced effectiveness on typical Java runtime systems as objects are moved in memory transparently to the programmer.

Repository Information