From 115ab8728f4154d461262fa6aec82e39c76e4d27 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 8 May 2024 13:00:00 -1000 Subject: [PATCH 1/4] Mon prep --- .../data-protection/includes/introduction7.md | 99 +++++++++++++++++++ .../security/data-protection/introduction.md | 5 + 2 files changed, 104 insertions(+) create mode 100644 aspnetcore/security/data-protection/includes/introduction7.md diff --git a/aspnetcore/security/data-protection/includes/introduction7.md b/aspnetcore/security/data-protection/includes/introduction7.md new file mode 100644 index 000000000000..48845d5a7e67 --- /dev/null +++ b/aspnetcore/security/data-protection/includes/introduction7.md @@ -0,0 +1,99 @@ +:::moniker range="< aspnetcore-8.0" + +# ASP.NET Core Data Protection Overview + +ASP.NET Core provides a cryptographic API to protect data, including key management and rotation. + +Web apps often need to store sensitive data. The Windows data protection API ([DPAPI](/dotnet/standard/security/how-to-use-data-protection)) isn't intended for use in web apps. + +The ASP.NET Core data protection stack was designed to: + +* Provide a built in solution for most Web scenarios. +* Address many of the deficiencies of the previous encryption system. +* Serve as the replacement for the `` element in ASP.NET 1.x - 4.x. + +## Problem statement + +*I need to persist trusted information for later retrieval, but I don't trust the persistence mechanism.* In web terms, this might be written as *I need to round-trip trusted state via an untrusted client.* + +Authenticity, integrity, and tamper-proofing is a requirement. The canonical example of this is an authentication cookie or bearer token. The server generates an ***I am Groot and have xyz permissions*** token and sends it to the client. The client presents that token back to the server, but the server needs some kind of assurance that the client hasn't forged the token. + +Confidentiality is a requirement. Since the persisted state is trusted by the server, this state could contain information that shouldn't be disclosed to an untrusted client. For example: + +* A file path. +* A permission. +* A handle or other indirect reference. +* Some server-specific data. + +Isolation is a requirement. Since modern apps are componentized, individual components want to take advantage of this system without regard to other components in the system. For instance, consider a bearer token component using this stack. It should operate without any interference, for example, from an anti-CSRF mechanism also using the same stack. + +Some common assumptions can narrow the scope of requirements: + +* All services operating within the cryptosystem are equally trusted. +* The data doesn't need to be generated or consumed outside of the services under our direct control. +* Operations must be fast since each request to the web service might go through the cryptosystem one or more times. The speed requirement makes symmetric cryptography ideal. Asymmetric cryptography isn't used until it's required. + +## Design philosophy + +ASP.NET Core data protection is an [easy to use](xref:security/data-protection/using-data-protection) data protection stack. It's based on the following principles: + +* Ease of configuration. The system strives for zero configuration. In situations where developers need to configure a specific aspect, such as the key repository, those specific configurations aren't difficult. +* Offer a basic consumer-facing API. The APIs are straight forward to use correctly and difficult to use incorrectly. +* Developers don't have to learn key management principles. The system handles algorithm selection and key lifetime on behalf of the developer. The developer doesn't have access to the raw key material. +* Keys are protected at rest as much as possible. The system figures out an appropriate default protection mechanism and applies it automatically. + +The data protection APIs aren't primarily intended for indefinite persistence of confidential payloads. Other technologies, such as [Windows CNG DPAPI](/windows/win32/seccng/cng-dpapi) and [Azure Rights Management](/rights-management/) are more suited to the scenario of indefinite storage. They have correspondingly strong key management capabilities. That said, the ASP.NET Core data protection APIs can be used for long-term protection of confidential data. + +## Audience + +The data protection system provides APIs that target three main audiences: + +1. The [consumer APIs](xref:security/data-protection/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. I just want to perform some operation with high probability of using the APIs successfully.* + +2. The [configuration APIs](xref:security/data-protection/configuration/overview) target app developers and system administrators. + + *I need to tell the data protection system that my environment requires non-default paths or settings.* + +3. The extensibility APIs target developers in charge of implementing custom policy. Usage of these APIs is limited to rare situations and developers with security experience. + + *I need to replace an entire component within the system because I have truly unique behavioral requirements. I'm 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: + +* [Microsoft.AspNetCore.DataProtection.Abstractions](https://www.nuget.org/packages/Microsoft.AspNetCore.DataProtection.Abstractions/) contains: + + * and interfaces to create data protection services. + * Useful extension methods for working with these types. for example, [IDataProtector.Protect](xref:Microsoft.AspNetCore.DataProtection.IDataProtector.Protect%2A) + + If the data protection system is instantiated elsewhere and you're consuming the API, reference `Microsoft.AspNetCore.DataProtection.Abstractions`. + +* [Microsoft.AspNetCore.DataProtection](https://www.nuget.org/packages/Microsoft.AspNetCore.DataProtection/) contains the core implementation of the data protection system, including: + + * Core cryptographic operations. + * Key management. + * Configuration and extensibility. + + To instantiate the data protection system, reference `Microsoft.AspNetCore.DataProtection`. You might need to reference the data protection system when: + + * Adding it to an . + * Modifying or extending its behavior. + +* [Microsoft.AspNetCore.DataProtection.Extensions](https://www.nuget.org/packages/Microsoft.AspNetCore.DataProtection.Extensions/) contains additional APIs which developers might find useful but which don't belong in the core package. For instance, this package contains: + + * Factory methods to instantiate the data protection system to store keys at a location on the file system without dependency injection. See . + * Extension methods for limiting the lifetime of protected payloads. See . + +* [Microsoft.AspNetCore.DataProtection.SystemWeb](https://www.nuget.org/packages/Microsoft.AspNetCore.DataProtection.SystemWeb/) can be installed into an existing ASP.NET 4.x app to redirect its `` operations to use the new ASP.NET Core data protection stack. For more information, see . + +* [Microsoft.AspNetCore.Cryptography.KeyDerivation](https://www.nuget.org/packages/Microsoft.AspNetCore.Cryptography.KeyDerivation/) provides an implementation of the PBKDF2 password hashing routine and can be used by systems that must handle user passwords securely. For more information, see . + +## Additional resources + +* +* + +:::moniker-end diff --git a/aspnetcore/security/data-protection/introduction.md b/aspnetcore/security/data-protection/introduction.md index 2053a655ffcf..c5e2cb5e139f 100644 --- a/aspnetcore/security/data-protection/introduction.md +++ b/aspnetcore/security/data-protection/introduction.md @@ -7,6 +7,9 @@ ms.custom: mvc ms.date: 03/07/2022 uid: security/data-protection/introduction --- + +:::moniker range=">= aspnetcore-8.0" + # ASP.NET Core Data Protection Overview ASP.NET Core provides a cryptographic API to protect data, including key management and rotation. @@ -102,3 +105,5 @@ The data protection stack consists of five packages: * * + +:::moniker-end From 3d12aa7cf56dfc614d44e37bba3e1b4769d4df84 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 8 May 2024 13:02:10 -1000 Subject: [PATCH 2/4] Mon prep --- aspnetcore/security/data-protection/introduction.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/aspnetcore/security/data-protection/introduction.md b/aspnetcore/security/data-protection/introduction.md index c5e2cb5e139f..bea3eb42405b 100644 --- a/aspnetcore/security/data-protection/introduction.md +++ b/aspnetcore/security/data-protection/introduction.md @@ -107,3 +107,6 @@ The data protection stack consists of five packages: * :::moniker-end + +[!INCLUDE[](~/security/data-protection/includes/introduction7.md)] + From 20912527877842fe42f547d06f583a8520edbb49 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 8 May 2024 13:18:24 -1000 Subject: [PATCH 3/4] Mon prep --- .../security/data-protection/includes/introduction7.md | 2 -- aspnetcore/security/data-protection/introduction.md | 5 ++--- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/aspnetcore/security/data-protection/includes/introduction7.md b/aspnetcore/security/data-protection/includes/introduction7.md index 48845d5a7e67..c1ac8db8d22d 100644 --- a/aspnetcore/security/data-protection/includes/introduction7.md +++ b/aspnetcore/security/data-protection/includes/introduction7.md @@ -1,7 +1,5 @@ :::moniker range="< aspnetcore-8.0" -# ASP.NET Core Data Protection Overview - ASP.NET Core provides a cryptographic API to protect data, including key management and rotation. Web apps often need to store sensitive data. The Windows data protection API ([DPAPI](/dotnet/standard/security/how-to-use-data-protection)) isn't intended for use in web apps. diff --git a/aspnetcore/security/data-protection/introduction.md b/aspnetcore/security/data-protection/introduction.md index bea3eb42405b..b46cc7ed647b 100644 --- a/aspnetcore/security/data-protection/introduction.md +++ b/aspnetcore/security/data-protection/introduction.md @@ -8,10 +8,10 @@ ms.date: 03/07/2022 uid: security/data-protection/introduction --- -:::moniker range=">= aspnetcore-8.0" - # ASP.NET Core Data Protection Overview +:::moniker range=">= aspnetcore-8.0" + ASP.NET Core provides a cryptographic API to protect data, including key management and rotation. Web apps often need to store sensitive data. The Windows data protection API ([DPAPI](/dotnet/standard/security/how-to-use-data-protection)) isn't intended for use in web apps. @@ -109,4 +109,3 @@ The data protection stack consists of five packages: :::moniker-end [!INCLUDE[](~/security/data-protection/includes/introduction7.md)] - From 6c3c963eaefe8e8b167039d75774778cfd7c7e8a Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 8 May 2024 13:19:35 -1000 Subject: [PATCH 4/4] Mon prep --- cspell.json | 48 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/cspell.json b/cspell.json index 5dcda1ba6644..c9f7b672446d 100644 --- a/cspell.json +++ b/cspell.json @@ -2,11 +2,49 @@ "version": "0.1", "language": "en", "words": [ - "antiforgery","appsettings","aspnet","aspnetcore","Blazor","Blazor's","blazorwasm","blazorserver","blazor", - "dotnetcli","entra","guardrex","kiota","Linq","Microservices","microservices","msal","NuGet","nuget","oidc", - "Prerender","prerendering","signalr","rendermode","rerender","rerenders","rerendering","riande","Routable", - "routable","Prerendered","prerendered","wadepickett","wasm","webassembly","webform","webforms","websocket", - "websockets","wwwroot" + "antiforgery", + "appsettings", + "aspnet", + "aspnetcore", + "blazor", + "Blazor", + "Blazor's", + "blazorserver", + "blazorwasm", + "componentized", + "cryptosystem", + "dotnetcli", + "DPAPI", + "entra", + "guardrex", + "kiota", + "Linq", + "microservices", + "Microservices", + "msal", + "nuget", + "NuGet", + "oidc", + "Prerender", + "prerendered", + "Prerendered", + "prerendering", + "rendermode", + "rerender", + "rerendering", + "rerenders", + "riande", + "routable", + "Routable", + "signalr", + "wadepickett", + "wasm", + "webassembly", + "webform", + "webforms", + "websocket", + "websockets", + "wwwroot" ], "flagWords": [ "hte"