安全存储

项目
05/14/2024

本文介绍如何使用 .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 文件中将 android:allowBackup 设置设为“false”对整个应用程序禁用自动备份。仅当计划按另一种方式还原数据时才建议使用此方法。

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

选择性备份

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

在你的 AndroidManifest.xml 中设置 android:fullBackupContent 属性：

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

使用 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>

使用安全存储

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

提示

调用 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 类从 Android 安全库进行加密，该安全库包装 SharedPreferences 类，并使用双方案方法自动加密密钥和值：

密钥加密是确定性的，以便可以加密密钥并正确查找。
使用 AES-256 GCM 对值进行非确定性加密。

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

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

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

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

限制

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

通过