安全存储

浏览示例

本文介绍如何使用 .NET Multi-platform App UI (.NET MAUI) ISecureStorage 接口。 此接口有助于安全存储简单的键/值对。

ISecureStorage 接口的默认实现通过 SecureStorage.Default 属性提供。 ISecureStorage 接口和 SecureStorage 类都包含在 Microsoft.Maui.Storage 命名空间中。

开始

要访问 SecureStorage 功能，需要进行以下平台特定的设置：

应用自动备份 是 Android 6.0（API 级别 23）及更高版本的功能，可备份用户的应用数据（共享偏好设置、应用的内部存储中的文件和其他特定文件）。 在新设备上重新安装或安装应用时，数据将被还原。 这可能会影响使用共享首选项的SecureStorage，这些首选项已备份但在还原时无法解密。 .NET MAUI 通过删除密钥自动处理此情况，以便可以重置密钥。 或者，可以禁用自动备份。

启用或禁用备份

您可以选择在 AndroidManifest.xml 文件中将 设置为"false"来禁用整个应用程序的自动备份。 仅当计划按另一种方式还原数据时才建议使用此方法。

<manifest ... >
    ...
    <application android:allowBackup="false" ... >
        ...
    </application>
</manifest>

选择性备份

可以将自动备份配置为禁止备份特定内容。 可以创建自定义规则集以排除 SecureStore 项目不进行备份。

1. 在您的 AndroidManifest.xml 中设置 属性：

   <application ...
       android:fullBackupContent="@xml/auto_backup_rules">
   </application>
   

2. 使用 AndroidResource 的生成操作在 Platforms/Android/Resources/xml 目录中新建名为 auto_backup_rules.xml 的 XML 文件。 设置以下内容，包括所有共享首选项，SecureStorage 除外：

   <?xml version="1.0" encoding="utf-8"?>
   <full-backup-content>
       <include domain="sharedpref" path="."/>
       <exclude domain="sharedpref" path="${applicationId}.microsoft.maui.essentials.preferences.xml"/>
   </full-backup-content>
   

iOS/Mac Catalyst

在 iOS 模拟器上开发时，启用密钥链权利，并为应用程序的捆绑包标识符添加密钥链访问组。

在项目中创建或打开 Entitlements.plist，查找“密钥链”权利并将其启用。 这样会自动将应用程序的标识符添加为一个组。 有关编辑 Entitlements.plist 文件的更多信息，请参阅 Entitlements。

在“iOS 捆绑包签名”下的“项目属性”中，将“自定义权利”设置为“Entitlements.plist”。

提示

部署到 iOS 设备时，无需此权利，应将其删除。

Windows

无需设置。

使用安全存储

下面的代码示例展示如何使用安全存储。

提示

调用 GetAsync 或 SetAsync 时，可能会引发异常。 这可能是由于设备不支持安全存储、加密密钥更改或数据损坏等原因造成。 最好通过移除并重新添加设置(如果可能)的方式处理这种情况。

写入值

将给定密钥的值保存在安全存储中：

await SecureStorage.Default.SetAsync("oauth_token", "secret-oauth-token-value");

读取值

从安全存储中检索值：

string oauthToken = await SecureStorage.Default.GetAsync("oauth_token");

if (oauthToken == null)
{
    // No value is associated with the key "oauth_token"
}

提示

如果没有与键关联的值，则 GetAsync 返回 null。

删除值

若要删除特定值，请删除密钥：

bool success = SecureStorage.Default.Remove("oauth_token");

要移除所有值，请使用 RemoveAll 方法：

SecureStorage.Default.RemoveAll();

平台差异

本部分描述了安全存储 API 的平台特定差异。

SecureStorage 使用 首选项 API，并遵循 首选项 文档中概述的相同数据持久性，文件名为 [YOUR-APP-PACKAGE-ID].microsoft.maui.essentials.preferences。 但是，数据使用 Android 安全库中的 EncryptedSharedPreferences 类进行加密，该库包装了 SharedPreferences 类，并采用双方案方法自动加密密钥和值：

• 密钥经过确定性加密，以确保密钥可以被加密后仍可正确查找。
• 使用 AES-256 GCM 对值进行非确定性加密。

有关 Android 安全库的详细信息，请参阅 developer.android.com 上的 更安全地处理数据。

警告

当 Android 自动备份将加密首选项还原到新设备时，不会传输原始加密密钥，这意味着无法解密还原的值。 .NET MAUI 会在发生这种情况时自动删除受影响的密钥，但对仍缓存损坏值的任何 GetAsync 调用都可能会引发异常。 始终将安全存储调用包装在 try/catch 中，并调用 RemoveAll 以清除任何不可读的值。

try
{
    var value = await SecureStorage.Default.GetAsync("auth_token");
}
catch (Exception)
{
    // Encrypted values from backup can't be decrypted on this device —
    // clear all secure values so they can be re-entered or re-fetched.
    SecureStorage.Default.RemoveAll();
}

若要完全防止问题，请使用选择性备份来排除 SecureStorage 首选项文件 ， 请参阅上述设置部分中的 选择性备份 。

KeyChain 用于在 iOS 设备上安全地存储值。 用于存储值的 SecRecord 有一个设置为 Service 值的 [YOUR-APP-BUNDLE-ID].microsoft.maui.essentials.preferences。

注释

与 Android 不同，卸载 iOS 应用 不会 删除其密钥链条目。 如果重新安装应用，则新安装仍可访问以前存储的值。 为了避免在设备销售或共享后向另一个用户公开存储的数据，请在首次运行应用时检查首次启动标志并清除密钥链条目：

if (!Preferences.Default.ContainsKey("app_initialized"))
{
    SecureStorage.Default.RemoveAll();
    Preferences.Default.Set("app_initialized", true);
}

注释

如果设备用户已启用 iCloud 密钥链，则由 SecureStorage 其编写的密钥链值可能会以无提示方式同步到用户的其他 Apple 设备。 此行为无法从 .NET MAUI 进行控制。 如果需要设备本地隔离，请考虑在决定要存储 SecureStorage哪些数据时考虑这一点。

Windows

DataProtectionProvider 用于在 Windows 设备上安全地加密值。

在打包的应用程序中，加密值存储在ApplicationData.Current.LocalSettings，位于名为[YOUR-APP-ID].microsoft.maui.essentials.preferences的容器内。 使用首选项 API，并遵循首选项文档中所述的相同数据持久性。 它还使用 LocalSettings，后者存在一个限制：设置名称的长度最多为 255 个字符。 每个设置的大小最大可为 8K 字节，且每个复合设置的大小最大可为 64K 字节。

在未打包的应用中，加密值以 JSON 格式存储在应用的数据文件夹中的 securestorage.dat 中。

限制

如果存储大量文本，性能可能会受到影响，因为 API 旨在存储少量文本。