EncryptedSharedPreferences: o que é, API e como usar

O que é EncryptedSharedPreferences?

EncryptedSharedPreferences é uma classe do pacote androidx.security.crypto, apresentada no AndroidX Security 1.0.0 (2019). Ela implementa a interface SharedPreferences, mas todas as operações de escrita (putString, putInt, putBoolean, etc.) criptografam os dados antecipadamente, e as operações de leitura os descriptografam antes de retornar.

O problema das SharedPreferences comuns

As SharedPreferences padrão salvam dados em um arquivo XML no diretório do aplicativo (/data/data/package/shared_prefs/). O arquivo não é criptografado — com acesso root ao dispositivo ou durante a análise de backup, todos os dados são lidos como XML simples. Tokens de autenticação, chaves de API e dados pessoais do usuário ficam acessíveis a um invasor.

EncryptedSharedPreferences resolve esse problema no nível da biblioteca: os dados são criptografados antes de serem gravados no disco e descriptografados quando lidos. O desenvolvedor não precisa chamar funções criptográficas manualmente — a API permanece idêntica às SharedPreferences comuns.

Histórico e versões

A biblioteca AndroidX Security v1.0.0 foi lançada em dezembro de 2019. O EncryptedSharedPreferences substituiu a abordagem obsoleta de criptografia manual via Cipher + SharedPreferences. A versão estável atual é 1.1.0-alpha06 (2024), compatível com API 19+. A biblioteca faz parte do Jetpack e não requer permissões adicionais.

De acordo com o Google Security Blog (2024), o EncryptedSharedPreferences é a maneira recomendada de armazenar configurações confidenciais do aplicativo que não exigem sincronização em nuvem. Para cenários mais complexos, recomenda-se Room com criptografia SQLCipher.

Como funciona o EncryptedSharedPreferences?

EncryptedSharedPreferences usa um esquema de criptografia de dois níveis: a Master Key é armazenada no Android Keystore e chaves derivadas são usadas para criptografia de dados. Isso combina a proteção do Keystore com o desempenho da criptografia simétrica.

Esquema de criptografia: AES-256 GCM + SIV

Para valores, é usado AES-256 GCM (modo Galois/Counter) — um modo de criptografia autenticada (AEAD) que garante confidencialidade e integridade dos dados. Para chaves (nomes de parâmetros), é aplicado AES-256 SIV (RFC 5297) — criptografia determinística necessária para pesquisa de chaves sem revelar seu conteúdo.

Cada arquivo do EncryptedSharedPreferences contém pares chave-valor criptografados. A estrutura do arquivo inclui: primeiro um cabeçalho com metadados (versão, identificador de chave), depois uma lista de entradas criptografadas. O arquivo não é XML válido e não pode ser lido por editores de texto.

MasterKey e KeyStore

A classe MasterKey é responsável por criar e gerenciar uma chave mestra de 256 bits armazenada no Android Keystore. O MasterKey.Builder permite configurar: tipo de armazenamento (Keystore ou software), proteção biométrica e tempo de vida da chave. Por padrão, a chave mestra é gerada no Android Keystore com o algoritmo AES/GCM/NoPadding.

import androidx.security.crypto.MasterKey
import androidx.security.crypto.EncryptedSharedPreferences

fun getEncryptedPrefs() {
    val masterKey = MasterKey.Builder(context)
        .setKeyScheme(MasterKey.AES256_GCM_SPEC)
        .build()

    val prefs = EncryptedSharedPreferences.create(
        context,
        "secure_prefs",
        masterKey,
        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
    )
}

Configuração da criptografia

EncryptedSharedPreferences.create aceita cinco parâmetros: contexto, nome do arquivo, chave mestra, esquema de criptografia de chaves e esquema de criptografia de valores. A escolha dos esquemas afeta o desempenho e o nível de segurança.

Esquemas de criptografia de chaves

AES256_SIV — criptografia determinística: chaves idênticas sempre produzem o mesmo texto cifrado. Isso é necessário para pesquisa de chaves (SharedPreferences.getX(key)). Desvantagem: um invasor pode determinar quais chaves estão sendo usadas comparando textos cifrados repetidos. AES256_SIV2 — uma versão melhorada com randomização adicional.

Para valores, é usado AES256_GCM. O GCM adiciona um IV de 12 bytes (vetor de inicialização) e um tag de autenticação de 16 bytes a cada valor. Isso fornece confidencialidade (ninguém pode ler o valor) e autenticação (ninguém pode adulterar o valor sem ser detectado).

Proteção biométrica da chave mestra

O método setUserAuthenticationRequired(true) no MasterKey.Builder requer confirmação biométrica antes de recuperar a chave mestra do Keystore. Isso adiciona uma camada extra: mesmo se o aplicativo estiver sendo executado em um dispositivo desbloqueado, um invasor não pode ler o EncryptedSharedPreferences sem Face ID ou Touch ID.

Importante: com setUserAuthenticationRequired, a chave mestra se torna indisponível se o usuário alterar ou remover os dados biométricos. É necessário lidar com KeyPermanentlyInvalidatedException e criar uma nova chave mestra com migração de dados.

fun createBiometricKey(): MasterKey {
    return MasterKey.Builder(context)
        .setKeyScheme(MasterKey.AES256_GCM_SPEC)
        .setUserAuthenticationRequired(true)
        .setRequestStrongBoxBacked(true)
        .build()
}

fun writeSecureToken(token: String) {
    try {
        prefs.edit().putString("auth_token", token).apply()
    } catch (e: KeyPermanentlyInvalidatedException) {
        // A biometria mudou — é necessário recriar a chave
    }
}

Exemplo de uso em Kotlin

Vamos ver um exemplo completo de integração do EncryptedSharedPreferences em um aplicativo Android usando Kotlin. A biblioteca androidx.security:security-crypto é adicionada via Gradle.

Adicionando a dependência

No arquivo build.gradle (app), adicione: implementation "androidx.security:security-crypto:1.1.0-alpha06". Para projetos Kotlin, kotlin-stdlib também é necessário. A inicialização do MasterKey ocorre uma vez, normalmente em Application.onCreate ou através de um contêiner DI.

Lendo e escrevendo dados

Após criar uma instância do EncryptedSharedPreferences, a API não difere das SharedPreferences comuns. edit() retorna um Editor, todos os métodos (putString, getString, putBoolean, getBoolean) funcionam da mesma forma. A única diferença é interna: os dados são criptografados ao escrever e descriptografados ao ler.

class AuthRepository(context: Context) {
    private val prefs = createEncryptedPrefs(context)

    fun saveCredentials(login: String, password: String) {
        prefs.edit()
            .putString("login", login)
            .putString("password", password)
            .apply()
    }

    fun getToken(): String? {
        return prefs.getString("auth_token", null)
    }

    fun clearAll() {
        prefs.edit().clear().apply()
    }
}

Migração de SharedPreferences comuns

Para migrar dados existentes de SharedPreferences não criptografadas para EncryptedSharedPreferences, é necessário: ler todos os dados do arquivo antigo, criar um novo EncryptedSharedPreferences, escrever todos os dados e excluir o arquivo antigo. O Google não fornece um migrador integrado — o desenvolvedor o implementa manualmente.

Comparação com SharedPreferences comuns

A escolha entre SharedPreferences e EncryptedSharedPreferences depende do tipo de dado armazenado. Para configurações de interface (tema, idioma, ordenação), as SharedPreferences comuns são suficientes. Para informações confidenciais (tokens, senhas, chaves), o EncryptedSharedPreferences é obrigatório.

Desempenho

EncryptedSharedPreferences é mais lento que o comum devido às operações criptográficas. Escrever um único valor de string leva ~5-15 ms (dependendo do tamanho dos dados e da aceleração de hardware AES). A leitura leva 2-5 ms. Para a maioria dos aplicativos isso é imperceptível, mas para operações em lote (migração, restauração) use apply() em vez de commit().

Segurança

As SharedPreferences comuns não fornecem nenhuma proteção criptográfica: o arquivo XML pode ser lido por qualquer processo com acesso root ou via adb backup. O EncryptedSharedPreferences criptografa os dados no nível do aplicativo, e a chave mestra é armazenada no Android Keystore com proteção de hardware opcional (StrongBox).

Quando escolher EncryptedSharedPreferences

Use EncryptedSharedPreferences para armazenar: tokens de atualização OAuth, chaves de API para serviços externos, email ou número de telefone do usuário e configurações confidenciais do aplicativo (PIN, flags de autenticação). O EncryptedSharedPreferences não é adequado para armazenar dados biométricos ou documentos grandes — use EncryptedFile ou Room com SQLCipher.

A regra geral: se um vazamento de dados prejudicar o usuário ou o negócio — use EncryptedSharedPreferences. Se os dados forem apenas cosméticos (tema, idioma, ordenação) — SharedPreferences comuns. Faz sentido implementar o EncryptedSharedPreferences desde o início, sem refatoração: substituí-lo em um projeto existente exigirá migração e tratamento de dados antigos não criptografados.

Lembre-se de que o EncryptedSharedPreferences não protege os dados durante a execução do aplicativo — apenas no disco. Se um invasor tiver acesso à memória do processo, os dados descriptografados podem ser interceptados. Use proteção adicional: ProGuard/DexGuard para ofuscação.