前言
接【中篇】 ,在有一些場景下,我們需要對 ASP.NET Core 的加密方法進行擴展,來適應我們的需求,這個時候就需要使用到了一些 Core 提供的高級的功能。
本文還列舉了在集群場景下,有時候我們需要實現自己的一些方法來對Data Protection進行分布式配置。
加密擴展
IAuthenticatedEncryptor 和 IAuthenticatedEncryptorDescriptor
IAuthenticatedEncryptor是 Data Protection 在構建其密碼加密系統中的一個基礎的接口。
一般情況下一個key 對應一個IAuthenticatedEncryptor,IAuthenticatedEncryptor封裝了加密操作中需要使用到的秘鑰材料和必要的加密算法信息等。
下面是IAuthenticatedEncryptor接口提供的兩個 api方法:
Decrypt(ArraySegment<byte> ciphertext, ArraySegment<byte> additionalAuthenticatedData) : byte[]
Encrypt(ArraySegment<byte> plaintext, ArraySegment<byte> additionalAuthenticatedData) : byte[]
其中接口中的參數additionalAuthenticatedData表示在構建加密的時候提供的一些附屬信息。
IAuthenticatedEncryptorDescriptor接口提供了一個創建包含類型信息IAuthenticatedEncryptor實例方法。
CreateEncryptorInstance() : IAuthenticatedEncryptor
ExportToXml() : XmlSerializedDescriptorInfo
密鑰管理擴展
在密鑰系統管理中,提供了一個基礎的接口IKey,它包含以下屬性:
Activation
creation
expiration dates
Revocation status
Key identifier (a GUID)
IKey還提供了一個創建IAuthenticatedEncryptor實例的方法CreateEncryptorInstance。
IKeyManager接口提供了一系列用來操作Key的方法,包括存儲,檢索操作等。他提供的高級操作有:
•創建一個Key 並且持久存儲
•從存儲庫中獲取所有的 Key
•撤銷保存到存儲中的一個或多個鍵
XmlKeyManager
通常情況下,開發人員不需要去實現IKeyManager來自定義一個 KeyManager。我們可以使用系統默認提供的XmlKeyManager類。
XMLKeyManager是一個具體實現IKeyManager的類,它提供了一些非常有用的方法。
public sealed class XmlKeyManager : IKeyManager, IInternalXmlKeyManager { public XmlKeyManager(IXmlRepository repository, IAuthenticatedEncryptorConfiguration configuration, IServiceProvider services); public IKey CreateNewKey(DateTimeOffset activationDate, DateTimeOffset expirationDate); public IReadOnlyCollection<IKey> GetAllKeys(); public CancellationToken GetCacheExpirationToken(); public void RevokeAllKeys(DateTimeOffset revocationDate, string reason = null); public void RevokeKey(Guid keyId, string reason = null); }
•IAuthenticatedEncryptorConfiguration 主要是規定新 Key 使用的算法。
•IXmlRepository 主要控制 Key 在哪裡持久化存儲。
IXmlRepository
IXmlRepository接口主要提供了持久化以及檢索XML的方法,它只要提供了兩個API:
•GetAllElements() : IReadOnlyCollection
•StoreElement(XElement element, string friendlyName)
我們可以通過實現IXmlRepository接口的StoreElement方法來定義data protection xml的存儲位置。
GetAllElements來檢索所有存在的加密的xml文件。
接口部分寫到這裡吧,因為這一篇我想把重點放到下面,更多接口的介紹大家還是去官方文檔看吧~
集群場景
上面的API估計看著有點枯燥,那我們就來看看我們需要在集群場景下借助於Data Protection來做點什麼吧。
就像我在【上篇】總結中末尾提到的,在做分布式集群的時候,Data Protection的一些機制我們需要知道,因為如果不了解這些可能會給你的部署帶來一些麻煩,下面我們就來看看吧。
在做集群的時,我們必須知道並且明白關於 ASP.NET Core Data Protection 的三個東西:
1、程序識別者
“Application discriminator”,它是用來標識應用程序的唯一性。
為什麼需要這個東西呢?因為在集群環境中,如果不被具體的硬件機器環境所限制,就要排除運行機器的一些差異,就需要抽象出來一些特定的標識,來標識應用程序本身並且使用該標識來區分不同的應用程序。這個時候,我們可以指定ApplicationDiscriminator。
在services.AddDataProtection(DataProtectionOptions option)的時候,ApplicationDiscriminator可以作為參數傳遞,來看一下代碼:
public void ConfigureServices(IServiceCollection services) { services.AddDataProtection(); services.AddDataProtection(DataProtectionOptions option); } //===========擴展方法如下: public static class DataProtectionServiceCollectionExtensions { public static IDataProtectionBuilder AddDataProtection(this IServiceCollection services); //具有可傳遞參數的重載,在集群環境中需要使用此項配置 public static IDataProtectionBuilder AddDataProtection(this IServiceCollection services, Action<DataProtectionOptions> setupAction); } // DataProtectionOptions 屬性: public class DataProtectionOptions { public string ApplicationDiscriminator { get; set; } }
可以看到這個擴展返回的是一個IDataProtectionBuilder,在IDataProtectionBuilder還有一個擴展方法叫 SetApplicationName ,這個擴展方法在內部還是修改的ApplicationDiscriminator的值。也就說以下寫法是等價的:
services.AddDataProtection(x => x.ApplicationDiscriminator = "my_app_sample_identity");
services.AddDataProtection().SetApplicationName("my_app_sample_identity");
也就是說集群環境下同一應用程序他們需要設定為相同的值(ApplicationName or ApplicationDiscriminator)。
2、主加密鍵
“Master encryption key”,主要是用來加密解密的,包括一客戶端服務器在請求的過程中的一些會話數據,狀態等。有幾個可選項可以配置,比如使用證書或者是windows DPAPI或者注冊表等。如果是非windows平台,注冊表和Windows DPAPI就不能用了。
public void ConfigureServices(IServiceCollection services) { services.AddDataProtection() //windows dpaip 作為主加密鍵 .ProtectKeysWithDpapi() //如果是 windows 8+ 或者windows server2012+ 可以使用此選項(基於Windows DPAPI-NG) .ProtectKeysWithDpapiNG("SID={current account SID}", DpapiNGProtectionDescriptorFlags.None) //如果是 windows 8+ 或者windows server2012+ 可以使用此選項(基於證書) .ProtectKeysWithDpapiNG("CERTIFICATE=HashId:3BCE558E2AD3E0E34A7743EAB5AEA2A9BD2575A0", DpapiNGProtectionDescriptorFlags.None) //使用證書作為主加密鍵,目前只有widnows支持,linux還不支持。 .ProtectKeysWithCertificate(); }
如果在集群環境中,他們需要具有配置相同的主加密鍵。
3、加密後存儲位置
在【上篇】的時候說過,默認情況下Data Protection會生成 xml 文件用來存儲session或者是狀態的密鑰文件。這些文件用來加密或者解密session等狀態數據。
就是上篇中說的那個私鑰存儲位置:
1、如果程序寄宿在 Microsoft Azure下,存儲在“%HOME%\ASP.NET\DataProtection-Keys” 文件夾。
2、如果程序寄宿在IIS下,它被保存在HKLM注冊表的ACLed特殊注冊表鍵,並且只有工作進程可以訪問,它使用windows的DPAPI加密。
3、如果當前用戶可用,即win10或者win7中,它存儲在“%LOCALAPPDATA%\ASP.NET\DataProtection-Keys”文件夾,同樣使用的windows的DPAPI加密。
4、如果這些都不符合,那麼也就是私鑰是沒有被持久化的,也就是說當進程關閉的時候,生成的私鑰就丟失了。
集群環境下:
最簡單的方式是通過文件共享、DPAPI或者注冊表,也就是說把加密過後的xml文件都存儲在相同的地方。為什麼說最簡單,因為系統已經給封裝好了,不需要寫多余的代碼了,但是要保證文件共享相關的端口是開放的。如下:
public void ConfigureServices(IServiceCollection services) { services.AddDataProtection() //windows、Linux、macOS 下可以使用此種方式 保存到文件系統 .PersistKeysToFileSystem(new System.IO.DirectoryInfo("C:\\share_keys\\")) //windows 下可以使用此種方式 保存到注冊表 .PersistKeysToRegistry(Microsoft.Win32.RegistryKey.FromHandle(null)) }
你也可以自己擴展方法來自己定義一些存儲,比如使用數據庫或者Redis等。
不過通常情況下,如果在linux上部署的話,都是需要擴展的。下面來看一下我們想要用redis存儲,該怎麼做呢?
如何擴展加密鍵集合的存儲位置?
首先,定義個針對IXmlRepository接口的 redis 實現類RedisXmlRepository.cs:
public class RedisXmlRepository : IXmlRepository, IDisposable { public static readonly string RedisHashKey = "DataProtectionXmlRepository"; private IConnectionMultiplexer _connection; private bool _disposed = false; public RedisXmlRepository(string connectionString, ILogger<RedisXmlRepository> logger) : this(ConnectionMultiplexer.Connect(connectionString), logger) { } public RedisXmlRepository(IConnectionMultiplexer connection, ILogger<RedisXmlRepository> logger) { if (connection == null) { throw new ArgumentNullException(nameof(connection)); } if (logger == null) { throw new ArgumentNullException(nameof(logger)); } this._connection = connection; this.Logger = logger; var configuration = Regex.Replace(this._connection.Configuration, @"password\s*=\s*[^,]*", "password=****", RegexOptions.IgnoreCase); this.Logger.LogDebug("Storing data protection keys in Redis: {RedisConfiguration}", configuration); } public ILogger<RedisXmlRepository> Logger { get; private set; } public void Dispose() { this.Dispose(true); } public IReadOnlyCollection<XElement> GetAllElements() { var database = this._connection.GetDatabase(); var hash = database.HashGetAll(RedisHashKey); var elements = new List<XElement>(); if (hash == null || hash.Length == 0) { return elements.AsReadOnly(); } foreach (var item in hash.ToStringDictionary()) { elements.Add(XElement.Parse(item.Value)); } this.Logger.LogDebug("Read {XmlElementCount} XML elements from Redis.", elements.Count); return elements.AsReadOnly(); } public void StoreElement(XElement element, string friendlyName) { if (element == null) { throw new ArgumentNullException(nameof(element)); } if (string.IsNullOrEmpty(friendlyName)) { friendlyName = Guid.NewGuid().ToString(); } this.Logger.LogDebug("Storing XML element with friendly name {XmlElementFriendlyName}.", friendlyName); this._connection.GetDatabase().HashSet(RedisHashKey, friendlyName, element.ToString()); } protected virtual void Dispose(bool disposing) { if (!this._disposed) { if (disposing) { if (this._connection != null) { this._connection.Close(); this._connection.Dispose(); } } this._connection = null; this._disposed = true; } } }
然後任意一個擴展類中先定義一個擴展方法:
public static IDataProtectionBuilder PersistKeysToRedis(this IDataProtectionBuilder builder, string redisConnectionString) { if (builder == null) { throw new ArgumentNullException(nameof(builder)); } if (redisConnectionString == null) { throw new ArgumentNullException(nameof(redisConnectionString)); } if (redisConnectionString.Length == 0) { throw new ArgumentException("Redis connection string may not be empty.", nameof(redisConnectionString)); } //因為在services.AddDataProtection()的時候,已經注入了IXmlRepository,所以應該先移除掉 //此處應該封裝成為一個方法來調用,為了讀者好理解,我就直接寫了 for (int i = builder.Services.Count - 1; i >= 0; i--) { if (builder.Services[i]?.ServiceType == descriptor.ServiceType) { builder.Services.RemoveAt(i); } } var descriptor = ServiceDescriptor.Singleton<IXmlRepository>(services => new RedisXmlRepository(redisConnectionString, services.GetRequiredService<ILogger<RedisXmlRepository>>())) builder.Services.Add(descriptor); return builder.Use(); }
最終Services中關於DataProtection是這樣的:
public void ConfigureServices(IServiceCollection services) { services.AddDataProtection() // ================以下是唯一標識============== //設置應用程序唯一標識 .SetApplicationName("my_app_sample_identity"); // =============以下是主加密鍵=============== //windows dpaip 作為主加密鍵 .ProtectKeysWithDpapi() //如果是 windows 8+ 或者windows server2012+ 可以使用此選項(基於Windows DPAPI-NG) .ProtectKeysWithDpapiNG("SID={current account SID}", DpapiNGProtectionDescriptorFlags.None) //如果是 windows 8+ 或者windows server2012+ 可以使用此選項(基於證書) .ProtectKeysWithDpapiNG("CERTIFICATE=HashId:3BCE558E2AD3E0E34A7743EAB5AEA2A9BD2575A0", DpapiNGProtectionDescriptorFlags.None) //使用證書作為主加密鍵,目前只有widnows支持,linux還不支持。 .ProtectKeysWithCertificate(); // ==============以下是存儲位置================= //windows、Linux、macOS 下可以使用此種方式 保存到文件系統 .PersistKeysToFileSystem(new System.IO.DirectoryInfo("C:\\share_keys\\")) //windows 下可以使用此種方式 保存到注冊表 .PersistKeysToRegistry(Microsoft.Win32.RegistryKey.FromHandle(null)) // 存儲到redis .PersistKeysToRedis(Configuration.Section["RedisConnection"]) }
在上面的配置中,我把所有可以使用的配置都列出來了哦,實際項目中應該視實際情況選擇。
總結
關於ASP.NET Core Data Protection 系列終於寫完了,其實這這部分花了蠻多時間的,對於Data Protection來說我也是一個循循漸進的學習過程,希望能幫助到一些人。
以上就是本文的全部內容,希望對大家的學習有所幫助,也希望大家多多支持幫客之家。