Android Jetpack Security 使用入门指南

一、核心功能与使用场景

Jetpack Security (Security) 提供了一套标准化的数据加密工具，用于保护本地敏感数据。主要使用场景包括：

1. 敏感数据存储

• 加密 SharedPreferences 数据（如用户令牌、密码）
• 加密本地文件（如用户聊天记录、财务信息）

2. 安全密钥管理

• 基于 Android 密钥库系统（KeyStore）管理加密密钥
• 支持生物认证（指纹/人脸）绑定密钥访问

3. 安全通信

• 加密网络请求中的敏感字段（需结合网络库）

二、基础使用示例

1. 配置依赖

// build.gradle (app)
dependencies {
    implementation "androidx.security:security-crypto:1.1.0-alpha06"
    // 支持Tink加密
    implementation "androidx.security:security-crypto-ktx:1.1.0-alpha06"
}

2. 加密 SharedPreferences(示例代码)

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

val encryptedPrefs = EncryptedSharedPreferences.create(
    context,
    "secret_prefs",
    masterKey,
    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
)

// 写入加密数据
encryptedPrefs.edit().putString("api_token", "s3cr3t_t0k3n").apply()

// 读取数据
val token = encryptedPrefs.getString("api_token", "")

3. 加密文件(示例代码)

val file = File(context.filesDir, "encrypted_data.txt")

val encryptedFile = EncryptedFile.Builder(
    file,
    context,
    masterKey,
    EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB
).build()

// 写入加密文件
encryptedFile.openFileOutput().use { output ->
    output.write("Confidential info".toByteArray())
}

// 读取加密文件
encryptedFile.openFileInput().use { input ->
    val content = input.readBytes().toString(Charsets.UTF_8)
}

三、高级功能与安全配置

1. 生物认证绑定密钥

val advancedMasterKey = MasterKey.Builder(context)
    .setUserAuthenticationRequired(true)
    .setUserAuthenticationValidityDurationSeconds(30) // 生物认证有效期
    .setKeyGenParameterSpec(KeyGenParameterSpec.Builder(
        "biometric_key",
        KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
    ).apply {
        setUserAuthenticationParameters(0, KeyProperties.AUTH_BIOMETRIC_STRONG)
        setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
    }.build())
    .build()

2. 自定义密钥别名（避免冲突）

val customKeyAlias = "com.example.app.encryption_key"

val customMasterKey = MasterKey.Builder(context, customKeyAlias)
    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
    .build()

3. 多进程共享加密数据

val multiProcessPrefs = EncryptedSharedPreferences.create(
    context,
    "multi_process_prefs",
    masterKey,
    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
    Context.MODE_MULTI_PROCESS
)

四、版本兼容性处理

Android 版本	适配策略
Android 6.0+	完全支持硬件密钥库 (KeyStore)
Android 9.0+	支持强生物认证 (BiometricPrompt)
Android 10+	必须使用 AES256-GCM 加密方案
Android 11+	新增密钥超时自动失效功能
Android 13+	要求所有新设备支持硬件密钥库

兼容代码示例：

fun getSupportedEncryptionScheme(): FileEncryptionScheme {
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB
    } else {
        EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_1MB
    }
}

五、注意事项与最佳实践

1. 密钥安全

• 禁止硬编码密钥：依赖系统生成的密钥
• 密钥轮换策略：定期更新主密钥（需迁移旧数据）

2. 生物认证集成

val promptInfo = BiometricPrompt.PromptInfo.Builder()
    .setTitle("需要验证")
    .setSubtitle("请验证身份以访问加密数据")
    .setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
    .build()

biometricPrompt.authenticate(promptInfo)

3. 备份与恢复

• 禁用自动备份：避免密钥被备份到非安全环境

<application
    android:allowBackup="false"
    android:fullBackupContent="false">

4. 异常处理

try {
    encryptedFile.openFileInput()
} catch (e: UserNotAuthenticatedException) {
    // 触发生物认证
} catch (e: KeyPermanentlyInvalidatedException) {
    // 密钥失效，需重新生成
}

5. 性能优化

• 大文件加密使用流式处理（避免内存溢出）

encryptedFile.openFileOutput().use { output ->
    FileInputStream(sourceFile).use { input ->
        input.copyTo(output)
    }
}

六、安全审计要点

1. 密钥存储位置检查

val keyInfo = (keyStore.getEntry(keyAlias, null) as KeyStore.SecretKeyEntry)
    .secretKey.keyInfo
if (!keyInfo.isInsideSecureHardware) {
    Log.w("Security", "密钥未存储在安全硬件中！")
}

2. 加密算法验证

val cipher = encryptedPrefs.preferenceDataStore.valueEncryptionCipher
assert(cipher.algorithm == "AES/GCM/NoPadding")

七、总结

• 核心价值：通过标准化 API 简化数据加密，降低安全漏洞风险
• 推荐场景：支付类 App、企业级应用、医疗健康数据存储
• 避坑指南 ：
  • 测试所有可能的认证失败场景
  • 使用 Security.getProvider("AndroidKeyStore") 验证密钥库状态
  • 定期使用 Android Keystore 安全扫描工具 检查配置

通过合理使用 Jetpack Security，开发者可在不深入密码学细节的情况下，快速构建符合 FIPS 140-2 标准的安全存储方案。

更多分享

1. Android Jetpack Room 新手使用指南
2. Android Jetpack WorkManager 详解