安全

安全

用户指南  代码示例

API 参考文档
androidx.security.crypto

安全地管理密钥并对文件和 sharedpreferences 进行加密。

下表列出了 androidx.security 组中的所有制品。

制品	稳定版	候选版	Beta 版	Alpha 版
security-crypto	1.0.0	-	1.1.0-beta01	-
security-app-authenticator	-	1.0.0-rc01	-	-
security-identity-credential	-	-	-	1.0.0-alpha03

此库的上次更新时间：2025 年 6 月 4 日

声明依赖项

如需添加 Security 的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 制品库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

Security-State 版本 1.0

版本 1.0.0-beta01

2025 年 2 月 26 日

发布了 androidx.security:security-state:1.0.0-beta01。版本 1.0.0-beta01 包含这些提交内容。

bug 修复

• 修复了导致 getPatchedCves() 无法为 COMPONENT_SYSTEM_MODULES 返回已修补的 CVE 的问题。(Ice5e2)

版本 1.0.0-alpha05

2025 年 1 月 29 日

发布了 androidx.security:security-state:1.0.0-alpha05。版本 1.0.0-alpha05 包含这些提交内容。

新功能

• 默认系统模块的软件包名称已添加到库的清单中，以允许客户端应用获取适用于系统模块的设备 SPL。(Ic259c)

API 变更

• 将 SecurityStateManager 重命名为 SecurityStateManagerCompat，为公共属性和函数添加了其他文档，并将 getComponentSecurityPatchLevel 和 getVulnerabilityReportUrl 设为静态方法。(I44a0c)
• 更新库存状况功能（listAvailableUpdates() 和 getAvailableSecurityPatchLevel() 方法）现已从 API Surface 中移除，并计划在库的未来更新中恢复。(Idbc5e)
• 访问供应商 SPL 现在由编译时标志进行保护，该标志默认处于停用状态，直至库日后进行更新。(I45b58)
• getGlobalSecurityState() 现在会针对 SDK 35 及更高版本从系统服务返回全局安全状态。I7b9da

bug 修复

• 修复了在未提供已发布内核 LTS 版本的旧版 Android 上尝试获取已发布内核 SPL 时发生的崩溃问题。(I93dff)

版本 1.0.0-alpha04

2024 年 8 月 7 日

发布了 androidx.security:security-state:1.0.0-alpha04。版本 1.0.0-alpha04 包含这些提交内容。

备注

• 将 compileSdk 更新为 35 5dc41be

API 变更

• 破坏性更改：为了实现可扩展性，组件枚举已替换为字符串常量。(Ia3283)

版本 1.0.0-alpha03

2024 年 7 月 10 日

发布了 androidx.security:security-state:1.0.0-alpha03。版本 1.0.0-alpha03 包含这些提交内容。

bug 修复

• 修复了 Android 安全公告 bug 的 ASB-A- 模式、其他组件的 JSON 解析以及 Webview 打包检索。(Ide86a)

版本 1.0.0-alpha02

2024 年 6 月 26 日

发布了 androidx.security:security-state:1.0.0-alpha02。版本 1.0.0-alpha02 包含这些提交内容。

bug 修复

• 修复了获取内核版本的逻辑。(I5602a)

版本 1.0.0-alpha01

2024 年 6 月 12 日

发布了 androidx.security:security-state:1.0.0-alpha01。版本 1.0.0-alpha01 包含这些提交内容。

新功能

• Security State 是一个新库，开发者可以使用该库获取有关可更新系统组件版本、安全更新和已应用修复程序的实用数据。

Security-App-Authenticator-Testing 版本 1.0

版本 1.0.0-rc01

2025 年 5 月 20 日

发布了 androidx.security:security-app-authenticator:1.0.0-rc01 和 androidx.security:security-app-authenticator-testing:1.0.0-rc01。版本 1.0.0-rc01 包含这些提交内容。

版本 1.0.0-beta01

2024 年 3 月 6 日

发布了 androidx.security:security-app-authenticator:1.0.0-beta01 和 androidx.security:security-app-authenticator-testing:1.0.0-beta01。版本 1.0.0-beta01 包含这些提交内容。

版本 1.0.0-alpha02

2023 年 12 月 13 日

发布了 androidx.security:security-app-authenticator-testing:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

bug 修复

• 更新了针对新 API 行为的测试，该行为在未向 [check|enforce]CallingAppIdentity API 提供时不再假定 Binder#getCalling[Uid|Pid]。(I1851b)

版本 1.0.0-alpha01

2021 年 6 月 2 日

发布了 androidx.security:security-app-authenticator-testing:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

新功能

此测试库提供了一个构建器，可用于配置可注入的 AppAuthenticator，以满足测试要求。此库支持多种配置 AppAuthenticator 的方法：

• 可以指定一项通用测试政策，用于针对配置中声明的所有软件包在签名匹配时进行报告。
• 可以将个别软件包指定为返回自身签名匹配而所有其他软件包报告无匹配的情况。
• 可以为各个软件包设置显式签名身份。仅当所提供的身份与配置文件中的声明匹配时，生成的 AppAuthenticator 才会报告签名匹配。
• 软件包也可被视为未安装或具有明确的 UID。

Security-App-Authenticator 版本 1.0.0

版本 1.0.0-alpha03

2023 年 12 月 13 日

发布了 androidx.security:security-app-authenticator:1.0.0-alpha03。版本 1.0.0-alpha03 中包含这些提交内容。

API 变更

• 添加了对以下用例的支持：无法获取要验证的软件包的 UID / PID；这些 API 现在支持 startActivityForResult 和 activity / 接收器等用例，其中调用应用的身份是通过 [Activity|Broadcast]Options#setShareIdentityEnabled 共享的。
• [check|enforce]CallingAppIdentity(String, String) 的行为已更新为支持这些新用例；这些方法不再默认使用 Binder#getCalling[Uid|Pid]，而是会跳过调用软件包的 UID 验证（如果未明确提供）。(I1851b)

版本 1.0.0-alpha02

2021 年 6 月 2 日

发布了 androidx.security:security-app-authenticator:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

API 变更

• 为了更好地支持 Android 12 中新引入的 knownSigner 权限保护标志，现在不必再在配置中指定 digestAlgorithm 属性。因此，所有证书摘要都应使用 SHA-256 计算。

bug 修复

• 配置中提供的所有证书摘要现在都已标准化，以确保在运行期间计算摘要时以及使用测试库定义显式签名身份时，如果签名匹配成功，系统就会报告。

版本 1.0.0-alpha01

2021 年 5 月 5 日

发布了 androidx.security:security-app-authenticator:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

新功能

AppAuthenticator 是一个新库，旨在根据登录身份简化应用信任验证。应用只需指定一个 XML 配置文件来包含受信任应用的软件包名称和签名身份，该库将负责在运行时验证应用的签名身份。

Security-Identity-Credential 版本 1.0.0

版本 1.0.0-alpha03

2021 年 9 月 1 日

发布了 androidx.security:security-identity-credential:1.0.0-alpha03。版本 1.0.0-alpha03 中包含这些提交内容。

新功能

• Android 12 中现在支持由硬件支持的身份凭据功能。

版本 1.0.0-alpha02

2021 年 2 月 24 日

发布了 androidx.security:security-identity-credential:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

bug 修复

• 更新了 Identity Credential API 以符合 Android 12 计划的要求 (Iff83e)

版本 1.0.0-alpha01

2020 年 8 月 19 日

发布了 androidx.security:security-identity-credential:1.0.0-alpha01。版本 1.0.0-alpha01 中包含这些提交内容。

新功能

此 Jetpack 版本具有身份凭据 API 的 Jetpack 版本，它已添加到 Android 11 和 API 级别 30。如果设备搭载 Android 11 并支持由硬件支持的身份凭据，那么此 Jetpack 仅会向平台 API 转发调用。否则，将使用由 Android 密钥库支持的实现。虽然由 Android 密钥库支持的实现不会提供相同级别的安全和隐私保护，但只要所有数据都经颁发者签名，对持有者和颁发者而言，该实现就完全足够。此库需要 API 级别 24 或更高级别。

身份凭据 API 为用户身份文档提供安全存储的接口。这些 API 被特意设计为极其普通且抽象的 API。在可能的情况下，这些 API 应不负责指定与凭据验证设备和颁发机构 (IA) 通信时的消息格式和语义。这些 API 所依赖的数据结构与即将发布的《ISO/IEC IS 18013-5 个人身份识别 — 符合 ISO 要求的驾照 — 第 5 部分：移动驾照 (mDL) 申请标准》中的数据结构兼容。

API 变更

• 添加了身份凭据 Jetpack。(Icf90b)

Security-Crypto 版本 1.1.0

版本 1.1.0-beta01

2025 年 6 月 4 日

发布了 androidx.security:security-crypto:1.1.0-beta01 和 androidx.security:security-crypto-ktx:1.1.0-beta01。版本 1.1.0-beta01 包含这些提交内容。

API 变更

• 废弃了所有 API，改为使用现有平台 API 和直接使用 Android 密钥库。

版本 1.1.0-alpha07

2025 年 4 月 9 日

发布了 androidx.security:security-crypto:1.1.0-alpha07 和 androidx.security:security-crypto-ktx:1.1.0-alpha07。版本 1.1.0-alpha07 包含这些提交内容。

API 变更

• 废弃了所有 API，改为使用现有平台 API 和直接使用 Android 密钥库。

版本 1.1.0-alpha06

2023 年 4 月 19 日

发布了 androidx.security:security-crypto:1.1.0-alpha06 和 androidx.security:security-crypto-ktx:1.1.0-alpha06。版本 1.1.0-alpha06 中包含这些提交内容。

新功能

• 将 Tink 依赖项更新到了 1.8.0

版本 1.1.0-alpha05

2023 年 2 月 22 日

发布了 androidx.security:security-crypto:1.1.0-alpha05 和 androidx.security:security-crypto-ktx:1.1.0-alpha05。版本 1.1.0-alpha05 中包含这些提交内容。

bug 修复

• 修复了 MasterKeys.getOrCreate 中的竞态条件（I3391e、b/268572037）

版本 1.1.0-alpha04

2022 年 11 月 9 日

发布了 androidx.security:security-crypto:1.1.0-alpha04 和 androidx.security:security-crypto-ktx:1.1.0-alpha04。版本 1.1.0-alpha04 中包含这些提交内容。

新功能

• 移除了应用首次启动时的日志消息“keyset not found, will generate a new one”（找不到密钥集，将生成新的密钥集）。(b/185219606)
• 将 Tink 依赖项升级到了版本 1.7.0。

API 变更

• 更改了 EncryptedFile#openFileInput()，以便在请求的文件不存在时抛出 FileNotFoundException，而不是抛出通用 IOException。（I80e41、b/148804719）
• 更新了“MasterKeys”类，要求使用 Android M，而不是 Android M 的每个方法。(I8b4b8)
• 在值的类型无法与已定义的枚举变体之一匹配时（极少发生），更改 EncryptedSharedPreferences 上的所有偏好设置 getter（例如 #getString、#getInt）以抛出 SecurityException。(b/241699427)

bug 修复

• 通过将 security-crypto-ktx 库的最低 SDK 版本降低至 v21 来使其与 security-crypto 同步 (b/193550375)
• 修复了构建多个 EncryptedFile 时出现的并发 bug (b/136590547)

外部贡献

• 从 [e-mail] 收到了针对 EncryptedSharedPreferences.Editor#remove 的修复程序（b/224994760、b/134197835、f44d44d）

Security-Crypto-Ktx 版本 1.1.0-alpha03

2021 年 5 月 18 日

发布了 androidx.security:security-crypto-ktx:1.1.0-alpha03。版本 1.1.0-alpha03 中包含这些提交内容。

已更新为与 androidx.security:security-crypto:1.1.0-alpha03 匹配。

版本 1.1.0-alpha03

2020 年 12 月 2 日

发布了 androidx.security:security-crypto:1.1.0-alpha03。版本 1.1.0-alpha03 中包含这些提交内容。

新功能

• 将 Tink 更新为了稳定版 1.5.0

版本 1.1.0-alpha02

2020 年 8 月 5 日

发布了 androidx.security:security-crypto:1.1.0-alpha02 和 androidx.security:security-crypto-ktx:1.1.0-alpha02。版本 1.1.0-alpha02 中包含这些提交内容。

新功能

• 将 Tink 更新为了稳定版 1.4.0

bug 修复

• Tink 更新应该能够修复 R8 和 Proguard 存在的阴影 Protobuf 依赖项相关问题。
• Tink 更新应该能够妥善处理 AndroidKeyStore 并发故障。

外部贡献

• 在应用时清除 mKeysChanged，针对 EncryptedSharedPreferences 进行修复 (aosp/1323026)

版本 1.1.0-alpha01

2020 年 6 月 10 日

发布了 androidx.security:security-crypto:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

新功能

• Lollipop（API 级别 21 以上）现在受支持。请注意，AndroidKeyStore 不用于 API 21 和 22。（I7c12d、b/132325342）
• 新的 MasterKey 类为密钥提供更多选项，同时废弃了 MasterKey 以支持新功能和不具有 KeyGenParamSpec 的 Android 版本。

Security-Crypto 版本 1.0.0

版本 1.0.0

2021 年 4 月 21 日

发布了 androidx.security:security-crypto:1.0.0。版本 1.0.0 中包含这些提交内容。

1.0.0 的主要功能

功能亮点

• EncryptedFile，提供加密输入和输出流，以从文件读取或向文件写入加密数据。
• EncryptedSharedPreferences - 提供了 SharedPreferences 的实现，可自动加密/解密所有键和值。
• 通过 MasterKeys 提供简单的密钥生成机制。
• 依赖 Tink 1.5.0 来提升稳定性。

版本 1.0.0-rc04

2021 年 1 月 13 日

发布了 androidx.security:security-crypto:1.0.0-rc04。版本 1.0.0-rc04 中包含这些提交内容。

bug 修复

• 已将 Tink 升级到 1.5.0 以提升稳定性。

版本 1.0.0-rc03

2020 年 8 月 5 日

发布了 androidx.security:security-crypto:1.0.0-rc03。版本 1.0.0-rc03 中包含这些提交内容。

新功能

• 将 Tink 更新为了稳定版 1.4.0

bug 修复

• Tink 更新应该能够修复 R8 和 Proguard 存在的阴影 Protobuf 依赖项相关问题。
• Tink 更新应该能够妥善处理 AndroidKeyStore 并发故障。

外部贡献

• 在应用时清除 mKeysChanged，针对 EncryptedSharedPreferences 进行修复 (aosp/1323026)

版本 1.0.0-rc02

2020 年 5 月 20 日

发布了 androidx.security:security-crypto:1.0.0-rc02。版本 1.0.0-rc02 中包含这些提交内容。

bug 修复

• 已更新至 Tink 版本 1.4.0-rc2，可为 protobuf 精简依赖项添加阴影。这解决了被广泛报告的与其他 Android SDK 冲突的问题。(I8a831)
• 修复了 EncryptedSharedPreferences 中的 apply()。（I29069、b/154366606）

版本 1.0.0-rc01

2020 年 4 月 15 日

发布了 androidx.security:security-crypto:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

bug 修复

• 添加了检查功能，确保如果 KeyGenParamSpec 传递给 MasterKeys.getOrCreate，并且 getUserAuthenticationRequired 返回 true，则 getUserAuthenticationValidityDurationSeconds 返回的值大于 0。(I911f5) (b/152644939)

版本 1.0.0-beta01

2020 年 3 月 18 日

发布了 androidx.security:security-crypto:1.0.0-beta01，该版本与 1.0.0-alpha02 相比没有变化。版本 1.0.0-beta01 中包含这些提交内容。

版本 1.0.0-alpha02

2019 年 5 月 23 日

发布了 androidx.security:security-crypto:1.0.0-alpha02。点击提交内容日志可查看此版本中包含的提交内容。

bug 修复

• 修复了从 getAll() 检索与共享偏好设置相关的键值对时出现的问题。
• 已阻止使用受限的偏好设置键。
• 对 Javadoc 进行了次要更新。

版本 1.0.0-alpha01

2019 年 5 月 7 日

发布了 androidx.security:security-crypto:1.0.0-alpha01。点击此处可查看此版本中包含的提交内容。

新功能亮点

• EncryptedFile，提供加密输入和输出流，以从文件读取或向文件写入加密数据。
• EncryptedSharedPreferences，提供了 SharedPreferences 的实现，可自动加密/解密所有键和值。
• 通过 MasterKeys 提供简单的密钥生成机制。