Rozšiřitelnost kryptografie jádra v ASP.NET Core

Upozorňující

Typy, které implementují některé z následujících rozhraní, by měly být pro více volajících bezpečné pro více volajících.

IAuthenticatedEncryptor

Rozhraní IAuthenticatedEncryptor je základní stavební blok kryptografického subsystému. Obecně existuje jeden IAuthenticatedEncryptor na klíč a instance IAuthenticatedEncryptor zabalí všechny kryptografické klíče materiál a algoritmické informace potřebné k provádění kryptografických operací.

Jak název napovídá, typ zodpovídá za poskytování ověřených služeb šifrování a dešifrování. Zveřejňuje následující dvě rozhraní API.

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

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

Metoda Encrypt vrátí objekt blob, který obsahuje šifrovaný prostý text a ověřovací značku. Ověřovací značka musí zahrnovat další ověřená data (AAD), i když samotná AAD nemusí být obnovitelná z konečné datové části. Metoda Decrypt ověří značku ověřování a vrátí dešifrovanou datovou část. Všechna selhání (s výjimkou ArgumentNullException a podobné) by měla být homogenizována pro kryptografickýexception.

Poznámka

Samotná instance IAuthenticatedEncryptor nemusí ve skutečnosti obsahovat klíčový materiál. Implementace může například delegovat na HSM pro všechny operace.

Jak vytvořit IAuthenticatedEncryptor

ASP.NET Core 2.x

IAuthenticatedEncryptorFactory rozhraní představuje typ, který ví, jak vytvořit IAuthenticatedEncryptor instance. Jeho rozhraní API je následující.

• CreateEncryptorInstance(klíč IKey): IAuthenticatedEncryptor

U každé dané instance IKey by měly být všechny ověřené šifrátory vytvořené metodou CreateEncryptorInstance považovány za ekvivalentní, jako v následující ukázce kódu.

// 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

ASP.NET Core 1.x

IAuthenticatedEncryptorDescriptor rozhraní představuje typ, který ví, jak vytvořit IAuthenticatedEncryptor instance. Jeho rozhraní API je následující.

• CreateEncryptorInstance() : IAuthenticatedEncryptor

• ExportToXml() : XmlSerializedDescriptorInfo

Podobně jako IAuthenticatedEncryptor se předpokládá, že instance IAuthenticatedEncryptorDescriptor zabalí jeden konkrétní klíč. To znamená, že pro všechny dané instance IAuthenticatedEncryptorDescriptor by všechny ověřené šifrované šifrory vytvořené metodou CreateEncryptorInstance měly být považovány za ekvivalentní, jako v následující ukázce kódu.

// we have an IAuthenticatedEncryptorDescriptor instance
IAuthenticatedEncryptorDescriptor descriptor = ...;

// 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 = descriptor.CreateEncryptorInstance();
byte[] ciphertext = encryptor1.Encrypt(plaintext, aad);

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


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

IAuthenticatedEncryptorDescriptor (pouze ASP.NET Core 2.x)

ASP.NET Core 2.x

IAuthenticatedEncryptorDescriptor rozhraní představuje typ, který ví, jak exportovat do XML. Jeho rozhraní API je následující.

• ExportToXml() : XmlSerializedDescriptorInfo

ASP.NET Core 1.x

Serializace XML

Primární rozdíl mezi IAuthenticatedEncryptor a IAuthenticatedEncryptorDescriptor je, že popisovač ví, jak vytvořit encryptor a zadat ho platnými argumenty. Zvažte IAuthenticatedEncryptor, jehož implementace spoléhá na SymmetricAlgorithm a KeyedHashAlgorithm. Úloha šifrátoru je využívat tyto typy, ale nemusí nutně vědět, odkud tyto typy pocházejí, takže ve skutečnosti nemůže napsat správný popis, jak se znovu vytvořit, pokud se aplikace restartuje. Popisovač funguje jako vyšší úroveň nad tímto popisovačem. Vzhledem k tomu, že popisovač ví, jak vytvořit instanci encryptoru (např. ví, jak vytvořit požadované algoritmy), může serializovat znalosti ve formuláři XML, aby bylo možné instanci encryptoru znovu vytvořit po resetování aplikace.

Popisovač lze serializovat pomocí rutiny ExportToXml. Tato rutina vrátí XmlSerializedDescriptorInfo, která obsahuje dvě vlastnosti: XElement reprezentaci popisovače a Type, který představuje IAuthenticatedEncryptorDescriptorDescriptorDeserializer , který lze použít k obnovení tohoto popisovače vzhledem k odpovídající XElement.

Serializovaný popisovač může obsahovat citlivé informace, jako je kryptografický klíč materiál. Systém ochrany dat má integrovanou podporu šifrování informací, než se uloží do úložiště. Abyste toho mohli využít, měl by popisovač označit prvek, který obsahuje citlivé informace s názvem atributu "requiresEncryption" (xmlns "<http://schemas.asp.net/2015/03/dataProtection>"), hodnota "true".

Tip

Pro nastavení tohoto atributu je k dispozici pomocné rozhraní API. Volání metody rozšíření XElement.MarkAsRequiresEncryption() umístěné v oboru názvů Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel.

Existují také případy, kdy serializovaný popisovač neobsahuje citlivé informace. Zvažte znovu případ kryptografického klíče uloženého v HSM. Popisovač nemůže při serializaci sám zapsat materiál klíče, protože HSM nezpřístupní materiál ve formátu prostého textu. Místo toho může popisovač zapsat verzi klíče zabalenou klíčem (pokud modul hardwarového zabezpečení umožňuje export tímto způsobem) nebo vlastní jedinečný identifikátor HSM pro tento klíč.

IAuthenticatedEncryptorDescriptorDeserializer

IAuthenticatedEncryptorDescriptorDeserializer rozhraní představuje typ, který ví, jak deserializovat IAuthenticatedEncryptorDescriptor instance z XElement. Zveřejňuje jednu metodu:

• ImportFromXml(element XElement): IAuthenticatedEncryptorDescriptor

Metoda ImportFromXml přebírá XElement, který byl vrácen IAuthenticatedEncryptorDescriptor.ExportToXml a vytvoří ekvivalent původního IAuthenticatedEncryptorDescriptor.

Typy, které implementují IAuthenticatedEncryptorDescriptorDeserializer, by měly mít jeden z následujících dvou veřejných konstruktorů:

• .ctor(IServiceProvider)

• .ctor()

Poznámka

IServiceProvider předaný konstruktoru může mít hodnotu null.

Továrna nejvyšší úrovně

ASP.NET Core 2.x

Třída AlgorithmConfiguration představuje typ, který ví, jak vytvořit IAuthenticatedEncryptorDescriptor instance. Zveřejňuje jedno rozhraní API.

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

AlgoritmusConfiguration si můžete představit jako továrnu nejvyšší úrovně. Konfigurace slouží jako šablona. Zabalí algoritmické informace (například tato konfigurace vytvoří popisovače s hlavním klíčem AES-128-GCM), ale zatím není přidružená ke konkrétnímu klíči.

Při volání CreateNewDescriptor se vytvoří nový materiál klíče pouze pro toto volání a vytvoří se nový IAuthenticatedEncryptorDescriptor, který zabalí tento klíč materiál a algoritmické informace potřebné ke spotřebování materiálu. Klíčový materiál lze vytvořit v softwaru (a uchovávat v paměti), lze ho vytvořit a uchovávat v modulu HSM atd. Zásadním bodem je, že žádná dvě volání CreateNewDescriptor by nikdy neměla vytvářet ekvivalentní instance IAuthenticatedEncryptorDescriptor.

Typ AlgorithmConfiguration slouží jako vstupní bod pro rutiny vytváření klíčů, jako je například automatické vracení klíčů. Chcete-li změnit implementaci pro všechny budoucí klíče, nastavte AuthenticatedEncryptorConfiguration vlastnost v KeyManagementOptions.

ASP.NET Core 1.x

IAuthenticatedEncryptorConfiguration rozhraní představuje typ, který ví, jak vytvořit IAuthenticatedEncryptorDescriptor instance. Zveřejňuje jedno rozhraní API.

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

IAuthenticatedEncryptorConfiguration si můžete představit jako továrnu nejvyšší úrovně. Konfigurace slouží jako šablona. Zabalí algoritmické informace (například tato konfigurace vytvoří popisovače s hlavním klíčem AES-128-GCM), ale zatím není přidružená ke konkrétnímu klíči.

Při volání CreateNewDescriptor se vytvoří nový materiál klíče pouze pro toto volání a vytvoří se nový IAuthenticatedEncryptorDescriptor, který zabalí tento klíč materiál a algoritmické informace potřebné ke spotřebování materiálu. Klíčový materiál lze vytvořit v softwaru (a uchovávat v paměti), lze ho vytvořit a uchovávat v modulu HSM atd. Zásadním bodem je, že žádná dvě volání CreateNewDescriptor by nikdy neměla vytvářet ekvivalentní instance IAuthenticatedEncryptorDescriptor.

Typ IAuthenticatedEncryptorConfiguration slouží jako vstupní bod pro rutiny vytváření klíčů, jako je automatické vrácení klíče. Pokud chcete změnit implementaci pro všechny budoucí klíče, zaregistrujte v kontejneru služby singleton IAuthenticatedEncryptorConfiguration.