ASP.NET Core'da anahtar yönetimi genişletilebilirliği

Bu bölümü okumadan önce, bu API'lerin arkasındaki temel kavramlardan bazılarını açıkladığı için anahtar yönetimi bölümünü okuyun.

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.

Tuş

IKey Arabirim, şifreleme sistemindeki bir anahtarın temel gösterimidir. Anahtar terimi burada "şifreleme anahtarı malzemesi" değişmez anlamıyla değil soyut anlamda kullanılır. Anahtar aşağıdaki özelliklere sahiptir:

• Etkinleştirme, oluşturma ve son kullanma tarihleri

• İptal durumu

• Anahtar tanımlayıcısı (GUID)

Ayrıca, IKey bu anahtara bağlı bir CreateEncryptor IAuthenticatedEncryptor örneği oluşturmak için kullanılabilecek bir yöntemi kullanıma sunar.

Dekont

Bir örnekten ham şifreleme malzemesini IKey almak için API yoktur.

IKeyManager

Arabirim, IKeyManager genel anahtar depolama, alma ve işlemeden sorumlu bir nesneyi temsil eder. Üç üst düzey işlemi kullanıma sunar:

• Yeni bir anahtar oluşturun ve bunu depolamada kalıcı hale getirmek.

• Depolamadan tüm anahtarları alın.

• Bir veya daha fazla anahtarı iptal edin ve iptal bilgilerini depolamada kalıcı hale getirmek.

Uyarı

Yazmak IKeyManager çok gelişmiş bir görevdir ve geliştiricilerin çoğunluğu bunu denememelidir. Bunun yerine, geliştiricilerin çoğu XmlKeyManager sınıfı tarafından sunulan olanaklardan yararlanmalıdır.

XmlKeyManager

Türü XmlKeyManager , 'nin kutu içi somut uygulamasıdır IKeyManager. Anahtar emaneti ve bekleyen anahtarların şifrelenmesi de dahil olmak üzere çeşitli yararlı olanaklar sağlar. Bu sistemdeki anahtarlar XML öğeleri (özellikle XElement) olarak temsil edilir.

XmlKeyManager görevlerini yerine getirme süresi boyunca diğer birkaç bileşene bağlıdır:

• AlgorithmConfiguration, yeni anahtarlar tarafından kullanılan algoritmaları dikte eder.

• IXmlRepository, anahtarların depolamada nerede kalıcı olduğunu denetler.

• IXmlEncryptor [isteğe bağlı], bekleyen anahtarların şifrelenmesine izin verir.

• IKeyEscrowSink [isteğe bağlı], anahtar emanet hizmetleri sağlar.

Aşağıda, bu bileşenlerin içinde XmlKeyManagernasıl kablolu olduğunu gösteren üst düzey diyagramlar yer almaktadır.

Anahtar Oluşturma / CreateNewKey

uygulamasındaCreateNewKeyAlgorithmConfiguration, bileşen benzersiz IAuthenticatedEncryptorDescriptorbir oluşturmak için kullanılır ve ardından XML olarak serileştirilir. Anahtar emanet havuzu varsa, havuza uzun süreli depolama için ham (şifrelenmemiş) XML sağlanır. Şifrelenmemiş XML daha sonra şifrelenmiş XML belgesini oluşturmak için bir IXmlEncryptor (gerekirse) üzerinden çalıştırılır. Bu şifrelenmiş belge, aracılığıyla uzun vadeli depolama alanında kalıcı hale getiriliyor IXmlRepository. (Hayır IXmlEncryptor yapılandırıldıysa, şifrelenmemiş belge içinde IXmlRepositorykalıcı olur.)

Anahtar Alma / GetAllKeys

uygulamasında GetAllKeysanahtarları ve iptalleri temsil eden XML belgeleri temel IXmlRepositoryalınan dosyasından okunur. Bu belgeler şifrelenirse sistem bunların şifresini otomatik olarak çözer. XmlKeyManager, belgeleri seri durumdan çıkarmak için uygun IAuthenticatedEncryptorDescriptorDeserializer örnekleri oluşturur ve ardından tek tek IKey örneklere IAuthenticatedEncryptorDescriptor sarmalanmıştır. Bu örnek koleksiyonu IKey çağırana döndürülür.

Belirli XML öğeleri hakkında daha fazla bilgi, anahtar depolama biçimi belgesinde bulunabilir.

IXmlRepository

Arabirim, IXmlRepository XML'i kalıcı hale getirebilen ve bir yedekleme deposundan XML alabilen bir türü temsil eder. İki API'leri kullanıma sunar:

• GetAllElements :IReadOnlyCollection<XElement>

• StoreElement(XElement element, string friendlyName)

uygulamalarının IXmlRepository , içinden geçen XML'yi ayrıştırmalarına gerek yoktur. XML belgelerini opak olarak ele almalı ve daha yüksek katmanların belgeleri oluşturma ve ayrıştırma konusunda endişelenmesine izin vermelidir.

Uygulayan IXmlRepositorydört yerleşik beton türü vardır:

• FileSystemXmlRepository
• RegistryXmlRepository
• Azure Depolama. AzureBlobXmlRepository
• RedisXmlRepository

Daha fazla bilgi için anahtar depolama sağlayıcıları belgesine bakın.

Özel IXmlRepository kayıt, farklı bir yedekleme deposu (örneğin, Azure Tablo Depolama) kullanılırken uygundur.

Uygulama genelinde varsayılan depoyu değiştirmek için özel IXmlRepository bir örnek kaydedin:

services.Configure<KeyManagementOptions>(options => options.XmlRepository = new MyCustomXmlRepository());

IXmlEncryptor

Arabirim, IXmlEncryptor düz metin XML öğesini şifreleyebilen bir türü temsil eder. Tek bir API'nin kullanıma sunar:

• Encrypt(XElement plaintextElement) : EncryptedXmlInfo

Seri hale getirilmiş IAuthenticatedEncryptorDescriptor bir öğe "şifreleme gerektiriyor" olarak işaretlenmiş öğeler içeriyorsa, XmlKeyManager bu öğeleri yapılandırılan IXmlEncryptor's Encrypt yöntemi aracılığıyla çalıştırır ve düz metin öğesi yerine şifrelenen öğeyi IXmlRepositoryüzerinde kalıcı hale getirecektir. yönteminin Encrypt çıkışı bir EncryptedXmlInfo nesnedir. Bu nesne, hem şifrelenen XElement sonuç öğesini hem de karşılık gelen öğeyi deşifre etmek için kullanılabilecek bir öğesini temsil eden Türü içeren bir IXmlDecryptor sarmalayıcıdır.

Uygulayan IXmlEncryptordört yerleşik beton türü vardır:

• CertificateXmlEncryptor
• DpapiNGXmlEncryptor
• DpapiXmlEncryptor
• NullXmlEncryptor

Daha fazla bilgi için bekleyen anahtar şifreleme belgesine bakın.

Uygulama genelinde varsayılan anahtar şifrelemesi uygulama genelinde anahtar şifreleme mekanizmasını değiştirmek için özel IXmlEncryptor bir örnek kaydedin:

services.Configure<KeyManagementOptions>(options => options.XmlEncryptor = new MyCustomXmlEncryptor());

IXmlDecryptor

Arabirimi, IXmlDecryptor aracılığıyla şifrelenen bir XElement şifrenin şifresinin nasıl çözüldüğünü bilen bir IXmlEncryptortürü temsil eder. Tek bir API'nin kullanıma sunar:

• Decrypt(XElement encryptedElement) : XElement

yöntemi tarafından DecryptIXmlEncryptor.Encryptgerçekleştirilen şifrelemeyi geri alır. Genel olarak, her somut IXmlEncryptor uygulamanın karşılık gelen bir somut IXmlDecryptor uygulaması olacaktır.

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

• .ctor(IServiceProvider)
• .ctor()

Dekont

IServiceProvider Oluşturucuya geçirilen null olabilir.

IKeyEscrowSink

Arabirim, IKeyEscrowSink hassas bilgilerin emanetini gerçekleştirebilen bir türü temsil eder. Seri hale getirilmiş tanımlayıcıların hassas bilgiler (şifreleme malzemesi gibi) içerebileceğini ve ilk etapta IXmlEncryptor türünün eklenmesine yol açan şeyin bu olduğunu hatırlayın. Ancak, kazalar meydana gelir ve anahtar halkaları silinebilir veya bozulabilir.

Escrow arabirimi, yapılandırılmış IXmlEncryptor tarafından dönüştürülmeden önce ham serileştirilmiş XML'e erişim sağlayan bir acil durum kaçış taraması sağlar. Arabirim tek bir API'yi kullanıma sunar:

• Store(Guid keyId, XElement öğesi)

Sağlanan öğeyi IKeyEscrowSink iş ilkesiyle tutarlı bir şekilde güvenli bir şekilde işlemek uygulamaya bağlı. Sertifikanın özel anahtarının emanet edildiği bilinen bir kurumsal X.509 sertifikası kullanarak XML öğesini şifrelemek için escrow havuzu için olası bir uygulama olabilir; CertificateXmlEncryptor türü bu konuda yardımcı olabilir. Uygulama IKeyEscrowSink , sağlanan öğeyi uygun şekilde kalıcı hale getirilmesinden de sorumludur.

Varsayılan olarak hiçbir emanet mekanizması etkinleştirilmez, ancak sunucu yöneticileri bunu genel olarak yapılandırabilir. Aşağıdaki örnekte gösterildiği gibi yöntemi aracılığıyla IDataProtectionBuilder.AddKeyEscrowSink program aracılığıyla da yapılandırılabilir. Yöntemlerin AddKeyEscrowSink aşırı yüklemeleri, IKeyEscrowSink örneklerin IServiceCollection.AddSingleton tekil olması amaçlandığından ve IServiceCollection.AddInstance aşırı yüklemelerini yansıtır. Birden çok IKeyEscrowSink örnek kaydedilirse, anahtar oluşturma sırasında her biri çağrılır, böylece anahtarlar aynı anda birden çok mekanizmaya emanet edilebilir.

Bir örnekten malzeme okunacak API IKeyEscrowSink yoktur. Bu, emanet mekanizmasının tasarım teorisiyle tutarlıdır: anahtar malzemeyi güvenilir bir yetkili için erişilebilir hale getirmek için tasarlanmıştır ve uygulamanın kendisi güvenilir bir yetkili olmadığından, kendi emanet edilen malzemeye erişimi olmamalıdır.

Aşağıdaki örnek kod, anahtarların yalnızca "CONTOSODomain Yönetici s" üyelerinin kurtarabileceği şekilde bir yer anahtarlarının oluşturulmasını ve kaydedilmesini IKeyEscrowSink gösterir.

Dekont

Bu örneği çalıştırmak için etki alanına katılmış bir Windows 8 / Windows Server 2012 makinesinde olmanız ve etki alanı denetleyicisinin Windows Server 2012 veya üzeri olması gerekir.

using System;
using System.IO;
using System.Xml.Linq;
using Microsoft.AspNetCore.DataProtection;
using Microsoft.AspNetCore.DataProtection.KeyManagement;
using Microsoft.AspNetCore.DataProtection.XmlEncryption;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        var serviceCollection = new ServiceCollection();
        serviceCollection.AddDataProtection()
            .PersistKeysToFileSystem(new DirectoryInfo(@"c:\temp-keys"))
            .ProtectKeysWithDpapi()
            .AddKeyEscrowSink(sp => new MyKeyEscrowSink(sp));
        var services = serviceCollection.BuildServiceProvider();

        // get a reference to the key manager and force a new key to be generated
        Console.WriteLine("Generating new key...");
        var keyManager = services.GetService<IKeyManager>();
        keyManager.CreateNewKey(
            activationDate: DateTimeOffset.Now,
            expirationDate: DateTimeOffset.Now.AddDays(7));
    }

    // A key escrow sink where keys are escrowed such that they
    // can be read by members of the CONTOSO\Domain Admins group.
    private class MyKeyEscrowSink : IKeyEscrowSink
    {
        private readonly IXmlEncryptor _escrowEncryptor;

        public MyKeyEscrowSink(IServiceProvider services)
        {
            // Assuming I'm on a machine that's a member of the CONTOSO
            // domain, I can use the Domain Admins SID to generate an
            // encrypted payload that only they can read. Sample SID from
            // https://technet.microsoft.com/library/cc778824(v=ws.10).aspx.
            _escrowEncryptor = new DpapiNGXmlEncryptor(
                "SID=S-1-5-21-1004336348-1177238915-682003330-512",
                DpapiNGProtectionDescriptorFlags.None,
                new LoggerFactory());
        }

        public void Store(Guid keyId, XElement element)
        {
            // Encrypt the key element to the escrow encryptor.
            var encryptedXmlInfo = _escrowEncryptor.Encrypt(element);

            // A real implementation would save the escrowed key to a
            // write-only file share or some other stable storage, but
            // in this sample we'll just write it out to the console.
            Console.WriteLine($"Escrowing key {keyId}");
            Console.WriteLine(encryptedXmlInfo.EncryptedElement);

            // Note: We cannot read the escrowed key material ourselves.
            // We need to get a member of CONTOSO\Domain Admins to read
            // it for us in the event we need to recover it.
        }
    }
}

/*
 * SAMPLE OUTPUT
 *
 * Generating new key...
 * Escrowing key 38e74534-c1b8-4b43-aea1-79e856a822e5
 * <encryptedKey>
 *   <!-- This key is encrypted with Windows DPAPI-NG. -->
 *   <!-- Rule: SID=S-1-5-21-1004336348-1177238915-682003330-512 -->
 *   <value>MIIIfAYJKoZIhvcNAQcDoIIIbTCCCGkCAQ...T5rA4g==</value>
 * </encryptedKey>
 */