Session Storage

This guide covers securely storing and restoring Privacy Boost sessions using Android Keystore, expanding on the persistence options in Key Management.

Why Keystore?

Session data includes sensitive cryptographic keys. Android Keystore provides:

Hardware-backed encryption (TEE/Secure Element)
Key material never leaves secure hardware
Biometric authentication support
Protection against extraction

There are two ways to use it. The SDK can own the vault in Keystore-backed storage itself through a KeychainDelegate, which is the path described next, or the app can export the session and store it with its own code, which the rest of this guide covers.

SDK-Managed Persistence

Select persistenceStorage = StorageBackend.OS_KEYCHAIN and an unlock method, and register a KeychainDelegate before constructing the SDK. PrivacyBoostDefaults.create(context, config) registers DefaultKeystoreDelegate(context) for you unless the app already registered its own, then constructs the SDK:

import com.privacyboost.defaults.PrivacyBoostDefaults
import com.privacyboost.sdk.*

val config = PrivacyBoostConfig(
    serverUrl = "https://indexer.example.com",
    chainId = null,
    shieldContractAddress = null,
    wethContractAddress = null,
    teePublicKey = null,
    appId = "my-app",
    persistenceStorage = StorageBackend.OS_KEYCHAIN,
    persistenceUnlock = UnlockMethod.PIN
)

val sdk = PrivacyBoostDefaults.create(applicationContext, config)

DefaultKeystoreDelegate stores entries in EncryptedSharedPreferences (privacyboost_vault unless you pass another preferenceName) under an Android Keystore master key. To use your own implementation instead, implement KeychainDelegate and register it yourself:

registerKeychainDelegate(MyKeystoreDelegate(applicationContext))
val sdk = PrivacyBoost(config)

registerKeychainDelegate takes an optional service that namespaces the vault items. Omit it and the SDK uses its own name; pass your own when two SDK instances share the process, so their items cannot collide. The registration is process-wide: do it once, before the first PrivacyBoost whose config selects OS_KEYCHAIN, and note that a later call replaces the delegate for every instance. Construction throws SDKError.ConfigError naming register_keychain_delegate when no delegate is registered; hasKeychainDelegate() tells you whether one is. LOCAL_STORAGE and INDEXED_DB are browser backends and are rejected on Android, as is PASSKEY unlock.

Unlock methods

`persistenceUnlock`	On the next launch
`UnlockMethod.PIN`, `UnlockMethod.PASSWORD`	`authenticate` returns `AuthResult.CredentialRequired`; collect the credential and call `submitCredential`.
`UnlockMethod.BIOMETRIC`	The vault is written to a second store whose Keystore key requires a class-3 biometric (`BIOMETRIC_STRONG`) and is invalidated by new enrollment. There is no credential challenge: `authenticate` asks the wallet for one signature to derive the vault key and returns `Authenticated`.
`UnlockMethod.NONE`	One wallet signature, then `Authenticated`.

DefaultKeystoreDelegate does not show a biometric prompt itself. With BIOMETRIC, complete your own class-3 BiometricPrompt immediately before authenticate, on the first launch as well as later ones: the gated store stays reachable for authValiditySeconds (30 by default) after a successful prompt, and outside that window the delegate throws rather than returning nothing.

Unlocking on the next launch

With PIN or PASSWORD, the first launch returns CredentialRequired with challenge.action == CredentialAction.SETUP, where the user chooses the credential, and every later launch returns it with CredentialAction.UNLOCK. submitCredential completes the login either way and can be retried after a wrong credential without calling authenticate again:

suspend fun signIn(): LoginResult {
    val result = withContext(Dispatchers.IO) {
        sdk.authenticate(
            wallet = walletDelegate,
            keySource = KeySource.WalletDerived,   // ignored once a vault exists
            tokenProvider = null
        )
    }

    return when (result) {
        is AuthResult.Authenticated -> result.loginResult
        is AuthResult.CredentialRequired -> {
            val pin = promptForPin(isNew = result.challenge.action == CredentialAction.SETUP)
            withContext(Dispatchers.IO) { sdk.submitCredential(pin) }
        }
        else -> {
            // MnemonicGenerated, RecoveryRequired, AccountCreationRequired:
            // see Getting Started.
            throw IllegalStateException("unhandled auth result: $result")
        }
    }
}

The vault survives logout() and lock(); call deleteVault() to erase it, for example when the user removes the account from the device. Auto-lock below wipes the decrypted keys on a timer and sends the user through this same unlock on the next key access.

EncryptedSharedPreferences

The simplest approach using AndroidX Security:

Setup

Add dependency:

dependencies {
    implementation("androidx.security:security-crypto:1.1.0-alpha06")
}

Implementation

import android.content.Context
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey
import com.google.gson.Gson

class SessionStorage(context: Context) {

    private val masterKey = MasterKey.Builder(context)
        .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
        .build()

    private val sharedPrefs = EncryptedSharedPreferences.create(
        context,
        "privacy_boost_session",
        masterKey,
        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
    )

    private val gson = Gson()

    fun saveSession(session: ExportedSession) {
        val json = gson.toJson(session)
        sharedPrefs.edit()
            .putString(KEY_SESSION, json)
            .apply()
    }

    fun loadSession(): ExportedSession? {
        val json = sharedPrefs.getString(KEY_SESSION, null) ?: return null
        return try {
            gson.fromJson(json, ExportedSession::class.java)
        } catch (e: Exception) {
            null
        }
    }

    fun deleteSession() {
        sharedPrefs.edit()
            .remove(KEY_SESSION)
            .apply()
    }

    fun hasSession(): Boolean {
        return sharedPrefs.contains(KEY_SESSION)
    }

    companion object {
        private const val KEY_SESSION = "session_data"
    }
}

Biometric Authentication

Add biometric protection for session access:

Setup

Add dependencies:

dependencies {
    implementation("androidx.biometric:biometric:1.1.0")
}

BiometricSessionStorage

import android.content.Context
import android.security.keystore.KeyGenParameterSpec
import android.security.keystore.KeyProperties
import androidx.biometric.BiometricManager
import androidx.biometric.BiometricPrompt
import androidx.core.content.ContextCompat
import androidx.fragment.app.FragmentActivity
import java.security.KeyStore
import javax.crypto.Cipher
import javax.crypto.KeyGenerator
import javax.crypto.SecretKey
import javax.crypto.spec.GCMParameterSpec

class BiometricSessionStorage(private val context: Context) {

    private val keyStore = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
    private val gson = Gson()

    // MARK: - Biometric Availability

    fun isBiometricAvailable(): Boolean {
        val biometricManager = BiometricManager.from(context)
        return when (biometricManager.canAuthenticate(BiometricManager.Authenticators.BIOMETRIC_STRONG)) {
            BiometricManager.BIOMETRIC_SUCCESS -> true
            else -> false
        }
    }

    // MARK: - Save with Biometrics

    fun saveSession(
        activity: FragmentActivity,
        session: ExportedSession,
        onSuccess: () -> Unit,
        onError: (String) -> Unit
    ) {
        val executor = ContextCompat.getMainExecutor(context)

        val callback = object : BiometricPrompt.AuthenticationCallback() {
            override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
                try {
                    val cipher = result.cryptoObject?.cipher
                        ?: throw Exception("No cipher available")

                    val json = gson.toJson(session)
                    val encrypted = cipher.doFinal(json.toByteArray())
                    val iv = cipher.iv

                    // Store encrypted data and IV
                    getPrefs().edit()
                        .putString(KEY_ENCRYPTED_SESSION, encrypted.toBase64())
                        .putString(KEY_IV, iv.toBase64())
                        .apply()

                    onSuccess()
                } catch (e: Exception) {
                    onError(e.message ?: "Encryption failed")
                }
            }

            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                onError(errString.toString())
            }

            override fun onAuthenticationFailed() {
                // Called when biometric is valid but not recognized
            }
        }

        val prompt = BiometricPrompt(activity, executor, callback)

        val promptInfo = BiometricPrompt.PromptInfo.Builder()
            .setTitle("Save Session")
            .setSubtitle("Authenticate to save your Privacy Boost session")
            .setNegativeButtonText("Cancel")
            .setAllowedAuthenticators(BiometricManager.Authenticators.BIOMETRIC_STRONG)
            .build()

        // Get cipher for encryption
        val cipher = getCipherForEncryption()
        prompt.authenticate(promptInfo, BiometricPrompt.CryptoObject(cipher))
    }

    // MARK: - Load with Biometrics

    fun loadSession(
        activity: FragmentActivity,
        onSuccess: (ExportedSession) -> Unit,
        onError: (String) -> Unit
    ) {
        val prefs = getPrefs()
        val encryptedBase64 = prefs.getString(KEY_ENCRYPTED_SESSION, null)
        val ivBase64 = prefs.getString(KEY_IV, null)

        if (encryptedBase64 == null || ivBase64 == null) {
            onError("No session found")
            return
        }

        val executor = ContextCompat.getMainExecutor(context)

        val callback = object : BiometricPrompt.AuthenticationCallback() {
            override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
                try {
                    val cipher = result.cryptoObject?.cipher
                        ?: throw Exception("No cipher available")

                    val encrypted = encryptedBase64.fromBase64()
                    val decrypted = cipher.doFinal(encrypted)
                    val json = String(decrypted)

                    val session = gson.fromJson(json, ExportedSession::class.java)
                    onSuccess(session)
                } catch (e: Exception) {
                    onError(e.message ?: "Decryption failed")
                }
            }

            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                onError(errString.toString())
            }
        }

        val prompt = BiometricPrompt(activity, executor, callback)

        val promptInfo = BiometricPrompt.PromptInfo.Builder()
            .setTitle("Access Session")
            .setSubtitle("Authenticate to access your Privacy Boost session")
            .setNegativeButtonText("Cancel")
            .setAllowedAuthenticators(BiometricManager.Authenticators.BIOMETRIC_STRONG)
            .build()

        // Get cipher for decryption
        val iv = ivBase64.fromBase64()
        val cipher = getCipherForDecryption(iv)
        prompt.authenticate(promptInfo, BiometricPrompt.CryptoObject(cipher))
    }

    // MARK: - Key Management

    private fun getOrCreateKey(): SecretKey {
        keyStore.getKey(KEY_ALIAS, null)?.let {
            return it as SecretKey
        }

        val keyGenerator = KeyGenerator.getInstance(
            KeyProperties.KEY_ALGORITHM_AES,
            "AndroidKeyStore"
        )

        val keySpec = KeyGenParameterSpec.Builder(
            KEY_ALIAS,
            KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
        )
            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
            .setKeySize(256)
            .setUserAuthenticationRequired(true)
            .setUserAuthenticationParameters(
                0, // Timeout (0 = every use)
                KeyProperties.AUTH_BIOMETRIC_STRONG
            )
            .setInvalidatedByBiometricEnrollment(true)
            .build()

        keyGenerator.init(keySpec)
        return keyGenerator.generateKey()
    }

    private fun getCipherForEncryption(): Cipher {
        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
        cipher.init(Cipher.ENCRYPT_MODE, getOrCreateKey())
        return cipher
    }

    private fun getCipherForDecryption(iv: ByteArray): Cipher {
        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
        val spec = GCMParameterSpec(128, iv)
        cipher.init(Cipher.DECRYPT_MODE, getOrCreateKey(), spec)
        return cipher
    }

    private fun getPrefs() = context.getSharedPreferences(
        "privacy_boost_biometric",
        Context.MODE_PRIVATE
    )

    fun deleteSession() {
        getPrefs().edit().clear().apply()
        keyStore.deleteEntry(KEY_ALIAS)
    }

    fun hasSession(): Boolean {
        return getPrefs().contains(KEY_ENCRYPTED_SESSION)
    }

    companion object {
        private const val KEY_ALIAS = "privacy_boost_session_key"
        private const val KEY_ENCRYPTED_SESSION = "encrypted_session"
        private const val KEY_IV = "iv"
    }
}

// Extension functions
private fun ByteArray.toBase64(): String =
    android.util.Base64.encodeToString(this, android.util.Base64.NO_WRAP)

private fun String.fromBase64(): ByteArray =
    android.util.Base64.decode(this, android.util.Base64.NO_WRAP)

Usage in Repository

class PrivacyBoostRepository(
    private val sdk: PrivacyBoost,
    private val sessionStorage: SessionStorage,
    private val biometricStorage: BiometricSessionStorage
) {

    suspend fun restoreSession(): Boolean = withContext(Dispatchers.IO) {
        // Try regular storage first
        sessionStorage.loadSession()?.let { session ->
            return@withContext try {
                sdk.importSession(session)
            } catch (e: Exception) {
                sessionStorage.deleteSession()
                false
            }
        }
        false
    }

    fun restoreSessionWithBiometrics(
        activity: FragmentActivity,
        onSuccess: () -> Unit,
        onError: (String) -> Unit
    ) {
        if (!biometricStorage.isBiometricAvailable()) {
            onError("Biometrics not available")
            return
        }

        biometricStorage.loadSession(
            activity = activity,
            onSuccess = { session ->
                try {
                    val success = sdk.importSession(session)
                    if (success) onSuccess() else onError("Session expired")
                } catch (e: Exception) {
                    onError(e.message ?: "Import failed")
                }
            },
            onError = onError
        )
    }

    fun saveCurrentSession(useBiometrics: Boolean = false, activity: FragmentActivity? = null) {
        val session = sdk.exportSession() ?: return

        if (useBiometrics && activity != null && biometricStorage.isBiometricAvailable()) {
            biometricStorage.saveSession(
                activity = activity,
                session = session,
                onSuccess = { /* Saved */ },
                onError = { /* Fall back to regular storage */
                    sessionStorage.saveSession(session)
                }
            )
        } else {
            sessionStorage.saveSession(session)
        }
    }

    fun clearSession() {
        sessionStorage.deleteSession()
        biometricStorage.deleteSession()
    }
}

ViewModel Integration

@HiltViewModel
class AuthViewModel @Inject constructor(
    private val repository: PrivacyBoostRepository
) : ViewModel() {

    private val _sessionRestored = MutableStateFlow(false)
    val sessionRestored: StateFlow<Boolean> = _sessionRestored

    fun tryRestoreSession() {
        viewModelScope.launch {
            _sessionRestored.value = repository.restoreSession()
        }
    }

    fun restoreWithBiometrics(activity: FragmentActivity) {
        repository.restoreSessionWithBiometrics(
            activity = activity,
            onSuccess = { _sessionRestored.value = true },
            onError = { /* Show error */ }
        )
    }

    fun saveSession(useBiometrics: Boolean, activity: FragmentActivity?) {
        repository.saveCurrentSession(useBiometrics, activity)
    }
}

Auto-lock

Persisting a session keeps the encrypted vault on disk; auto-lock bounds how long the decrypted keys stay in memory. Two optional PrivacyBoostConfig fields drive it, both in seconds:

idleTtlSecs: how long the keys may go unused before the SDK wipes them.
absoluteTtlSecs: how long after an unlock the SDK wipes them, regardless of activity.

null or 0u disables the respective timer, and both default to null. The timers are checked lazily, on the next key access: once one has elapsed, that access zeroizes the resident keys and throws SDKError.NotAuthenticated. They bound key use rather than key residency, so a screen that needs the keys gone at a fixed time should call lock() from its own timer.

val config = PrivacyBoostConfig(
    serverUrl = "https://indexer.example.com",
    chainId = null,
    shieldContractAddress = null,
    wethContractAddress = null,
    teePublicKey = null,
    appId = "my-app",
    persistenceStorage = StorageBackend.OS_KEYCHAIN,
    persistenceUnlock = UnlockMethod.BIOMETRIC,
    idleTtlSecs = 300u,          // wipe keys after 5 minutes without use
    absoluteTtlSecs = 43_200u    // and 12 hours after unlock, no matter what
)

lock() does the same on demand. It zeroizes the key material and drops the session JWT but keeps the persisted vault, which makes it the right call when the app moves to the background:

import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleEventObserver
import androidx.lifecycle.ProcessLifecycleOwner

ProcessLifecycleOwner.get().lifecycle.addObserver(
    LifecycleEventObserver { _, event ->
        if (event == Lifecycle.Event.ON_STOP) sdk.lock()
    }
)

To unlock, call authenticate again. With a persisted vault the SDK reopens it instead of re-deriving keys: PIN and password vaults return CredentialRequired, and the other unlock methods complete inside authenticate. Compare clearSession(), which drops the JWT but leaves the keys in memory for a quick re-auth, and logout(), which ends the session entirely. Chain-context handles created with createChainContext share the resident keys, so auto-lock and lock() apply to them too, but each keeps its own JWT; call clearSession() on the handle to drop it.

Security Best Practices

Use BIOMETRIC_STRONG - Requires Class 3 biometrics
Set invalidatedByBiometricEnrollment - Invalidate key if new biometric enrolled
No timeout - Require auth every time for sensitive data
Handle key invalidation - Clear session if key is invalidated
Don’t store unencrypted - Always encrypt sensitive data

Next Steps

API Reference - Complete API documentation
Android Getting Started - Jetpack Compose integration

Quickstart

Setup

SDKs

Session storage

Session Storage

Why Keystore?

SDK-Managed Persistence

Unlock methods

Unlocking on the next launch

EncryptedSharedPreferences

Setup

Implementation

Biometric Authentication

Setup

BiometricSessionStorage

Usage in Repository

ViewModel Integration

Auto-lock

Security Best Practices

Next Steps

​Session Storage

​Why Keystore?

​SDK-Managed Persistence

​Unlock methods

​Unlocking on the next launch

​EncryptedSharedPreferences

​Setup

​Implementation

​Biometric Authentication

​Setup

​BiometricSessionStorage

​Usage in Repository

​ViewModel Integration

​Auto-lock

​Security Best Practices

​Next Steps

Session Storage

Why Keystore?

SDK-Managed Persistence

Unlock methods

Unlocking on the next launch

EncryptedSharedPreferences

Setup

Implementation

Biometric Authentication

Setup

BiometricSessionStorage

Usage in Repository

ViewModel Integration

Auto-lock

Security Best Practices

Next Steps