Xamarin.Essentials: Almacenamiento seguroXamarin.Essentials: Secure Storage

La clase SecureStorage ayuda a almacenar pares de clave-valor sencillos de manera segura.The SecureStorage class helps securely store simple key/value pairs.

Primeros pasosGet started

Para empezar a usar esta API, lea la guía de introducción para Xamarin.Essentials con el fin de asegurarse de que la biblioteca está correctamente instalada y configurada en los proyectos.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.

Para acceder a la funcionalidad SecureStorage, se requiere la siguiente configuración específica para la plataforma:To access the SecureStorage functionality, the following platform-specific setup is required:

Sugerencia

Copia de seguridad para aplicaciones es una característica de Android 6.0 (nivel de API 23) y versiones posteriores que crea copias de seguridad de los datos de aplicación del usuario (preferencias compartidas, archivos en el almacenamiento interno de la aplicación y otros archivos específicos).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). Los datos se restauran cuando se reinstala o instala una aplicación en un dispositivo nuevo.Data is restored when an app is re-installed or installed on a new device. Esto puede afectar a SecureStorage, que utiliza las preferencias compartidas de las que se creó una copia de seguridad y que no se pueden descifrar cuando se realiza la restauración.This can impact SecureStorage which utilizes share preferences that are backed up and can not be decrypted when the restore occurs. Xamarin.Essentials controla automáticamente este caso al quitar la clave para que se pueda restablecer, pero puede dar un paso adicional si deshabilita Copia de seguridad automática.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.

Habilitación o deshabilitación de copia de seguridadEnable or disable backup

Puede elegir deshabilitar Copia de seguridad automática para toda la aplicación al establecer el valor android:allowBackup en false en el archivo AndroidManifest.xml.You can choose to disable Auto Backup for your entire application by setting the android:allowBackup setting to false in the AndroidManifest.xml file. Este enfoque solo se recomienda si planea restaurar los datos de otra manera.This approach is only recommended if you plan on restoring data in another way.

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

Copia de seguridad selectivaSelective Backup

Es posible configurar Copia de seguridad automática para deshabilitar la copia de seguridad de contenido específico.Auto Backup can be configured to disable specific content from backing up. Puede crear un conjunto de reglas personalizadas para excluir los elementos SecureStore de la copia de seguridad.You can create a custom rule set to exclude SecureStore items from being backed up.

  1. Establezca el atributo android:fullBackupContent en AndroidManifest.xml:Set the android:fullBackupContent attribute in your AndroidManifest.xml:

    <application ...
        android:fullBackupContent="@xml/auto_backup_rules">
    </application>
    
  2. Cree un archivo XML denominado auto_backup_rules.xml en el directorio Resources/xml con la acción de compilación AndroidResource.Create a new XML file named auto_backup_rules.xml in the Resources/xml directory with the build action of AndroidResource. Luego, establezca este contenido que incluye todas las preferencias compartidas, excepto SecureStorage: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>
    

Uso de Secure StorageUsing Secure Storage

Agregue una referencia a Xamarin.Essentials en su clase:Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

Para guardar un valor para una clave determinada en el almacenamiento seguro: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.
}

Para recuperar un valor desde el almacenamiento seguro: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.
}

Nota

Si no hay ningún valor asociado con la clave solicitada, GetAsync devolverá null.If there is no value associated with the requested key, GetAsync will return null.

Para quitar una clave específica, llame a:To remove a specific key, call:

SecureStorage.Remove("oauth_token");

Para quitar todas las claves, llame a:To remove all keys, call:

SecureStorage.RemoveAll();

Detalles de implementación de la plataformaPlatform Implementation Specifics

Android KeyStore se usa para almacenar la clave de cifrado con la que se cifra el valor antes de guardarlo en Preferencias compartidas con un nombre de archivo [ID-PAQUETE-APLICACIÓN].xamarinessentials.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. La clave (no una clave criptográfica, la clave para el valor) usada en el archivo de preferencias compartido es un hash MD5 de la clave pasada a las API SecureStorage.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.

Nivel de API 23 y superiorAPI Level 23 and Higher

En los niveles de API más nuevos, una clave AES se obtiene de Android KeyStore y se usa con una cifra AES/GCM/NoPadding para cifrar el valor antes de que se almacene en el archivo de preferencias compartidas.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.

Nivel de API 22 e inferiorAPI Level 22 and Lower

En los niveles de API anteriores, Android KeyStore solo admite el almacenamiento de claves RSA, que se usa con una cifra RSA/ECB/PKCS1Padding para cifrar una clave AES (generada de manera aleatoria en tiempo de ejecución) y se almacena en el archivo de preferencias compartidas en la clave SecureStorageKey, si todavía no se ha generado una.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 usa la API Preferences y sigue la misma persistencia de datos que se describe en la documentación sobre Preferencias.SecureStorage uses the Preferences API and follows the same data persistence outlined in the Preferences documentation. Si se actualiza un dispositivo desde Nivel de API 22 o inferior a Nivel de API 23 y superior, se seguirá usando este tipo de cifrado a menos que la aplicación se desinstale o se llame a RemoveAll.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.

LimitacionesLimitations

Esta API está pensada para almacenar pequeñas cantidades de texto.This API is intended to store small amounts of text. El rendimiento puede ser lento si intenta usarla para almacenar grandes cantidades de texto.Performance may be slow if you try to use it to store large amounts of text.

APIAPI

Encuentre más vídeos de Xamarin en Channel 9 y YouTube.Find more Xamarin videos on Channel 9 and YouTube.