Migrowanie z bezpiecznego magazynu platformy Xamarin.Essentials do bezpiecznego magazynu programu .NET MAUI

Artykuł
05/14/2024

Interfejs użytkownika wieloplatformowych aplikacji platformy Xamarin.Essentials (.NET MAUI) ma zarówno klasę SecureStorage ułatwiającą bezpieczne przechowywanie prostych par klucz/wartość. Istnieją jednak różnice implementacji między klasą SecureStorage W zestawie narzędzi Xamarin.Essentials i .NET MAUI:

Platforma	Xamarin.Essentials	.NET MAUI
Android	Magazyn kluczy systemu Android służy do przechowywania klucza szyfrowania używanego do szyfrowania wartości przed zapisaniem go w udostępnionym obiekcie preferencji o nazwie {your-app-package-id}.xamarinessentials.	Dane są szyfrowane przy `EncryptedSharedPreferences` użyciu klasy, która opakowuje klasę `SharedPreferences` , i automatycznie szyfruje klucze i wartości. Używana nazwa to {your-app-package-id}.microsoft.maui.essentials.preferences.
iOS	Pęk kluczy służy do bezpiecznego przechowywania wartości. Wartości `SecRecord` używane do przechowywania mają ustawioną `Service` wartość {your-app-package-id}.xamarinessentials.	Pęk kluczy służy do bezpiecznego przechowywania wartości. Wartości `SecRecord` używane do przechowywania mają ustawioną `Service` wartość {your-app-package-id}.microsoft.maui.essentials.preferences.

Aby uzyskać więcej informacji na temat SecureStorage klasy na platformie Xamarin.Essentials, zobacz Xamarin.Essentials: Bezpieczny magazyn. Aby uzyskać więcej informacji na temat SecureStorage klasy w programie .NET MAUI, zobacz Bezpieczny magazyn.

Podczas migrowania aplikacji platformy Xamarin.Forms korzystającej z klasy do interfejsu SecureStorage MAUI platformy .NET należy radzić sobie z tymi różnicami implementacji, aby zapewnić użytkownikom bezproblemowe środowisko uaktualniania. W tym artykule opisano sposób użycia LegacySecureStorage klas i klas pomocników do obsługi różnic implementacji. Klasa LegacySecureStorage umożliwia aplikacji .NET MAUI w systemach Android i iOS odczytywanie bezpiecznych danych magazynu utworzonych przy użyciu poprzedniej wersji platformy Xamarin.Forms aplikacji.

Uzyskiwanie dostępu do starszych danych bezpiecznego magazynu

Poniższy kod przedstawia klasę LegacySecureStorage , która zapewnia bezpieczną implementację magazynu z platformy Xamarin.Essentials:

Uwaga

Aby użyć tego kodu, dodaj go do klasy o nazwie LegacySecureStorage w projekcie aplikacji .NET MAUI.

#nullable enable
#if ANDROID || IOS

namespace MigrationHelpers;

public class LegacySecureStorage
{
    internal static readonly string Alias = $"{AppInfo.PackageName}.xamarinessentials";

    public static Task<string> GetAsync(string key)
    {
        if (string.IsNullOrWhiteSpace(key))
            throw new ArgumentNullException(nameof(key));

        string result = string.Empty;

#if ANDROID
        object locker = new object();
        string? encVal = Preferences.Get(key, null, Alias);

        if (!string.IsNullOrEmpty(encVal))
        {
            byte[] encData = Convert.FromBase64String(encVal);
            lock (locker)
            {
                AndroidKeyStore keyStore = new AndroidKeyStore(Platform.AppContext, Alias, false);
                result = keyStore.Decrypt(encData);
            }
        }
#elif IOS
        KeyChain keyChain = new KeyChain();
        result = keyChain.ValueForKey(key, Alias);
#endif
        return Task.FromResult(result);
    }

    public static bool Remove(string key)
    {
        bool result = false;

#if ANDROID
        Preferences.Remove(key, Alias);
        result = true;
#elif IOS
        KeyChain keyChain = new KeyChain();
        result = keyChain.Remove(key, Alias);
#endif
        return result;
    }

    public static void RemoveAll()
    {
#if ANDROID
        Preferences.Clear(Alias);
#elif IOS
        KeyChain keyChain = new KeyChain();
        keyChain.RemoveAll(Alias);
#endif
    }
}
#endif

Android

W systemie Android LegacySecureStorage klasa używa AndroidKeyStore klasy do przechowywania klucza szyfrowania używanego do szyfrowania wartości przed zapisaniem go w udostępnionym obiekcie preferencji o nazwie {your-app-package-id}.xamarinessentials. Poniższy kod przedstawia klasę AndroidKeyStore :

Uwaga

Aby użyć tego kodu, dodaj go do klasy o nazwie AndroidKeyStore w folderze Platforms\Android projektu aplikacji .NET MAUI.

using Android.Content;
using Android.OS;
using Android.Runtime;
using Android.Security;
using Android.Security.Keystore;
using Java.Security;
using Javax.Crypto;
using Javax.Crypto.Spec;
using System.Text;

namespace MigrationHelpers;

class AndroidKeyStore
{
    const string androidKeyStore = "AndroidKeyStore"; // this is an Android const value
    const string aesAlgorithm = "AES";
    const string cipherTransformationAsymmetric = "RSA/ECB/PKCS1Padding";
    const string cipherTransformationSymmetric = "AES/GCM/NoPadding";
    const string prefsMasterKey = "SecureStorageKey";
    const int initializationVectorLen = 12; // Android supports an IV of 12 for AES/GCM

    internal AndroidKeyStore(Context context, string keystoreAlias, bool alwaysUseAsymmetricKeyStorage)
    {
        alwaysUseAsymmetricKey = alwaysUseAsymmetricKeyStorage;
        appContext = context;
        alias = keystoreAlias;

        keyStore = KeyStore.GetInstance(androidKeyStore);
        keyStore.Load(null);
    }

    readonly Context appContext;
    readonly string alias;
    readonly bool alwaysUseAsymmetricKey;
    readonly string useSymmetricPreferenceKey = "essentials_use_symmetric";

    KeyStore keyStore;
    bool useSymmetric = false;

    ISecretKey GetKey()
    {
        // check to see if we need to get our key from past-versions or newer versions.
        // we want to use symmetric if we are >= 23 or we didn't set it previously.
        var hasApiLevel = Build.VERSION.SdkInt >= BuildVersionCodes.M;

        useSymmetric = Preferences.Get(useSymmetricPreferenceKey, hasApiLevel, alias);

        // If >= API 23 we can use the KeyStore's symmetric key
        if (useSymmetric && !alwaysUseAsymmetricKey)
            return GetSymmetricKey();

        // NOTE: KeyStore in < API 23 can only store asymmetric keys
        // specifically, only RSA/ECB/PKCS1Padding
        // So we will wrap our symmetric AES key we just generated
        // with this and save the encrypted/wrapped key out to
        // preferences for future use.
        // ECB should be fine in this case as the AES key should be
        // contained in one block.

        // Get the asymmetric key pair
        var keyPair = GetAsymmetricKeyPair();

        var existingKeyStr = Preferences.Get(prefsMasterKey, null, alias);

        if (!string.IsNullOrEmpty(existingKeyStr))
        {
            try
            {
                var wrappedKey = Convert.FromBase64String(existingKeyStr);

                var unwrappedKey = UnwrapKey(wrappedKey, keyPair.Private);
                var kp = unwrappedKey.JavaCast<ISecretKey>();

                return kp;
            }
            catch (InvalidKeyException ikEx)
            {
                System.Diagnostics.Debug.WriteLine($"Unable to unwrap key: Invalid Key. This may be caused by system backup or upgrades. All secure storage items will now be removed. {ikEx.Message}");
            }
            catch (IllegalBlockSizeException ibsEx)
            {
                System.Diagnostics.Debug.WriteLine($"Unable to unwrap key: Illegal Block Size. This may be caused by system backup or upgrades. All secure storage items will now be removed. {ibsEx.Message}");
            }
            catch (BadPaddingException paddingEx)
            {
                System.Diagnostics.Debug.WriteLine($"Unable to unwrap key: Bad Padding. This may be caused by system backup or upgrades. All secure storage items will now be removed. {paddingEx.Message}");
            }
            LegacySecureStorage.RemoveAll();
        }

        var keyGenerator = KeyGenerator.GetInstance(aesAlgorithm);
        var defSymmetricKey = keyGenerator.GenerateKey();

        var newWrappedKey = WrapKey(defSymmetricKey, keyPair.Public);

        Preferences.Set(prefsMasterKey, Convert.ToBase64String(newWrappedKey), alias);

        return defSymmetricKey;
    }

    // API 23+ Only
#pragma warning disable CA1416
    ISecretKey GetSymmetricKey()
    {
        Preferences.Set(useSymmetricPreferenceKey, true, alias);

        var existingKey = keyStore.GetKey(alias, null);

        if (existingKey != null)
        {
            var existingSecretKey = existingKey.JavaCast<ISecretKey>();
            return existingSecretKey;
        }

        var keyGenerator = KeyGenerator.GetInstance(KeyProperties.KeyAlgorithmAes, androidKeyStore);
        var builder = new KeyGenParameterSpec.Builder(alias, KeyStorePurpose.Encrypt | KeyStorePurpose.Decrypt)
            .SetBlockModes(KeyProperties.BlockModeGcm)
            .SetEncryptionPaddings(KeyProperties.EncryptionPaddingNone)
            .SetRandomizedEncryptionRequired(false);

        keyGenerator.Init(builder.Build());

        return keyGenerator.GenerateKey();
    }
#pragma warning restore CA1416

    KeyPair GetAsymmetricKeyPair()
    {
        // set that we generated keys on pre-m device.
        Preferences.Set(useSymmetricPreferenceKey, false, alias);

        var asymmetricAlias = $"{alias}.asymmetric";

        var privateKey = keyStore.GetKey(asymmetricAlias, null)?.JavaCast<IPrivateKey>();
        var publicKey = keyStore.GetCertificate(asymmetricAlias)?.PublicKey;

        // Return the existing key if found
        if (privateKey != null && publicKey != null)
            return new KeyPair(publicKey, privateKey);

        var originalLocale = Java.Util.Locale.Default;
        try
        {
            // Force to english for known bug in date parsing:
            // https://issuetracker.google.com/issues/37095309
            SetLocale(Java.Util.Locale.English);

            // Otherwise we create a new key
#pragma warning disable CA1416
            var generator = KeyPairGenerator.GetInstance(KeyProperties.KeyAlgorithmRsa, androidKeyStore);
#pragma warning restore CA1416

            var end = DateTime.UtcNow.AddYears(20);
            var startDate = new Java.Util.Date();
#pragma warning disable CS0618 // Type or member is obsolete
            var endDate = new Java.Util.Date(end.Year, end.Month, end.Day);
#pragma warning restore CS0618 // Type or member is obsolete

#pragma warning disable CS0618
            var builder = new KeyPairGeneratorSpec.Builder(Platform.AppContext)
                .SetAlias(asymmetricAlias)
                .SetSerialNumber(Java.Math.BigInteger.One)
                .SetSubject(new Javax.Security.Auth.X500.X500Principal($"CN={asymmetricAlias} CA Certificate"))
                .SetStartDate(startDate)
                .SetEndDate(endDate);

            generator.Initialize(builder.Build());
#pragma warning restore CS0618

            return generator.GenerateKeyPair();
        }
        finally
        {
            SetLocale(originalLocale);
        }
    }

    byte[] WrapKey(IKey keyToWrap, IKey withKey)
    {
        var cipher = Cipher.GetInstance(cipherTransformationAsymmetric);
        cipher.Init(CipherMode.WrapMode, withKey);
        return cipher.Wrap(keyToWrap);
    }

#pragma warning disable CA1416
    IKey UnwrapKey(byte[] wrappedData, IKey withKey)
    {
        var cipher = Cipher.GetInstance(cipherTransformationAsymmetric);
        cipher.Init(CipherMode.UnwrapMode, withKey);
        var unwrapped = cipher.Unwrap(wrappedData, KeyProperties.KeyAlgorithmAes, KeyType.SecretKey);
        return unwrapped;
    }
#pragma warning restore CA1416

    internal string Decrypt(byte[] data)
    {
        if (data.Length < initializationVectorLen)
            return null;

        var key = GetKey();

        // IV will be the first 16 bytes of the encrypted data
        var iv = new byte[initializationVectorLen];
        Buffer.BlockCopy(data, 0, iv, 0, initializationVectorLen);

        Cipher cipher;

        // Attempt to use GCMParameterSpec by default
        try
        {
            cipher = Cipher.GetInstance(cipherTransformationSymmetric);
            cipher.Init(CipherMode.DecryptMode, key, new GCMParameterSpec(128, iv));
        }
        catch (InvalidAlgorithmParameterException)
        {
            // If we encounter this error, it's likely an old bouncycastle provider version
            // is being used which does not recognize GCMParameterSpec, but should work
            // with IvParameterSpec, however we only do this as a last effort since other
            // implementations will error if you use IvParameterSpec when GCMParameterSpec
            // is recognized and expected.
            cipher = Cipher.GetInstance(cipherTransformationSymmetric);
            cipher.Init(CipherMode.DecryptMode, key, new IvParameterSpec(iv));
        }

        // Decrypt starting after the first 16 bytes from the IV
        var decryptedData = cipher.DoFinal(data, initializationVectorLen, data.Length - initializationVectorLen);

        return Encoding.UTF8.GetString(decryptedData);
    }

    internal void SetLocale(Java.Util.Locale locale)
    {
        Java.Util.Locale.Default = locale;
        var resources = appContext.Resources;
        var config = resources.Configuration;

        if (Build.VERSION.SdkInt >= BuildVersionCodes.N)
            config.SetLocale(locale);
        else
#pragma warning disable CS0618 // Type or member is obsolete
            config.Locale = locale;
#pragma warning restore CS0618 // Type or member is obsolete

#pragma warning disable CS0618 // Type or member is obsolete
        resources.UpdateConfiguration(config, resources.DisplayMetrics);
#pragma warning restore CS0618 // Type or member is obsolete
    }
}

Magazyn kluczy systemu Android służy do przechowywania klucza szyfrowania używanego do szyfrowania wartości przed zapisaniem go w pliku preferencji udostępnionycho nazwie {your-app-package-id}.xamarinessentials. Klucz (a nie klucz kryptograficzny, klucz do wartości) używany w udostępnionym pliku preferencji jest skrótem MD5 klucza przekazanego SecureStorage do interfejsów API.

W interfejsie API 23 lub nowszym klucz AES jest uzyskiwany z magazynu kluczy systemu Android i używany z szyfrem AES/GCM/NoPadding w celu zaszyfrowania wartości przed zapisaniem go w udostępnionym pliku preferencji. W przypadku interfejsu API 22 i niższego magazyn kluczy systemu Android obsługuje tylko przechowywanie kluczy RSA, które są używane z szyfrem RSA/EBC/PKCS1Padding w celu szyfrowania klucza AES (generowanego losowo w czasie wykonywania) i przechowywanego w udostępnionym pliku preferencji w kluczu SecureStorageKey, jeśli jeszcze nie został wygenerowany.

iOS

W systemie iOS LegacySecureStorage klasa używa KeyChain klasy do bezpiecznego przechowywania wartości. Wartości SecRecord używane do przechowywania mają ustawioną Service wartość {your-app-package-id}.xamarinessentials. Poniższy kod przedstawia klasę KeyChain :

Uwaga

Aby użyć tego kodu, dodaj go do klasy o nazwie KeyChain w folderze Platforms\iOS projektu aplikacji .NET MAUI.

using Foundation;
using Security;

namespace MigrationHelpers;

class KeyChain
{
    SecRecord ExistingRecordForKey(string key, string service)
    {
        return new SecRecord(SecKind.GenericPassword)
        {
            Account = key,
            Service = service
        };
    }

    internal string ValueForKey(string key, string service)
    {
        using (var record = ExistingRecordForKey(key, service))
        using (var match = SecKeyChain.QueryAsRecord(record, out var resultCode))
        {
            if (resultCode == SecStatusCode.Success)
                return NSString.FromData(match.ValueData, NSStringEncoding.UTF8);
            else
                return null;
        }
    }

    internal bool Remove(string key, string service)
    {
        using (var record = ExistingRecordForKey(key, service))
        using (var match = SecKeyChain.QueryAsRecord(record, out var resultCode))
        {
            if (resultCode == SecStatusCode.Success)
            {
                RemoveRecord(record);
                return true;
            }
        }
        return false;
    }

    internal void RemoveAll(string service)
    {
        using (var query = new SecRecord(SecKind.GenericPassword) { Service = service })
        {
            SecKeyChain.Remove(query);
        }
    }

    bool RemoveRecord(SecRecord record)
    {
        var result = SecKeyChain.Remove(record);
        if (result != SecStatusCode.Success && result != SecStatusCode.ItemNotFound)
            throw new Exception($"Error removing record: {result}");

        return true;
    }
}

Aby użyć tego kodu, musisz mieć plik Entitlements.plist dla aplikacji systemu iOS z zestawem uprawnień pęku kluczy:

<key>keychain-access-groups</key>
<array>
  <string>$(AppIdentifierPrefix)$(CFBundleIdentifier)</string>
</array>

Należy również upewnić się, że plik Entitlements.plist jest ustawiony jako pole Uprawnienia niestandardowe w ustawieniach podpisywania pakietu dla aplikacji. Aby uzyskać więcej informacji, zobacz Uprawnienia systemu iOS.

Korzystanie ze starszych bezpiecznych danych magazynu

Klasa LegacySecureStorage może służyć do korzystania ze starszych bezpiecznych danych magazynu w systemach Android i iOS utworzonych przy użyciu poprzedniej wersji platformy Xamarin.Forms aplikacji:

#if ANDROID || IOS
using MigrationHelpers;
...

string username = await LegacySecureStorage.GetAsync("username");
bool result = LegacySecureStorage.Remove("username");
await SecureStorage.SetAsync("username", username);
#endif

W przykładzie LegacySecureStorage pokazano użycie klasy do odczytywania i usuwania wartości ze starszego bezpiecznego magazynu, a następnie zapisywania wartości w bezpiecznym magazynie .NET MAUI.

Udostępnij za pośrednictwem

Migrowanie z bezpiecznego magazynu platformy Xamarin.Essentials do bezpiecznego magazynu programu .NET MAUI

Uzyskiwanie dostępu do starszych danych bezpiecznego magazynu

Android

iOS

Korzystanie ze starszych bezpiecznych danych magazynu

Dodatkowe zasoby