Adding Redaction and Compliance docs

docs/core/extensions/compliance.md

@@ -0,0 +1,21 @@
+---
+title: Compliance libraries in .NET
+description: Learn how to use compliance libraries to implement compliance features in .NET applications.
+ms.date: 03/21/2025
+---
+
+# Compliance libraries in .NET
+
+.NET provides libraries that offer foundational components and abstractions for implementing compliance features, such as data classification and redaction, in .NET applications. These abstractions help developers create and manage data in a standardized way. In this article, you get an overview on the data classification and redaction compliance libraries.
+
+## Data classification in .NET
+
+Data classification helps categorize data based on its sensitivity and protection level using the <xref:Microsoft.Extensions.Compliance.Classification.DataClassification> structure. This allows you to label sensitive information and enforce policies based on these labels. You can create custom classifications and attributes to tag your data appropriately.
+
+For more information about .NET's data classification library, see [Data classification in .NET](data-classification.md).
+
+## Data redaction in .NET
+
+Data redaction helps protect sensitive information in logs, error messages, or other outputs to comply with privacy rules and protect sensitive data. The <xref:Microsoft.Extensions.Compliance.Redaction> library provides various redactors, such as the <xref:Microsoft.Extensions.Compliance.Redaction.ErasingRedactor> and <xref:Microsoft.Extensions.Compliance.Redaction.HmacRedactor>. You can configure these redactors and register them using the `AddRedaction` methods. Additionally, you can create custom redactors and redactor providers to suit your specific needs.
+
+For more information about .NET's data redaction library, see [Data redaction in .NET](data-redaction.md).

docs/core/extensions/data-classification.md

@@ -0,0 +1,134 @@
+---
+title: Data classification in .NET
+description: Learn how to use .NET data classification libraries to categorize your application's data.
+ms.date: 03/21/2025
+---
+
+# Data classification in .NET
+
+Data classification helps you categorize (or classify) data based on its sensitivity and protection level. The <xref:Microsoft.Extensions.Compliance.Classification.DataClassification> structure lets you label sensitive information and enforce policies based on these labels.
+
+- <xref:Microsoft.Extensions.Compliance.Classification.DataClassification.TaxonomyName?displayProperty=nameWithType>: Identifies the classification system.
+- <xref:Microsoft.Extensions.Compliance.Classification.DataClassification.Value?displayProperty=nameWithType>: Represents the specific label within the taxonomy.
+
+In some situations, you might need to specify that data explicitly has no data classification, this is achieved with <xref:Microsoft.Extensions.Compliance.Classification.DataClassification.None?displayProperty=nameWithType>. Similarly, you might need to specify that data classification is unknown—use <xref:Microsoft.Extensions.Compliance.Classification.DataClassification.Unknown?displayProperty=nameWithType> in these cases.
+
+## Install the package
+
+To get started, install the [📦 Microsoft.Extensions.Compliance.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.Compliance.Abstractions) NuGet package:
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Microsoft.Extensions.Compliance.Abstractions
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.Extensions.Compliance.Abstractions"
+                    Version="*" />
+</ItemGroup>
+```
+
+---
+
+## Create custom classifications
+
+Define custom classifications by creating `static` members for different types of sensitive data. This gives you a consistent way to label and handle data across your app. Consider the following example class:
+
+```csharp
+using Microsoft.Extensions.Compliance.Classification;
+
+internal static class MyTaxonomyClassifications
+{
+    internal static string Name => "MyTaxonomy";
+
+    internal static DataClassification PrivateInformation => new(Name, nameof(PrivateInformation));
+    internal static DataClassification CreditCardNumber => new(Name, nameof(CreditCardNumber));
+    internal static DataClassification SocialSecurityNumber => new(Name, nameof(SocialSecurityNumber));
+
+    internal static DataClassificationSet PrivateAndSocialSet => new(PrivateInformation, SocialSecurityNumber);
+}
+```
+
+If you want to share your custom classification taxonomy with other apps, this class and its members should be `public` instead of `internal`. For example, you can have a shared library containing custom classifications, that you can use in multiple applications.
+
+<xref:Microsoft.Extensions.Compliance.Classification.DataClassificationSet> lets you compose multiple data classifications into a single set. This allows you classify your data with multiple data classifications. In addition, the .NET redaction APIs make use of a <xref:Microsoft.Extensions.Compliance.Classification.DataClassificationSet>.
+
+## Create custom classification attributes
+
+Create custom attributes based on your custom classifications. Use these attributes to tag your data with the right classification. Consider the following custom attribute class definition:
+
+```csharp
+public sealed class PrivateInformationAttribute : DataClassificationAttribute
+{
+    public PrivateInformationAttribute()
+        : base(MyTaxonomyClassifications.PrivateInformation)
+    {
+    }
+}
+```
+
+The preceding code declares a private information attribute, that's a subclass of the <xref:Microsoft.Extensions.Compliance.Classification.DataClassificationAttribute> type. It defines a parameterless constructor and pass the custom <xref:Microsoft.Extensions.Compliance.Classification.DataClassification> to its `base`.
+
+## Bind data classification settings
+
+To bind your data classification settings, use the .NET configuration system. For example, assuming you're using a JSON configuration provider, your _appsettings.json_ could be defined as follows:
+
+```json
+{
+    "Key": {
+        "PhoneNumber": "MyTaxonomy:PrivateInformation",
+        "ExampleDictionary": {
+            "CreditCard": "MyTaxonomy:CreditCardNumber",
+            "SSN": "MyTaxonomy:SocialSecurityNumber"
+        }
+    }
+}
+```
+
+Now consider the following options pattern approach, that binds these configuration settings into the `TestOptions` object:
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Compliance.Classification;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Options;
+
+public class TestOptions
+{
+    public DataClassification? PhoneNumber { get; set; }
+    public IDictionary<string, DataClassification> ExampleDictionary { get; set; } = new Dictionary<string, DataClassification>();
+}
+
+class Program
+{
+    static void Main(string[] args)
+    {
+        // Build configuration from an external json file.
+        IConfiguration configuration = new ConfigurationBuilder()
+            .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
+            .Build();
+
+        // Setup DI container and bind the configuration section "Key" to TestOptions.
+        IServiceCollection services = new ServiceCollection();
+        services.Configure<TestOptions>(configuration.GetSection("Key"));
+
+        // Build the service provider.
+        IServiceProvider serviceProvider = services.BuildServiceProvider();
+
+        // Get the bound options.
+        TestOptions options = serviceProvider.GetRequiredService<IOptions<TestOptions>>().Value;
+
+        // Simple output demonstrating binding results.
+        Console.WriteLine("Configuration bound to TestOptions:");
+        Console.WriteLine($"PhoneNumber: {options.PhoneNumber}");
+        foreach (var item in options.ExampleDictionary)
+        {
+            Console.WriteLine($"{item.Key}: {item.Value}");
+        }
+    }
+}
+```

docs/core/extensions/data-redaction.md

@@ -0,0 +1,179 @@
+---
+title: Data redaction in .NET
+description: Learn how to use .NET data redaction libraries to protect your application's sensitive data.
+ms.date: 03/21/2025
+---
+
+# Data redaction in .NET
+
+Redaction helps you sanitize or mask sensitive information in logs, error messages, or other outputs. This keeps you compliant with privacy rules and protects sensitive data. It's useful in apps that handle personal data, financial information, or other confidential data points.
+
+## Install redaction package
+
+To get started, install the [📦 Microsoft.Extensions.Compliance.Redaction](https://www.nuget.org/packages/Microsoft.Extensions.Compliance.Redaction) NuGet package:
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Microsoft.Extensions.Compliance.Redaction
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.Extensions.Compliance.Redaction"
+                    Version="*" />
+</ItemGroup>
+```
+
+---
+
+## Available redactors
+
+Redactors are responsible for the act of redacting sensitive data. They redact, replace, or mask sensitive information. Consider the following available redactors provided by the library:
+
+- The <xref:Microsoft.Extensions.Compliance.Redaction.ErasingRedactor> replaces any input with an empty string.
+- The <xref:Microsoft.Extensions.Compliance.Redaction.HmacRedactor> uses `HMACSHA256` to encode data being redacted.
+
+## Usage example
+
+To use the built-in redactors, you have to register the required services. Register the services using one of the available `AddRedaction` methods as described in the following list:
+
+- <xref:Microsoft.Extensions.DependencyInjection.RedactionServiceCollectionExtensions.AddRedaction(Microsoft.Extensions.DependencyInjection.IServiceCollection)>: Registers an implementation of <xref:Microsoft.Extensions.Compliance.Redaction.IRedactorProvider> in the <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection>.
+- <xref:Microsoft.Extensions.DependencyInjection.RedactionServiceCollectionExtensions.AddRedaction(Microsoft.Extensions.DependencyInjection.IServiceCollection,System.Action{Microsoft.Extensions.Compliance.Redaction.IRedactionBuilder})>: Registers an implementation of <xref:Microsoft.Extensions.Compliance.Redaction.IRedactorProvider> in the <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection> and configures available redactors with the given `configure` delegate.
+
+### Configure a redactor
+
+Fetch redactors at runtime using an <xref:Microsoft.Extensions.Compliance.Redaction.IRedactorProvider>. You can implement your own provider and register it inside the `AddRedaction` call, or use the default provider. Configure redactors using these <xref:Microsoft.Extensions.Compliance.Redaction.IRedactionBuilder> methods:
+
+```csharp
+// This will use the default redactor, which is the ErasingRedactor
+var serviceCollection = new ServiceCollection();
+serviceCollection.AddRedaction();
+
+// Using the default redactor provider:
+serviceCollection.AddRedaction(redactionBuilder =>
+{
+    // Assign a redactor to use for a set of data classifications.
+    redactionBuilder.SetRedactor<StarRedactor>(
+        MyTaxonomyClassifications.Private,
+        MyTaxonomyClassifications.Personal);
+    // Assign a fallback redactor to use when processing classified data for which no specific redactor has been registered.
+    // The `ErasingRedactor` is the default fallback redactor. If no redactor is configured for a data classification then the data will be erased.
+    redactionBuilder.SetFallbackRedactor<MyFallbackRedactor>();
+});
+
+// Using a custom redactor provider:
+builder.Services.AddSingleton<IRedactorProvider, StarRedactorProvider>();
+```
+
+Given this data classification in your code:
+
+```csharp
+public static class MyTaxonomyClassifications
+{
+    public static string Name => "MyTaxonomy";
+
+    public static DataClassification Private => new(Name, nameof(Private));
+    public static DataClassification Public => new(Name, nameof(Public));
+    public static DataClassification Personal => new(Name, nameof(Personal));
+}
+```
+
+### Configure the HMAC redactor
+
+Configure the HMAC redactor using these <xref:Microsoft.Extensions.Compliance.Redaction.IRedactionBuilder> methods:
+
+```csharp
+var serviceCollection = new ServiceCollection();
+serviceCollection.AddRedaction(builder =>
+{
+    builder.SetHmacRedactor(
+        options =>
+        {
+            options.KeyId = 1234567890;
+            options.Key = Convert.ToBase64String("1234567890abcdefghijklmnopqrstuvwxyz");
+        },
+
+        // Any data tagged with Personal or Private attributes will be redacted by the Hmac redactor.
+        MyTaxonomyClassifications.Personal, MyTaxonomyClassifications.Private,
+
+        // "DataClassificationSet" lets you compose multiple data classifications:
+        // For example, here the Hmac redactor will be used for data tagged
+        // with BOTH Personal and Private (but not one without the other).
+        new DataClassificationSet(MyTaxonomyClassifications.Personal,
+                                  MyTaxonomyClassifications.Private));
+});
+```
+
+Alternatively, configure it this way:
+
+```csharp
+var serviceCollection = new ServiceCollection();
+serviceCollection.AddRedaction(builder =>
+{
+    builder.SetHmacRedactor(
+        Configuration.GetSection("HmacRedactorOptions"), MyTaxonomyClassifications.Personal);
+});
+```
+
+Include this section in your JSON config file:
+
+```json
+{
+    "HmacRedactorOptions": {
+        "KeyId": 1234567890,
+        "Key": "1234567890abcdefghijklmnopqrstuvwxyz"
+    }
+}
+```
+
+- The <xref:Microsoft.Extensions.Compliance.Redaction.HmacRedactorOptions> requires its <xref:Microsoft.Extensions.Compliance.Redaction.HmacRedactorOptions.Key?displayProperty=nameWithType> and <xref:Microsoft.Extensions.Compliance.Redaction.HmacRedactorOptions.KeyId?displayProperty=nameWithType> properties to be set.
+- The `Key` should be in base 64 format and at least 44 characters long. Use a distinct key for each major deployment of a service. Keep the key material secret and rotate it regularly.
+- The `KeyId` is appended to each redacted value to identify the key used to hash the data.
+- Different key IDs mean the values are unrelated and can't be used for correlation.
+
+> [!NOTE]
+> The <xref:Microsoft.Extensions.Compliance.Redaction.HmacRedactor> is still experimental, so the preceding methods will cause the `EXTEXP0002` warningm indicating it's not yet stable.
+> To use it, add `<NoWarn>$(NoWarn);EXTEXP0002</NoWarn>` to your project file or add `#pragma warning disable EXTEXP0002` around the calls to `SetHmacRedactor`.
+
+### Configure a custom redactor
+
+To create a custom redactor, define a subclass that inherits from <xref:Microsoft.Extensions.Compliance.Redaction.Redactor>:
+
+```csharp
+public sealed class StarRedactor : Redactor
+
+public class StarRedactor : Redactor
+{
+    private const string Stars = "****";
+
+    public override int GetRedactedLength(ReadOnlySpan<char> input) => Stars.Length;
+
+    public override int Redact(ReadOnlySpan<char> source, Span<char> destination)
+    {
+        Stars.CopyTo(destination);
+
+        return Stars.Length;
+    }
+}
+```
+
+### Create a custom redactor provider
+
+The <xref:Microsoft.Extensions.Compliance.Redaction.IRedactorProvider> interface provides instances of redactors based on data classification. To create a custom redactor provider, inherit from <xref:Microsoft.Extensions.Compliance.Redaction.IRedactorProvider> as shown in the following example:
+
+```csharp
+using Microsoft.Extensions.Compliance.Classification;
+using Microsoft.Extensions.Compliance.Redaction;
+
+public sealed class StarRedactorProvider : IRedactorProvider
+{
+    private static readonly StarRedactor _starRedactor = new();
+
+    public static StarRedactorProvider Instance { get; } = new();
+
+    public Redactor GetRedactor(DataClassificationSet classifications) => _starRedactor;
+}
+```

docs/fundamentals/toc.yml

@@ -673,6 +673,14 @@ items:
                 href: runtime-libraries/system-text-rune.md
               - name: StringBuilder class
                 href: runtime-libraries/system-text-stringbuilder.md
+      - name: Compliance
+        items:
+          - name: Overview
+            href: ../core/extensions/compliance.md
+          - name: Data classification
+            href: ../core/extensions/data-classification.md
+          - name: Data redaction
+            href: ../core/extensions/data-redaction.md
       - name: Regular expressions
         items:
           - name: Overview