Share via


Xamarin.Essentials: Secure Storage

The SecureStorage class helps securely store simple key/value pairs.

Get started

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.

To access the SecureStorage functionality, the following platform-specific setup is required:

Tip

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). Data is restored when an app is re-installed or installed on a new device. This can impact SecureStorage which utilizes share preferences that are backed up and can not be decrypted when the restore occurs. 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.

Enable or disable backup

You can choose to disable Auto Backup for your entire application by setting the android:allowBackup setting to false in the AndroidManifest.xml file. This approach is only recommended if you plan on restoring data in another way.

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

Selective Backup

Auto Backup can be configured to disable specific content from backing up. You can create a custom rule set to exclude SecureStore items from being backed up.

  1. Set the android:fullBackupContent attribute in your AndroidManifest.xml:

    <application ...
        android:fullBackupContent="@xml/auto_backup_rules">
    </application>
    
  2. Create a new XML file named auto_backup_rules.xml in the Resources/xml directory with the build action of AndroidResource. 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>
    

Using Secure Storage

Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

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.
}

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.
}

Note

If there is no value associated with the requested key, GetAsync will return null.

To remove a specific key, call:

SecureStorage.Remove("oauth_token");

To remove all keys, call:

SecureStorage.RemoveAll();

Tip

It is possible that an exception is thrown when calling GetAsync or SetAsync. This can be caused by a device not supporting secure storage, encryption keys changing, or corruption of data. It is best to handle this by removing and adding the setting back if possible.

Platform Implementation Specifics

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. 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 Level 23 and Higher

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 Level 22 and Lower

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 uses the Preferences API and follows the same data persistence outlined in the Preferences documentation. 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.

Limitations

This API is intended to store small amounts of text. Performance may be slow if you try to use it to store large amounts of text.

API

Find more Xamarin videos on Channel 9 and YouTube.