安全
安全 · androidx.security
Security Crypto：加密偏好与文件1.1.0-rc01
EncryptedSharedPreferences 与 EncryptedFile 的初始化、写入与读取。
最后更新 2026-08-01
复制即用
加密 SharedPreferences：
import android.content.Context
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey
val masterKey = MasterKey.Builder(context)
.setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
.build()
val prefs = EncryptedSharedPreferences.create(
context,
"secret_prefs",
masterKey,
EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
)
prefs.edit().putString("token", "abc").apply()
val token = prefs.getString("token", null)加密文件：
import androidx.security.crypto.EncryptedFile
import androidx.security.crypto.MasterKey
val encryptedFile = EncryptedFile.Builder(
context,
File(context.filesDir, "secret.txt"),
masterKey,
EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB,
).build()
// 写入
encryptedFile.openFileOutput().use { output ->
output.write("机密内容".toByteArray())
}
// 读取
encryptedFile.openFileInput().use { input ->
val content = input.readBytes().toString(Charsets.UTF_8)
}加密方案选择
| 容器 | 加密方案 | 用途 |
|---|---|---|
EncryptedSharedPreferences | key: AES256_SIV，value: AES256_GCM | 小体积键值对（token、设置） |
EncryptedFile | AES256_GCM_HKDF_4KB | 任意大小的文件 |
Keystore 一致性校验
MasterKey.Builder 支持 KeyUniquenessScheme，避免同一 Keystore 条目被复用：
val masterKey = MasterKey.Builder(context)
.setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
.setKeyUniquenessScheme(MasterKey.KeyUniquenessScheme.SECURE)
.build()常见陷阱
- 模拟器/无 Keystore 设备：
MasterKey构建失败抛异常，需 try-catch 并降级（如提示用户）。 - 清除应用数据 = 丢数据：MasterKey 在 Keystore，但加密数据在 filesDir/SharedPreferences 里，清数据两样都没了。
- 主线程卡顿：首次使用触发 Keystore 初始化，放后台线程（
withContext(Dispatchers.IO)）。 - 不要把密钥写进源码：用 Keystore 管理，别硬编码 AES key。
- 升级主密钥：更换
setKeyScheme会导致旧数据无法解密，需要迁移。
与明文存储对比
| 场景 | 明文 SharedPreferences | EncryptedSharedPreferences |
|---|---|---|
| 读取速度 | 快 | 慢（解密开销） |
| root 后安全性 | 直接可见 | Keystore 保护 |
| 适用 | 非敏感 UI 状态 | token、密钥、个人信息 |
要点
MasterKey由 Android Keystore 保护，不落盘明文。- 必须先成功构建
MasterKey再创建加密容器；设备不支持时（如模拟器缺 Keystore）会抛异常。 EncryptedSharedPreferences的 key 和 value 可分别选加密方案。- 首次使用时可能触发 Keystore 初始化，建议放后台线程。