保護儲存體

發行項
12/16/2024

本文說明如何使用 .NET 多平臺應用程式 UI （.NET MAUI） ISecureStorage 介面。此介面可協助安全地儲存簡單的索引鍵/值組。

介面的預設實作 ISecureStorage 可透過 SecureStorage.Default 屬性取得。 ISecureStorage介面和SecureStorage類別都包含在命名空間中Microsoft.Maui.Storage。

開始使用

若要存取 SecureStorage 功能，需要下列平臺特定設定：

應用程式自動備份 (Auto Backup for Apps) 是 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 的建置動作，在 Platform/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>

使用安全記憶體

下列程式代碼範例示範如何使用安全記憶體。

提示

呼叫或SetAsync時GetAsync可能會擲回例外狀況。這可能是裝置不支援安全記憶體、加密金鑰變更或數據損毀所造成。最好盡可能移除和新增設定，以處理此狀況。

寫入值

若要將給定「機碼」的值儲存在安全的存放區中：

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 類別加密，而 Android EncryptedSharedPreferences 安全性連結庫會包裝 SharedPreferences 類別，並使用雙配置方法自動加密密鑰和值：

金鑰會以決定性方式加密，讓金鑰可以加密並正確查閱。
值是使用 AES-256 GCM 進行不具決定性的加密。

如需 Android 安全性連結庫的詳細資訊，請參閱在 developer.android.com 上更安全地使用數據。

DataProtectionProvider 用來在 Windows 裝置上安全地加密值。

在封裝的應用程式中，加密的值會儲存在 ApplicationData.Current.LocalSettings容器內，其名稱為 [YOUR-APP-ID].microsoft.maui.essentials.preferences。 SecureStorage會使用喜好設定 API，並遵循喜好設定檔中所述的相同數據持續性。它也會使用 LocalSettings，其限制設定名稱長度最多可以是 255 個字元。每個設定的大小最多可為8K個字節，而且每個複合設定的大小最多可達64 K個字節。

在解壓縮的應用程式中，加密的值會以 JSON 格式儲存在 securestorage.dat 應用程式的數據資料夾中。

限制

如果您儲存大量的文字，效能可能會受到影響，因為 API 是設計來儲存少量的文字。

共用方式為