Xamarin.Essentials：安全儲存體

發行項
03/05/2024

SecureStorage 類別有助於安全地存放簡單的機碼/值組。

開始使用

若要開始使用此 API，請閱讀入門指南Xamarin.Essentials，以確保連結庫已正確安裝並設定在您的專案中。

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

提示

應用程式自動備份 (Auto Backup for Apps) 是 Android 6.0 (API 層級 23) 與更新版本中的功能，可備份使用者的應用程式資料 (共用喜好設定、應用程式內部存放區中的檔案，以及其他特定檔案)。當重新安裝應用程式或在新裝置上安裝應用程式時，會還原資料。這會對 SecureStorage 造成影響，它利用備份的共用喜好設定，而且在進行還原時無法解密。 Xamarin.Essentials 藉由移除金鑰來自動處理此案例，以便重設密鑰，但您可以停用自動備份來採取其他步驟。

啟用或停用備份

您可以透過將 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>

在 Resources/xml 目錄中搭配 AndroidResource 的建置動作，建立名為 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}.xamarinessentials.xml"/>
</full-backup-content>

使用 Secure Storage

在類別中新增的 Xamarin.Essentials 參考：

using Xamarin.Essentials;

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

try
{
  await SecureStorage.SetAsync("oauth_token", "secret-oauth-token-value");
}
catch (Exception ex)
{
  // Possible that device doesn't support secure storage on device.
}

從安全的存放區擷取值：

try
{
  var oauthToken = await SecureStorage.GetAsync("oauth_token");
}
catch (Exception ex)
{
  // Possible that device doesn't support secure storage on device.
}

注意

若沒有值與該要求機碼相關聯，GetAsync 將會傳回 null。

若要移除指定的機碼，請呼叫：

SecureStorage.Remove("oauth_token");

若要移除所有機碼，請呼叫：

SecureStorage.RemoveAll();

提示

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

平台實作特性

Android KeyStore 是用來存放在將值以檔案名稱 [YOUR-APP-PACKAGE-ID].xamarinessentials 儲存到共用喜好設定之前用於加密值的密碼編譯金鑰。在共用喜好設定檔案中使用的金鑰 (不是密碼編譯金鑰，適用於「值」的「金鑰」) 是傳遞到 SecureStorage API 之金鑰的「MD5 雜湊」。

API 層級 23 和更新版本

在較新的 API 層級上，會從 Android KeyStore 取得 AES 金鑰並搭配 AES/GCM/NoPadding 密碼編譯使用，以在將值存放在共用喜好設定檔案中之前加密值。

API 層級 22 和更低

在較舊的 API 層級上，Android KeyStore 只支援存放 RSA 金鑰，此金鑰會搭配 RSA/ECB/PKCS1Padding 密碼編譯使用以加密 AES 金鑰 (在執行階段隨機產生) 並存放在機碼 SecureStorageKey 下的共用喜好設定檔案中 (若尚未產生)。

SecureStorage 使用 Preferences API 並遵循 Preferences 文件中概述的相同資料持續性原則。若裝置從 API 層級 22 或較低的層級升級到 API 層級 23 與更高版本，將會繼續使用此類型的加密，除非將應用程式解除安裝或呼叫 RemoveAll。

DataProtectionProvider 可用來安全地在 UWP 裝置上為值加密。

加密值會存放在 ApplicationData.Current.LocalSettings 中名為 [YOUR-APP-ID].xamarinessentials 的容器內。

SecureStorage 使用 Preferences API 並遵循 Preferences 文件中概述的相同資料持續性原則。它也會使用 LocalSettings 限制，限制每個設定的名稱最多可以長度為 255 個字元。每個設定的大小最多可以有8K個字節，而且每個複合設定的大小最多可達64K個字節。

限制

此 API 旨在存放少量文字。若嘗試使用它來存放大量文字，效能會變差。

API

在 Channel 9 與 YouTube 上尋找更多 Xamarin 影片。

Xamarin.Essentials：安全 儲存體