title | description | ms.date | no-loc | |||
---|---|---|---|---|---|---|
Secure storage |
Learn how to use the .NET MAUI ISecureStorage interface, which helps securely store simple key/value pairs. This article discusses how to use the ISecureStorage, platform implementation specifics, and its limitations. |
10/24/2022 |
|
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.
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.
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>
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.
-
Set the
android:fullBackupContent
attribute in your AndroidManifest.xml:<application ... android:fullBackupContent="@xml/auto_backup_rules"> </application>
-
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>
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.
No setup is required.
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.
To save a value for a given key in secure storage:
:::code language="csharp" source="../snippets/shared_1/Storage.cs" id="secstorage_set":::
To retrieve a value from secure storage:
:::code language="csharp" source="../snippets/shared_1/Storage.cs" id="secstorage_get":::
Tip
If there isn't a value associated with the key, GetAsync
returns null
.
To remove a specific value, remove the key:
:::code language="csharp" source="../snippets/shared_1/Storage.cs" id="secstorage_remove":::
To remove all values, use the RemoveAll
method:
:::code language="csharp" source="../snippets/shared_1/Storage.cs" id="secstorage_remove_all":::
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.
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.
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.
Performance may be impacted if you store large amounts of text, as the API was designed to store small amounts of text.