Udostępnij za pośrednictwem

Rozszerzalność kryptografii podstawowej w ASP.NET Core

  • Artykuł

Ostrzeżenie

Typy implementujące dowolny z następujących interfejsów powinny być bezpieczne wątkowo dla wielu wywołujących.

IAuthenticatedEncryptor

Interfejs IAuthenticatedEncryptor to podstawowy blok konstrukcyjny podsystemu kryptograficznego. Zazwyczaj istnieje jeden element IAuthenticatedEncryptor na klucz, a wystąpienie IAuthenticatedEncryptor opakowuje wszystkie materiały klucza kryptograficznego i informacje algorytmiczne niezbędne do wykonywania operacji kryptograficznych.

Jak sugeruje jego nazwa, typ jest odpowiedzialny za dostarczanie uwierzytelnionych usług szyfrowania i odszyfrowywania. Uwidacznia następujące dwa interfejsy API.

  • Decrypt(ArraySegment<byte> ciphertext, ArraySegment<byte> additionalAuthenticatedData) : byte[]

  • Encrypt(ArraySegment<byte> plaintext, ArraySegment<byte> additionalAuthenticatedData) : byte[]

Metoda Encrypt zwraca obiekt blob zawierający zaszyfrowany zwykły tekst i tag uwierzytelniania. Tag uwierzytelniania musi obejmować dodatkowe uwierzytelnione dane (AAD), chociaż sama usługa AAD nie musi być odzyskiwalna z końcowego ładunku. Metoda Decrypt weryfikuje tag uwierzytelniania i zwraca rozszyfrowany ładunek. Wszystkie błędy (z wyjątkiem ArgumentNullException i podobne) powinny być homogenizowane na Wartość CryptographicException.

Uwaga

Samo wystąpienie IAuthenticatedEncryptor nie musi zawierać materiału klucza. Na przykład implementacja może delegować do modułu HSM dla wszystkich operacji.

Jak utworzyć element IAuthenticatedEncryptor

Interfejs IAuthenticatedEncryptorFactory reprezentuje typ, który wie, jak utworzyć wystąpienie IAuthenticatedEncryptor . Jego interfejs API jest następujący.

  • CreateEncryptorInstance(klucz IKey): IAuthenticatedEncryptor

W przypadku dowolnego wystąpienia IKey wszystkie uwierzytelnione szyfratory utworzone przez metodę CreateEncryptorInstance powinny być traktowane jako równoważne, jak w poniższym przykładzie kodu.

// we have an IAuthenticatedEncryptorFactory instance and an IKey instance
IAuthenticatedEncryptorFactory factory = ...;
IKey key = ...;

// get an encryptor instance and perform an authenticated encryption operation
ArraySegment<byte> plaintext = new ArraySegment<byte>(Encoding.UTF8.GetBytes("plaintext"));
ArraySegment<byte> aad = new ArraySegment<byte>(Encoding.UTF8.GetBytes("AAD"));
var encryptor1 = factory.CreateEncryptorInstance(key);
byte[] ciphertext = encryptor1.Encrypt(plaintext, aad);

// get another encryptor instance and perform an authenticated decryption operation
var encryptor2 = factory.CreateEncryptorInstance(key);
byte[] roundTripped = encryptor2.Decrypt(new ArraySegment<byte>(ciphertext), aad);


// the 'roundTripped' and 'plaintext' buffers should be equivalent

IAuthenticatedEncryptorDescriptor (tylko ASP.NET Core 2.x)

Interfejs IAuthenticatedEncryptorDescriptor reprezentuje typ, który wie, jak wyeksportować się do kodu XML. Jego interfejs API jest następujący.

  • ExportToXml() : XmlSerializedDescriptorInfo

Serializacji XML

Podstawową różnicą między elementami IAuthenticatedEncryptor i IAuthenticatedEncryptorDescriptor jest to, że deskryptor wie, jak utworzyć program szyfrujący i podać go prawidłowymi argumentami. Rozważ element IAuthenticatedEncryptor, którego implementacja opiera się na SymmetricAlgorithm i KeyedHashAlgorithm. Zadanie szyfrora polega na użyciu tych typów, ale niekoniecznie wie, skąd pochodzą te typy, więc nie może on naprawdę napisać prawidłowy opis sposobu ponownego utworzenia aplikacji, jeśli aplikacja zostanie uruchomiona ponownie. Deskryptor działa jako wyższy poziom na tym poziomie. Ponieważ deskryptor wie, jak utworzyć wystąpienie modułu szyfrowania (np. wie, jak utworzyć wymagane algorytmy), może serializować wiedzę w postaci XML, aby można było odtworzyć wystąpienie szyfrera po zresetowaniu aplikacji.

Deskryptor można serializować za pomocą procedury ExportToXml. Ta rutyna zwraca element XmlSerializedDescriptorInfo zawierający dwie właściwości: reprezentację XElement deskryptora i typ, który reprezentuje element IAuthenticatedEncryptorDescriptorDeserializer , który może służyć do wskrzeszania tego deskryptora, biorąc pod uwagę odpowiedni element XElement.

Serializowany deskryptor może zawierać poufne informacje, takie jak materiał klucza kryptograficznego. System ochrony danych ma wbudowaną obsługę szyfrowania informacji przed utrwalone w magazynie. Aby to wykorzystać, deskryptor powinien oznaczyć element zawierający poufne informacje o nazwie atrybutu "requiresEncryption" (xmlns "<http://schemas.asp.net/2015/03/dataProtection>"), wartość "true".

Napiwek

Istnieje interfejs API pomocnika służący do ustawiania tego atrybutu. Wywołaj metodę rozszerzenia XElement.MarkAsRequiresEncryption() znajdującą się w przestrzeni nazw Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel.

Mogą również wystąpić przypadki, w których deskryptor serializowany nie zawiera poufnych informacji. Rozważ ponownie przypadek klucza kryptograficznego przechowywanego w module HSM. Deskryptor nie może wypisać materiału klucza podczas serializacji, ponieważ moduł HSM nie uwidacznia materiału w postaci zwykłego tekstu. Zamiast tego deskryptor może zapisać wersję klucza opakowaną kluczem (jeśli moduł HSM zezwala na eksportowanie w ten sposób) lub własny unikatowy identyfikator modułu HSM dla klucza.

IAuthenticatedEncryptorDescriptorDeserializer

Interfejs IAuthenticatedEncryptorDescriptorDeserializer reprezentuje typ, który wie, jak deserializować wystąpienie IAuthenticatedEncryptorDescriptor z elementu XElement. Uwidacznia jedną metodę:

  • ImportFromXml(element XElement): IAuthenticatedEncryptorDescriptor

Metoda ImportFromXml przyjmuje element XElement zwrócony przez element IAuthenticatedEncryptorDescriptor.ExportToXml i tworzy odpowiednik oryginalnego elementu IAuthenticatedEncryptorDescriptor.

Typy implementowane IAuthenticatedEncryptorDescriptorDeserializer powinny mieć jeden z następujących dwóch konstruktorów publicznych:

  • .ctor(IServiceProvider)

  • .ctor()

Uwaga

Element IServiceProvider przekazany do konstruktora może mieć wartość null.

Fabryka najwyższego poziomu

Klasa AlgorithmConfiguration reprezentuje typ, który wie, jak utworzyć wystąpienia IAuthenticatedEncryptorDescriptor . Uwidacznia pojedynczy interfejs API.

  • CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

Funkcja AlgorithmConfiguration jest fabryką najwyższego poziomu. Konfiguracja służy jako szablon. Opakowuje on informacje algorytmiczne (np. ta konfiguracja tworzy deskryptory z kluczem głównym AES-128-GCM), ale nie jest jeszcze skojarzony z określonym kluczem.

Po wywołaniu metody CreateNewDescriptor tworzony jest świeży materiał klucza wyłącznie dla tego wywołania, a nowy element IAuthenticatedEncryptorDescriptor jest tworzony, który opakowuje ten materiał klucza i informacje algorytmiczne wymagane do korzystania z materiału. Materiał klucza można utworzyć w oprogramowaniu (i przechowywać w pamięci), można go utworzyć i przechowywać w module HSM itd. Kluczowym punktem jest to, że wszystkie dwa wywołania metody CreateNewDescriptor nigdy nie powinny tworzyć równoważnych wystąpień IAuthenticatedEncryptorDescriptor.

Typ AlgorithmConfiguration służy jako punkt wejścia dla procedur tworzenia kluczy, takich jak automatyczne kroczenie klucza. Aby zmienić implementację wszystkich przyszłych kluczy, ustaw właściwość AuthenticatedEncryptorConfiguration w polu KeyManagementOptions.