Edit

Share via


Secure storage

Browse sample. Browse the sample

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) ISecureStorage interface. This interface helps securely store simple key/value pairs.

The default implementation of the ISecureStorage interface is available through the SecureStorage.Default property. Both the ISecureStorage interface and SecureStorage class are contained in the Microsoft.Maui.Storage namespace.

Get started

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

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 reinstalled or installed on a new device. This can affect SecureStorage, which utilizes share preferences that are backed up and can't be decrypted when the restore occurs. .NET MAUI automatically handles this case by removing the key so it can be reset. Alternatively, you can disable Auto Backup.

Enable or disable backup

You can choose to disable Auto Backup for your entire application by setting android:allowBackup 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 Platforms/Android/Resources/xml directory with the build action of AndroidResource. 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}.microsoft.maui.essentials.preferences.xml"/>
    </full-backup-content>
    

Use secure storage

The following code examples demonstrate how to use secure storage.

Tip

It's 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's best to handle this by removing and adding the setting back if possible.

Write a value

To save a value for a given key in secure storage:

await SecureStorage.Default.SetAsync("oauth_token", "secret-oauth-token-value");

Read a value

To retrieve a value from secure storage:

string oauthToken = await SecureStorage.Default.GetAsync("oauth_token");

if (oauthToken == null)
{
    // No value is associated with the key "oauth_token"
}

Tip

If there isn't a value associated with the key, GetAsync returns null.

Remove a value

To remove a specific value, remove the key:

bool success = SecureStorage.Default.Remove("oauth_token");

To remove all values, use the RemoveAll method:

SecureStorage.Default.RemoveAll();

Platform differences

This section describes the platform-specific differences with the secure storage API.

SecureStorage uses the Preferences API and follows the same data persistence outlined in the Preferences documentation, with a filename of [YOUR-APP-PACKAGE-ID].microsoft.maui.essentials.preferences. However, data is encrypted with the Android EncryptedSharedPreferences class, from the Android Security library, which wraps the SharedPreferences class and automatically encrypts keys and values using a two-scheme approach:

  • Keys are deterministically encrypted, so that the key can be encrypted and properly looked up.
  • Values are non-deterministically encrypted using AES-256 GCM.

For more information about the Android Security library, see Work with data more securely on developer.android.com.

Limitations

Performance may be impacted if you store large amounts of text, as the API was designed to store small amounts of text.