开发环境与项目配置：minSdkVersion 要求、Gradle 依赖、AndroidX Security-Crypto 库引入

本课程所有实战代码基于 Android API 23（Android 6.0）及以上版本构建。Android Keystore 在 API 23 新增了基于硬件支持的 KeyGenParameterSpec，支持 AES/GCM 和 EC 算法；API 28 进一步引入 StrongBox Keymaster 支持。为保证加解密流程兼容且能利用硬件安全模块，minSdkVersion 必须 ≥ 23。

2.1 minSdkVersion 要求速查

若项目需兼容 API 22 以下设备，请考虑使用 AndroidX Security-Crypto 提供的 EncryptedSharedPreferences 或 MasterKey 降级方案，但本课程所有示例统一以 API 23 为最低目标。

2.2 Gradle 依赖：引入 AndroidX Security-Crypto

在模块级 build.gradle 或 build.gradle.kts 中添加 security-crypto 以及关联依赖。推荐使用 1.1.0-alpha06 或更高稳定版（1.1.0-alpha06 已修复多个已知 bug，并支持 Android 12 以上新密钥策略）。

android {
    compileSdk 34
    defaultConfig {
        minSdk 23
        targetSdk 34
    }
    ...
}

dependencies {
    implementation 'androidx.security:security-crypto:1.1.0-alpha06'
    // 如需对文件或流加密可额外引入
    implementation 'androidx.security:security-crypto-ktx:1.1.0-alpha06'
}

android {
    compileSdk = 34
    defaultConfig {
        minSdk = 23
        targetSdk = 34
    }
    ...
}

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

说明：

• security-crypto 库依赖 Android Keystore 系统服务，无需额外注册。
• security-crypto-ktx 提供 Kotlin 扩展函数（如 encryptedSharedPreferences）提升开发效率。
• 若项目已使用 androidx.biometric 库，无需重复添加；Security-Crypto 本身不强制要求生物识别依赖。

2.3 依赖引入后的同步与验证

执行 Gradle 同步后，检查 External Libraries 中是否出现 androidx.security:security-crypto。可在代码中添加简单验证：

import android.security.keystore.KeyGenParameterSpec
import android.security.keystore.KeyProperties
import java.security.KeyStore

// 确认 KeyStore 可用
val keyStore = KeyStore.getInstance("AndroidKeyStore")
keyStore.load(null)
Log.d("KeystoreCheck", "KeyStore type: ${keyStore.type}, provider: ${keyStore.provider}")

若控制台输出 AndroidKeyStore 且未抛出异常，说明环境配置成功。

2.4 常见配置错误与修正

2.5 配置流程总图

下图梳理了从项目创建到可调用 Keystore 的完整配置路径：

2.6 完整配置清单