ASP.NET Core Data Protection 默认配置实战:从 AddDataProtection() 到 Protect/Unprotect 完整链路

原创2026-10-15 12:42:431,921 阅读
文章标签:示例工程

ASP.NET Core Data Protection 默认配置实战:从 AddDataProtection() 到 Protect/Unprotect 完整链路

本文围绕 practical-aspnetcore 仓库中的 Data Protection with Default Settings 示例,讲解 ASP.NET Core 数据保护(Data Protection)栈在“零配置”下的默认行为、核心 API 调用链与端到端运行方式。读完本文,你将掌握 AddDataProtection() 的注册语义、IDataProtector 的 Protect/Unprotect 使用模式,以及默认密钥环(key ring)的存储与加密策略,并能在此基础上对比仓库中 Azure Blob、Redis、EF Core 等进阶密钥存储方案。

Data Protection 默认设置示例运行页面:输入待加密字符串后,页面同时展示加密结果与解密还原结果

示例项目定位:默认设置下的最小可运行形态

该示例位于 projects/security/dataprotection/default-settings,是仓库 dataprotection 主题目录 中介绍的第一个基础样例。主题目录 README 将其定位为:

Basic sample to show data protection with default settings.

整个 dataprotection 目录围绕同一套“密钥管理(key management)+ 持久化(persistence)+ 加密(encryption)”体系展开,形成由浅入深的系列:

理解默认设置,是理解上述所有变体的前提——变体只是在“存储到哪里”“如何加密”两个维度上替换默认实现。

核心一行:services.AddDataProtection()

原文档给出的注册方式如下(源自其 README):

public void ConfigureServices(IServiceCollection services)
{
    services.AddDataProtection();
    ...
}

当前仓库中的 Program.cs 已将其升级为 .NET 10 的 Minimal Hosting 写法,逻辑完全等价:

var builder = WebApplication.CreateBuilder();
builder.Services.AddDataProtection();
builder.Services.AddRazorPages();

var app = builder.Build();
app.UseStaticFiles();
app.MapRazorPages();

app.Run();

其中:

  • builder.Services.AddDataProtection():向 DI 容器注册数据保护服务,返回 IDataProtectionBuilder 供后续链式配置(本示例没有后续配置,全部采用默认值);
  • builder.Services.AddRazorPages():注册 Razor Pages,承载演示页面;
  • app.UseStaticFiles() 与 app.MapRazorPages():启用静态文件并映射页面路由。

项目文件 DataProtectionDefaultSettings.csproj 声明了 TargetFramework 为 net10.0 并启用 ImplicitUsings,因此无需显式 using Microsoft.Extensions.DependencyInjection 即可调用扩展方法。值得注意的是,示例没有引用任何额外的 NuGet 包——Microsoft.AspNetCore.DataProtection 是 ASP.NET Core 共享框架(Microsoft.NET.Sdk.Web)自带的组件,这也正是“默认设置”零依赖、零配置的直接体现。

“默认”到底默认了什么:框架级默认行为盘点

原文档标题中的 “Default Settings” 指向 ASP.NET Core 官方文档中的 “Data Protection default settings” 一节(README 的 Reference 中给出的文档)。这些默认行为属于框架通用约定,本示例刻意不调用任何 PersistKeysTo*、ProtectKeysWith* 方法,因此全部生效:

维度 默认行为 说明
密钥环存储位置 Windows:%LOCALAPPDATA%\ASP.NET\DataProtection-Keys;非 Windows(Linux/macOS):$HOME/.aspnet/DataProtection-Keys 文件系统上的 XML 文件,文件名形如 key-{GUID}.xml
密钥加密(at-rest) Windows 下优先使用 DPAPI(ProtectKeysWithDpapi());非 Windows 平台默认不加密 即 Linux 容器中密钥环文件为明文 XML,生产环境应显式配置加密
密钥生命周期 默认 90 天 到期前会自动滚动生成新密钥
密钥自动生成 应用启动时会检查并自动创建默认密钥 保证系统无人工干预可运行
应用隔离 默认使用应用内容根路径(content root)作为应用标识符 不同应用使用不同的密钥子环,避免互相解密
算法 认证加密(authenticated encryption),默认 AES-256-CBC + HMAC-SHA256 Protect 输出同时保证机密性与完整性

需要特别提醒:本示例在非 Windows 环境下运行时,密钥环是未加密的 XML 文件。这适合演示与开发,但不适合作为生产密钥保护策略——仓库中 custom-encryptor 示例 正是为了演示如何用自定义 IXmlEncryptor 接管这一环节而存在。

消费数据保护:IDataProtectionProvider 与 IDataProtector

注册之后,页面模型通过构造函数注入 IDataProtectionProvider 来获取保护器。Index.cshtml.cs 完整展示了这一模式:

public class IndexModel : PageModel
{
    private readonly IDataProtector _protector;
    private readonly ILogger<IndexModel> _logger;

    public string EncryptedString { get; private set; }
    public string DeCryptedString { get; private set; }

    public IndexModel(ILogger<IndexModel> logger, IDataProtectionProvider dataProtectionProvider)
    {
        _protector = dataProtectionProvider.CreateProtector("DP.DefaultSettings.V1");
        _logger = logger;
    }

    public void OnGet() { }

    [Required(ErrorMessage = "Enter string to encrypt.")]
    [BindProperty]
    public string StringToEncrypt { get; set; }

    public void OnPost()
    {
        EncryptedString = _protector.Protect(StringToEncrypt);
        DeCryptedString = _protector.Unprotect(EncryptedString);
    }
}

这里有三个值得深入理解的技术点:

  1. CreateProtector("DP.DefaultSettings.V1") 中的目的字符串(purpose string)。这是数据保护 API 的核心设计:保护器不是全局单一的,而是通过“目的字符串”派生出的具名实例。不同目的字符串产生的密文互不通用,即使攻击者拿到某一路径的密文,也无法在其他目的上下文中解出原文。示例中 "DP.DefaultSettings.V1" 是一个语义化命名(项目名缩写 + 场景 + 版本号),实际项目建议按“用途 + 版本”命名,例如 "auth-token.v2",以便未来演进时做密钥隔离。

  2. Protect() 与 Unprotect() 是一对对称操作。Protect(plaintext) 返回带认证的密文(默认 Base64url 编码文本);Unprotect(ciphertext) 还原原文。若密文被篡改、目的字符串不匹配或密钥环中缺少对应密钥,Unprotect 会抛出 CryptographicException,从机制上保证数据未被伪造。

  3. 注入的是 IDataProtectionProvider 而非 IDataProtector。Provider 是“母工厂”,负责按目的字符串派生 Protector;Protector 才承载具体的 Protect/Unprotect 能力。这种分层允许同一个 Provider 在应用内派生任意多个互不干扰的保护器。

页面模型把加密结果同时赋给 EncryptedString(展示密文)与 DeCryptedString(展示 Unprotect 还原结果),从而在单个页面内完成“加密 → 解密”闭环验证。

端到端验证:表单提交闭环

Index.cshtml 提供提交表单与结果展示:

<form method="post">
    <div class="mb-3">
        <label asp-for="@Model.StringToEncrypt" class="form-label">String to encrypt</label>
        <input class="form-control" asp-for="@Model.StringToEncrypt">
        <span asp-validation-for="@Model.StringToEncrypt" class="text-danger"></span>
    </div>
    <button type="submit" class="btn btn-primary">Submit</button>
</form>

@if (!string.IsNullOrEmpty(Model.EncryptedString))
{
    <div class="py-4">
        Encrypted String: <br />
        <b class="w-75 text-wrap">@Model.EncryptedString</b>
    </div>
    <div class="py-4">
        DeCrypted String: <br />
        <b>@Model.DeCryptedString</b>
    </div>
}

交互闭环如下:

  1. 用户在 “String to encrypt” 输入框中输入明文;
  2. 点击 Submit 触发 OnPost();
  3. _protector.Protect(StringToEncrypt) 生成密文,展示在 “Encrypted String” 区域;
  4. _protector.Unprotect(EncryptedString) 还原明文,展示在 “DeCrypted String” 区域,二者应完全一致。

<a href="https://link.gitcode.com/i/79861b9dbef3cd5558b1406b7a5ef7df" target="_blank">Required] 验证保证空字符串不会进入加密流程;[appsettings.json 保持模板默认的日志级别与 AllowedHosts 配置,无需改动即可运行。

运行示例

在 default-settings 目录 下执行:

dotnet run

随后浏览器访问应用默认地址(如 http://localhost:5000),即可看到页面顶部截图中的演示界面:标题 “Default Settings Example”、加密输入框与 Submit 按钮,以及提交后的 “Encrypted String” / “DeCrypted String” 输出区。首次启动时,框架会自动在密钥目录生成密钥环 XML 文件,这正是默认设置“开箱即用”的直观体现。

从默认设置出发:何时需要替换默认行为

默认设置的适用前提是单实例部署:密钥环存放在本机文件系统,只有本机能解密。一旦面临以下场景,就需要参照仓库中其他示例替换默认行为:

场景 推荐的替换方式 仓库对应示例
多实例负载均衡,需共享密钥环 把密钥环持久化到共享存储 Azure Blob、Redis、EF Core
非 Windows 环境需要加密静态密钥 使用自定义 IXmlEncryptor custom-encryptor
托管密钥与集中管控 使用云托管密钥服务 Azure Key Vault + Blob

以 Redis 示例 为例,其注册方式仅是在默认基础上追加持久化配置:

builder.Services.AddDataProtection().PersistKeysToStackExchangeRedis(redis, redisKey);

EF Core 示例 则通过 PersistKeysToDbContext<DataProtectionKeyContext>() 将密钥表落入关系数据库。可以看到,所有进阶方案都以 AddDataProtection() 为起点,默认设置的理解因此成为整个数据保护知识体系的地基。

关键要点总结

  • 一行 AddDataProtection() 即可启用完整的密钥环管理、密钥滚动与认证加密能力,且随 ASP.NET Core 共享框架分发,无需额外包引用;
  • 默认密钥环落盘位置因操作系统而异,非 Windows 平台默认不对密钥做静态加密,生产环境必须显式配置;
  • 通过 IDataProtectionProvider.CreateProtector("目的字符串") 派生具名保护器,是实现密钥隔离与防伪造的最佳实践;
  • Protect/Unprotect 构成闭环,密文自带完整性认证,篡改或目的串不匹配将直接抛异常;
  • 多实例、容器化、云环境下的密钥共享与加密需求,可在同一 API 基础上通过 PersistKeysTo*、ProtectKeysWith* 扩展点平滑升级,仓库中五个进阶示例覆盖了 Blob、Key Vault、Redis、EF Core 与自定义加密器五条主流路径。
登录后查看全文
practical-aspnetcore