Xamarin.Essentials: Sicherer SpeicherXamarin.Essentials: Secure Storage

Mit der Klasse SecureStorage können Sie einfache Schlüssel/Wertpaare sicher speichern.The SecureStorage class helps securely store simple key/value pairs.

Erste SchritteGet started

Lesen Sie zum Einstieg in diese API das Handbuch Erste Schritte mit Xamarin.Essentials, um sicherzustellen, dass die Bibliothek ordnungsgemäß installiert und in Ihren Projekten eingerichtet ist.To start using this API, read the getting started guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects.

Der Zugriff auf die SecureStorage-Funktionalität erfordert das folgende plattformspezifische Setup:To access the SecureStorage functionality, the following platform-specific setup is required:

Tipp

Die Automatische Sicherung für Apps ist eine Funktion von Android 6.0 (API-Ebene 23) und höher, die die App-Daten von Benutzern sichert (freigegebene Einstellungen, Dateien im internen App-Speicher und andere spezifische Dateien).Auto Backup for Apps is a feature of Android 6.0 (API level 23) and later that backs up user's app data (shared preferences, files in the app's internal storage, and other specific files). Die Daten werden wiederhergestellt, wenn eine App neu installiert oder auf einem neuen Gerät installiert wird.Data is restored when an app is re-installed or installed on a new device. Dies kann sich auf die SecureStorage-Klasse auswirken, die Freigabeeinstellungen verwendet, die gesichert werden und nicht beim Wiederherstellen entschlüsselt werden können.This can impact SecureStorage which utilizes share preferences that are backed up and can not be decrypted when the restore occurs. Xamarin.Essentials verarbeitet diesen Fall automatisch durch Entfernen des Schlüssels, um das Zurücksetzen zu ermöglichen, aber Sie können die automatische Sicherung auch manuell deaktivieren.Xamarin.Essentials automatically handles this case by removing the key so it can be reset, but you can take an additional step by disabling Auto Backup.

Aktivieren und Deaktivieren der SicherungEnable or disable backup

Sie können die automatische Sicherung für Ihre gesamte Anwendung deaktivieren, indem Sie die Einstellung android:allowBackup in der Datei AndroidManifest.xml auf FALSE festlegen.You can choose to disable Auto Backup for your entire application by setting the android:allowBackup setting to false in the AndroidManifest.xml file. Dieser Ansatz wird nur empfohlen, wenn Sie Daten auf eine andere Weise wiederherstellen möchten.This approach is only recommended if you plan on restoring data in another way.

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

Selektive SicherungSelective Backup

Die automatische Sicherung lässt sich konfigurieren, um bestimmte Inhalte davon auszuschließen.Auto Backup can be configured to disable specific content from backing up. Sie können ein benutzerdefiniertes Regelset erstellen, um SecureStore-Elemente von der Sicherung auszuschließen.You can create a custom rule set to exclude SecureStore items from being backed up.

  1. Legen Sie das android:fullBackupContent-Attribut in Ihrer AndroidManifest.xml fest:Set the android:fullBackupContent attribute in your AndroidManifest.xml:

    <application ...
        android:fullBackupContent="@xml/auto_backup_rules">
    </application>
    
  2. Erstellen Sie eine neue XML-Datei mit dem Namen auto_backup_rules.xml mit dem Buildvorgang AndroidResource im Verzeichnis Resources/xml.Create a new XML file named auto_backup_rules.xml in the Resources/xml directory with the build action of AndroidResource. Legen Sie dann den folgenden Inhalt fest, der alle freigegebenen Einstellungen mit Ausnahme von SecureStorage enthält:Then set the following content that includes all shared preferences except for 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>
    

Verwenden des sicheren SpeichersUsing Secure Storage

Fügen Sie Ihrer Klasse einen Verweis auf Xamarin.Essentials hinzu:Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

So speichern Sie einen Wert für einen bestimmten Schlüssel im sicheren Speicher:To save a value for a given key in secure storage:

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

So rufen Sie einen Wert aus dem sicheren Speicher ab:To retrieve a value from secure storage:

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

Hinweis

Wenn dem angeforderten Schlüssel kein Wert zugeordnet ist, gibt GetAsync``null zurück.If there is no value associated with the requested key, GetAsync will return null.

So entfernen Sie einen bestimmten Schlüssel:To remove a specific key, call:

SecureStorage.Remove("oauth_token");

Rufen Sie Folgendes auf, um alle Schlüssel zu entfernen:To remove all keys, call:

SecureStorage.RemoveAll();

Besonderheiten bei der plattformspezifischen ImplementierungPlatform Implementation Specifics

Der Android-KeyStore wird verwendet, um den Chiffrierschlüssel zu speichern, mit dem der Wert verschlüsselt wurde, bevor er in einer freigegebenen Einstellung mit einem Dateinamen von [YOUR-APP-PACKAGE-ID].xamarinessentials gespeichert wird.The Android KeyStore is used to store the cipher key used to encrypt the value before it is saved into a Shared Preferences with a filename of [YOUR-APP-PACKAGE-ID].xamarinessentials. Der in der freigegebenen Einstellungsdatei verwendete Schlüssel (kein kryptografischer Schlüssel, sondern der Schlüssel für den Wert) ist ein MD5-Hash des Schlüssels, der an die SecureStorage-APIs übergeben wird.The key (not a cryptographic key, the key to the value) used in the shared preferences file is a MD5 Hash of the key passed into the SecureStorage APIs.

API-Ebene 23 und höherAPI Level 23 and Higher

Auf neueren API-Ebenen wird ein AES-Schlüssel im Android-KeyStore abgerufen und mit einer AES/GCM/NoPadding-Verschlüsselung verwendet, um den Wert zu verschlüsseln, bevor er in der freigegebenen Einstellungsdatei gespeichert wird.On newer API levels, an AES key is obtained from the Android KeyStore and used with an AES/GCM/NoPadding cipher to encrypt the value before it is stored in the shared preferences file.

API-Ebene 22 und niedrigerAPI Level 22 and Lower

Auf älteren API-Ebenen unterstützt der Android-KeyStore nur das Speichern von RSA-Schlüsseln, die mit einer RSA/ECB/PKCS1Padding-Verschlüsselung verwendet werden, um einen AES-Schlüssel zu verschlüsseln (zufällig zur Laufzeit erzeugt), und in der freigegebenen Einstellungsdatei unter dem Schlüssel SecureStorageKey gespeichert werden, wenn noch keiner generiert wurde.On older API levels, the Android KeyStore only supports storing RSA keys, which is used with an RSA/ECB/PKCS1Padding cipher to encrypt an AES key (randomly generated at runtime) and stored in the shared preferences file under the key SecureStorageKey, if one has not already been generated.

SecureStorage verwendet die Einstellungen-API und berücksichtigt die in der Dokumentation Einstellungen beschriebene Datenpersistenz.SecureStorage uses the Preferences API and follows the same data persistence outlined in the Preferences documentation. Wenn ein Gerät von API-Ebene 22 oder niedriger auf API-Ebene 23 oder höher aktualisiert wird, wird diese Art der Verschlüsselung weiterhin verwendet, es sei denn, die App wird deinstalliert oder RemoveAll aufgerufen.If a device upgrades from API level 22 or lower to API level 23 and higher, this type of encryption will continue to be used unless the app is uninstalled or RemoveAll is called.

EinschränkungenLimitations

Diese API wurde zum Speichern kleiner Textmengen konzipiert.This API is intended to store small amounts of text. Die Leistung ist ggf. langsam, wenn Sie versuchen, damit große Textmengen zu speichern.Performance may be slow if you try to use it to store large amounts of text.

APIAPI

Auf Channel 9 und auf YouTube finden Sie weitere Videos zu Xamarin.Find more Xamarin videos on Channel 9 and YouTube.