Secure storage

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:

Android

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>
   

iOS/Mac Catalyst

When developing on the iOS simulator, enable the Keychain entitlement and add a keychain access group for the application's bundle identifier.

Create or open the Entitlements.plist in the project and find the Keychain entitlement and enable it. This will automatically add the application's identifier as a group. For more information about editing the Entitlements.plist file, see Entitlements.

In the project properties, under iOS Bundle Signing set the Custom Entitlements to Entitlements.plist.

Tip

When deploying to an iOS device, this entitlement isn't required and should be removed.

Windows

No setup is required.

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.

Android

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.

iOS/Mac Catalyst

KeyChain is used to store values securely on iOS devices. The SecRecord used to store the value has a Service value set to [YOUR-APP-BUNDLE-ID].microsoft.maui.essentials.preferences.

In some cases, KeyChain data is synchronized with iCloud, and uninstalling the application may not remove the secure values from user devices.

Windows

DataProtectionProvider is used to encrypt values securely on Windows devices.

In packaged apps, encrypted values are stored in ApplicationData.Current.LocalSettings, inside a container with a name of [YOUR-APP-ID].microsoft.maui.essentials.preferences. SecureStorage uses the Preferences API and follows the same data persistence outlined in the Preferences documentation. It also uses LocalSettings, which has a restriction that a setting name length may be 255 characters at the most. Each setting can be up to 8K bytes in size, and each composite setting can be up to 64 K bytes in size.

In unpackaged apps, encrypted values are stored in JSON format in securestorage.dat inside the app's data folder.

Limitations

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