ASP.NET Core 数据保护ASP.NET Core Data Protection

Web 应用程序通常需要将安全敏感数据存储。Web applications often need to store security-sensitive data. Windows 桌面应用程序提供 DPAPI,但这并不适合 web 应用程序。Windows provides DPAPI for desktop applications but this is unsuitable for web applications. ASP.NET Core 数据保护堆栈提供一个简单、 易于使用的加密 API,开发人员可以使用来保护数据,包括密钥管理和旋转。The ASP.NET Core data protection stack provide a simple, easy to use cryptographic API a developer can use to protect data, including key management and rotation.

ASP.NET Core 数据保护堆栈旨在用作的长期替代<machineKey>在 ASP.NET 中的元素 1.x-4.x。The ASP.NET Core data protection stack is designed to serve as the long-term replacement for the <machineKey> element in ASP.NET 1.x - 4.x. 它旨在解决许多旧加密堆栈的不足之处同时为大多数现代应用程序可能会遇到的使用情况下提供开箱解决方案。It was designed to address many of the shortcomings of the old cryptographic stack while providing an out-of-the-box solution for the majority of use cases modern applications are likely to encounter.

问题陈述Problem statement

总体问题语句可以用于简单地在单个句子中所述:我需要保留以供将来检索受信任的信息,但我不信任持久性机制。The overall problem statement can be succinctly stated in a single sentence: I need to persist trusted information for later retrieval, but I don't trust the persistence mechanism. 在 web 术语中,这可能会根据写入"我需要为往返通过不受信任的客户端的受信任状态。"In web terms, this might be written as "I need to round-trip trusted state via an untrusted client."

此规范的示例是身份验证 cookie 或持有者令牌。The canonical example of this is an authentication cookie or bearer token. 服务器会生成"我是 Groot,具有 xyz 的权限"令牌并将它传递到客户端。The server generates an "I am Groot and have xyz permissions" token and hands it to the client. 在将来某天的客户端将显示该令牌发送回服务器,但该服务器需要某种类型的客户端尚未伪造令牌的保障。At some future date the client will present that token back to the server, but the server needs some kind of assurance that the client hasn't forged the token. 因此第一个要求: 真实性 (也称为Thus the first requirement: authenticity (a.k.a. 完整性、 防篡改攻击)。integrity, tamper-proofing).

持久化的状态由服务器信任的因为我们预计这种状态可能包含特定于操作环境的信息。Since the persisted state is trusted by the server, we anticipate that this state might contain information that's specific to the operating environment. 这可能是在文件路径、 权限、 句柄或其他间接引用的窗体或其他一些特定于服务器的数据。This could be in the form of a file path, a permission, a handle or other indirect reference, or some other piece of server-specific data. 此类信息通常不应公开到不受信任的客户端。Such information should generally not be disclosed to an untrusted client. 因此第二个要求: 保密性。Thus the second requirement: confidentiality.

最后,现代应用程序的组件化,因为我们已了解是各个组件将想要充分利用此系统而不考虑其他组件的系统中。Finally, since modern applications are componentized, what we've seen is that individual components will want to take advantage of this system without regard to other components in the system. 例如,如果持有者令牌组件使用的此堆栈,它应运行不受干扰地从一种反 CSRF 机制,也可能使用相同的堆栈。For instance, if a bearer token component is using this stack, it should operate without interference from an anti-CSRF mechanism that might also be using the same stack. 因此最后一项要求: 隔离。Thus the final requirement: isolation.

我们可以进一步约束以缩小我们的要求的范围。We can provide further constraints in order to narrow the scope of our requirements. 我们假定加密系统内的所有服务都是同等信任和数据无需生成或在我们的直接控制服务外部使用。We assume that all services operating within the cryptosystem are equally trusted and that the data doesn't need to be generated or consumed outside of the services under our direct control. 此外,我们需要的操作是尽可能快,因为 web 服务的每个请求可能会经过加密系统的一个或多个时间。Furthermore, we require that operations are as fast as possible since each request to the web service might go through the cryptosystem one or more times. 这使得对称加密非常适合用于我们的方案,和我们可以折扣此类具有所需的时间之前的非对称加密。This makes symmetric cryptography ideal for our scenario, and we can discount asymmetric cryptography until such a time that it's needed.

设计理念Design philosophy

我们首先使用现有的堆栈识别问题。We started by identifying problems with the existing stack. 一旦我们有的我们的调查了现有解决方案布局而得出的结论是,没有现有的解决方案没有我们查找的功能。Once we had that, we surveyed the landscape of existing solutions and concluded that no existing solution quite had the capabilities we sought. 然后,我们设计基于多个指导原则的解决方案。We then engineered a solution based on several guiding principles.

  • 系统应提供简单的配置。The system should offer simplicity of configuration. 理想情况下系统将为零配置,并且开发人员可以快速开始使用。Ideally the system would be zero-configuration and developers could hit the ground running. 在开发人员需要配置一个特定方面 (如密钥存储库) 的情况下,应考虑到使这些特定的配置更简单。In situations where developers need to configure a specific aspect (such as the key repository), consideration should be given to making those specific configurations simple.

  • 提供一个简单的面向消费者的 API。Offer a simple consumer-facing API. Api 应易于正确使用且难以使用不正确。The APIs should be easy to use correctly and difficult to use incorrectly.

  • 开发人员不应了解密钥管理原则。Developers shouldn't learn key management principles. 系统应处理算法选择和开发人员的代表的密钥生存期。The system should handle algorithm selection and key lifetime on the developer's behalf. 理想情况下,开发人员甚至不应具有访问原始密钥材料。Ideally the developer should never even have access to the raw key material.

  • 应尽可能的静态保护密钥。Keys should be protected at rest when possible. 系统应找出相应的默认保护机制,并将其自动应用。The system should figure out an appropriate default protection mechanism and apply it automatically.

记住这些原则与我们开发了一个简单易于使用数据保护堆栈。With these principles in mind we developed a simple, easy to use data protection stack.

ASP.NET Core 数据保护 Api 主要不用于机密负载的无限期持久性。The ASP.NET Core data protection APIs are not primarily intended for indefinite persistence of confidential payloads. 等其他技术Windows CNG DPAPIAzure Rights Management更适合的无限期存储方案,并且必须相应地强密钥管理功能。Other technologies like Windows CNG DPAPI and Azure Rights Management are more suited to the scenario of indefinite storage, and they have correspondingly strong key management capabilities. 也就是说,无需进行任何开发人员禁止使用 ASP.NET Core 数据保护 Api 进行长期保护的机密数据。That said, there's nothing prohibiting a developer from using the ASP.NET Core data protection APIs for long-term protection of confidential data.


数据保护系统分为五个主要的软件包。The data protection system is divided into five main packages. 这些 Api 的各个方面定位三个主要受众;Various aspects of these APIs target three main audiences;

  1. 使用者 Api 概述目标应用程序和框架开发人员。The Consumer APIs Overview target application and framework developers.

    "我不想要了解有关在堆栈的运行方式或配置方式。"I don't want to learn about how the stack operates or about how it's configured. 我只是想要执行某项操作中的最简单的方式尽可能高概率为成功使用 Api。"I simply want to perform some operation in as simple a manner as possible with high probability of using the APIs successfully."

  2. 配置 Api目标应用程序开发人员和系统管理员。The configuration APIs target application developers and system administrators.

    "我需要告诉我的环境需要非默认路径或设置数据保护系统。""I need to tell the data protection system that my environment requires non-default paths or settings."

  3. 扩展性 Api 目标,开发人员负责实现自定义策略。The extensibility APIs target developers in charge of implementing custom policy. 这些 Api 的使用情况将限于极少数情况下并遇到安全注意开发人员。Usage of these APIs would be limited to rare situations and experienced, security aware developers.

    "我需要替换的整个系统内组件,因为我有真正独特的行为要求。"I need to replace an entire component within the system because I have truly unique behavioral requirements. 我愿意以了解不常见使用的 API 图面部分,若要生成可满足我的要求的插件。"I am willing to learn uncommonly-used parts of the API surface in order to build a plugin that fulfills my requirements."

包布局Package layout

数据保护堆栈包含五个包。The data protection stack consists of five packages.

其他资源Additional resources

在 Web 场中托管 ASP.NET Core