接【】,在有一些场景下,我们需要对 ASP.NET Core 的加密方法进行扩展,来适应我们的需求,这个时候就需要使用到了一些 Core 提供的高级的功能。
本文还列举了在集群场景下,有时候我们需要实现自己的一些方法来对 Data Protection 进行分布式配置。
是 Data Protection 在构建其密码加密系统中的一个基础的接口。 一般情况下一个 key 对应一个
- IAuthenticatedEncryptor
,
- IAuthenticatedEncryptor
封装了加密操作中需要使用到的秘钥材料和必要的加密算法信息等。
- IAuthenticatedEncryptor
下面是
接口提供的两个 api 方法:
- IAuthenticatedEncryptor
- 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
实例的方法 CreateEncryptorInstance。
- IAuthenticatedEncryptor
接口提供了一系列用来操作 Key 的方法,包括存储,检索操作等。他提供的高级操作有:
- IKeyManager
XmlKeyManager
通常情况下,开发人员不需要去实现
来自定义一个 KeyManager。我们可以使用系统默认提供的
- IKeyManager
类。
- 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);
- }
IXmlRepository
接口主要提供了持久化以及检索 XML 的方法,它只要提供了两个 API:
- IXmlRepository
我们可以通过实现
接口的 StoreElement 方法来定义 data protection xml 的存储位置。
- IXmlRepository
GetAllElements 来检索所有存在的加密的 xml 文件。
接口部分写到这里吧,因为这一篇我想把重点放到下面,更多接口的介绍大家还是去官方文档看吧~
上面的 API 估计看着有点枯燥,那我们就来看看我们需要在集群场景下借助于 Data Protection 来做点什么吧。
就像我在【】总结中末尾提到的,在做分布式集群的时候,Data Protection 的一些机制我们需要知道,因为如果不了解这些可能会给你的部署带来一些麻烦,下面我们就来看看吧。
在做集群的时,我们必须知道并且明白关于 ASP.NET Core Data Protection 的三个东西:
"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
还有一个扩展方法叫 SetApplicationName , 这个扩展方法在内部还是修改的 ApplicationDiscriminator 的值。也就说以下写法是等价的:
- IDataProtectionBuilder
- services.AddDataProtection(x = >x.ApplicationDiscriminator = "my_app_sample_identity");
- services.AddDataProtection().SetApplicationName("my_app_sample_identity");
也就是说集群环境下同一应用程序他们需要设定为相同的值(ApplicationName or ApplicationDiscriminator)。
"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();
- }
如果在集群环境中,他们需要具有配置相同的主加密键。
在【】的时候说过,默认情况下 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 存储,该怎么做呢?
首先,定义个针对
接口的 redis 实现类
- IXmlRepository
:
- 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 来说我也是一个循循渐进的学习过程,希望能帮助到一些人。
如果您觉得本篇文章对你有用的话,不妨点个【推荐】。
来源: http://www.cnblogs.com/savorboard/p/dotnetcore-data-protected-farm.html