ASP.NET Core'da çekirdek şifreleme genişletilebilirliği

Uyarı

Aşağıdaki arabirimlerden herhangi birini uygulayan türler, birden çok arayan için iş parçacığı açısından güvenli olmalıdır.

IAuthenticatedEncryptor

IAuthenticatedEncryptor arabirimi, şifreleme alt sisteminin temel yapı taşıdır. Genellikle anahtar başına bir IAuthenticatedEncryptor vardır ve IAuthenticatedEncryptor örneği, şifreleme işlemlerini gerçekleştirmek için gereken tüm şifreleme anahtarı malzemelerini ve algoritma bilgilerini sarmalar.

Adından da anlaşılacağı gibi, türü kimliği doğrulanmış şifreleme ve şifre çözme hizmetleri sağlamakla sorumludur. Aşağıdaki iki API'yi kullanıma sunar.

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

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

Encrypt yöntemi, şifrelenen düz metni ve kimlik doğrulama etiketini içeren bir blob döndürür. Kimlik doğrulama etiketi ek kimliği doğrulanmış verileri (AAD) içermelidir ancak AAD'nin son yükten kurtarılabilir olması gerekmez. Decrypt yöntemi kimlik doğrulama etiketini doğrular ve deşifre edilmiş yükü döndürür. Tüm hatalar (ArgumentNullException ve benzeri hariç) CryptographicException ile homojenleştirilmelidir.

Not

IAuthenticatedEncryptor örneğinin aslında anahtar malzemeyi içermesi gerekmez. Örneğin, uygulama tüm işlemler için bir HSM'ye temsilci verebilir.

IAuthenticatedEncryptor oluşturma

ASP.NET Core 2.x

IAuthenticatedEncryptorFactory arabirimi, IAuthenticatedEncryptor örneğinin nasıl oluşturulacağını bilen bir türü temsil eder. API'leri aşağıdaki gibidir.

• CreateEncryptorInstance(IKey anahtarı) : IAuthenticatedEncryptor

Belirli bir IKey örneği için, aşağıdaki kod örneğinde olduğu gibi CreateEncryptorInstance yöntemi tarafından oluşturulan kimliği doğrulanmış tüm şifreleyiciler eşdeğer kabul edilmelidir.

// 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 arabirimi, IAuthenticatedEncryptor örneğinin nasıl oluşturulacağını bilen bir türü temsil eder. API'leri aşağıdaki gibidir.

• CreateEncryptorInstance() : IAuthenticatedEncryptor

• ExportToXml() : XmlSerializedDescriptorInfo

IAuthenticatedEncryptor gibi bir IAuthenticatedEncryptorDescriptor örneğinin de belirli bir anahtarı sarmalama olduğu varsayılır. Bu, belirli bir IAuthenticatedEncryptorDescriptor örneği için, aşağıdaki kod örneğinde olduğu gibi CreateEncryptorInstance yöntemi tarafından oluşturulan kimliği doğrulanmış tüm şifrelemecilerin eşdeğer olarak kabul edilmesi gerektiği anlamına gelir.

// 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 (yalnızca ASP.NET Core 2.x)

ASP.NET Core 2.x

IAuthenticatedEncryptorDescriptor arabirimi, kendisini XML'ye aktarmayı bilen bir türü temsil eder. API'leri aşağıdaki gibidir.

• ExportToXml() : XmlSerializedDescriptorInfo

ASP.NET Core 1.x

XML seri hale getirme

IAuthenticatedEncryptor ile IAuthenticatedEncryptorDescriptor arasındaki birincil fark, tanımlayıcının şifreleyiciyi oluşturmayı ve geçerli bağımsız değişkenlerle sağlamayı bilmesidir. Uygulaması SymmetricAlgorithm ve KeyedHashAlgorithm'e bağlı olan bir IAuthenticatedEncryptor düşünün. Şifreleyenin işi bu türleri kullanmaktır, ancak bu türlerin nereden geldiğini bilmesi gerekmez, bu nedenle uygulama yeniden başlatılırsa kendisini nasıl yeniden oluşturabileceğinize ilişkin düzgün bir açıklama yazamaz. Tanımlayıcı, bunun üzerinde daha yüksek bir düzey görevi görür. Tanımlayıcı, şifreleyici örneğinin nasıl oluşturulacağını bildiği için (örneğin gerekli algoritmaların nasıl oluşturulacağını biliyor), bu bilgiyi XML biçiminde seri hale getirerek şifreleme örneğinin uygulama sıfırlamadan sonra yeniden oluşturulabilmesini sağlayabilir.

Tanımlayıcı, ExportToXml yordamı aracılığıyla seri hale getirilebilir. Bu yordam, iki özellik içeren bir XmlSerializedDescriptorInfo döndürür: tanımlayıcının XElement gösterimi ve IAuthenticatedEncryptorDescriptorDeserializer'ı temsil eden Type, karşılık gelen XElement'i göz önünde bulundurarak bu tanımlayıcıyı yeniden canlandırmak için kullanılabilir.

Seri hale getirilmiş tanımlayıcı, şifreleme anahtarı malzemesi gibi hassas bilgiler içerebilir. Veri koruma sistemi, depolamada kalıcı hale gelmeden önce bilgileri şifrelemeye yönelik yerleşik desteğe sahiptir. Bundan yararlanmak için tanımlayıcı, "requiresEncryption" (xmlns "<http://schemas.asp.net/2015/03/dataProtection>"), "true" değeriyle hassas bilgiler içeren öğeyi işaretlemelidir.

İpucu

Bu özniteliği ayarlamak için bir yardımcı API vardır. Microsoft.AspNetCore.DataProtection.AuthenticatedEncryption.ConfigurationModel ad alanında bulunan XElement.MarkAsRequiresEncryption() uzantı yöntemini çağırın.

Seri hale getirilmiş tanımlayıcının hassas bilgiler içermediği durumlar da olabilir. Bir HSM'de depolanan şifreleme anahtarı örneğini yeniden düşünün. Tanımlayıcı, HSM malzemeyi düz metin biçiminde kullanıma sunmayacağından, kendisini serileştirirken anahtar malzemeyi yazamaz. Bunun yerine, tanımlayıcı anahtarın anahtar sarmalanmış sürümünü (HSM bu şekilde dışarı aktarmaya izin veriyorsa) veya HSM'nin anahtar için kendi benzersiz tanımlayıcısını yazabilir.

IAuthenticatedEncryptorDescriptorDeserializer

IAuthenticatedEncryptorDescriptorDeserializer arabirimi, bir XElement'ten IAuthenticatedEncryptorDescriptor örneğinin seri durumdan nasıl çıkarıldığını bilen bir türü temsil eder. Tek bir yöntemi kullanıma sunar:

• ImportFromXml(XElement öğesi) : IAuthenticatedEncryptorDescriptor

ImportFromXml yöntemi, IAuthenticatedEncryptorDescriptor.ExportToXml tarafından döndürülen XElement'i alır ve özgün IAuthenticatedEncryptorDescriptor'ın eşdeğerini oluşturur.

IAuthenticatedEncryptorDescriptorDeserializer uygulayan türler aşağıdaki iki ortak oluşturucudan birine sahip olmalıdır:

• .ctor(IServiceProvider)

• .ctor()

Not

Oluşturucuya geçirilen IServiceProvider null olabilir.

En üst düzey fabrika

ASP.NET Core 2.x

AlgorithmConfiguration sınıfı, IAuthenticatedEncryptorDescriptor örneklerinin nasıl oluşturulacağını bilen bir türü temsil eder. Tek bir API'nin kullanıma sunar.

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

AlgorithmConfiguration'ın en üst düzey fabrika olduğunu düşünün. Yapılandırma bir şablon görevi görür. Algoritmik bilgileri sarmalar (örneğin, bu yapılandırma AES-128-GCM ana anahtarıyla tanımlayıcılar oluşturur), ancak henüz belirli bir anahtarla ilişkilendirilmemiştir.

CreateNewDescriptor çağrıldığında, yalnızca bu çağrı için yeni anahtar malzemesi oluşturulur ve bu anahtar malzemeyi ve malzemeyi kullanmak için gereken algoritma bilgilerini sarmalayan yeni bir IAuthenticatedEncryptorDescriptor oluşturulur. Anahtar malzeme yazılımda oluşturulabilir (ve bellekte tutulabilir), bir HSM içinde oluşturulabilir ve tutulabilir vb. Kritik nokta, CreateNewDescriptor'a yapılan iki çağrının hiçbir zaman eşdeğer IAuthenticatedEncryptorDescriptor örnekleri oluşturmamasıdır.

AlgorithmConfiguration türü, otomatik anahtar sıralı gibi anahtar oluşturma yordamları için giriş noktası görevi görür. Gelecekteki tüm anahtarların uygulamasını değiştirmek için KeyManagementOptions içinde AuthenticatedEncryptorConfiguration özelliğini ayarlayın.

ASP.NET Core 1.x

IAuthenticatedEncryptorConfiguration arabirimi, IAuthenticatedEncryptorDescriptor örneklerinin nasıl oluşturulacağını bilen bir türü temsil eder. Tek bir API'nin kullanıma sunar.

• CreateNewDescriptor() : IAuthenticatedEncryptorDescriptor

IAuthenticatedEncryptorConfiguration'ı en üst düzey fabrika olarak düşünün. Yapılandırma bir şablon görevi görür. Algoritmik bilgileri sarmalar (örneğin, bu yapılandırma AES-128-GCM ana anahtarıyla tanımlayıcılar oluşturur), ancak henüz belirli bir anahtarla ilişkilendirilmemiştir.

CreateNewDescriptor çağrıldığında, yalnızca bu çağrı için yeni anahtar malzemesi oluşturulur ve bu anahtar malzemeyi ve malzemeyi kullanmak için gereken algoritma bilgilerini sarmalayan yeni bir IAuthenticatedEncryptorDescriptor oluşturulur. Anahtar malzeme yazılımda oluşturulabilir (ve bellekte tutulabilir), bir HSM içinde oluşturulabilir ve tutulabilir vb. Kritik nokta, CreateNewDescriptor'a yapılan iki çağrının hiçbir zaman eşdeğer IAuthenticatedEncryptorDescriptor örnekleri oluşturmamasıdır.

IAuthenticatedEncryptorConfiguration türü, otomatik anahtar döndürme gibi anahtar oluşturma yordamları için giriş noktası görevi görür. Gelecekteki tüm anahtarların uygulamasını değiştirmek için hizmet kapsayıcısına tekil bir IAuthenticatedEncryptorConfiguration kaydedin.