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 NuGet package:

dotnet add package Microsoft.Extensions.Compliance.Redaction

dotnet package add Microsoft.Extensions.Compliance.Redaction

<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 ErasingRedactor replaces any input with an empty string.
• The 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:

• AddRedaction(IServiceCollection): Registers an implementation of IRedactorProvider in the IServiceCollection.
• AddRedaction(IServiceCollection, Action<IRedactionBuilder>): Registers an implementation of IRedactorProvider in the IServiceCollection and configures available redactors with the given configure delegate.

Configure a redactor

Fetch redactors at runtime using an IRedactorProvider. You can implement your own provider and register it inside the AddRedaction call, or use the default provider. Configure redactors using these IRedactionBuilder methods:

// 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:

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 IRedactionBuilder methods:

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:

var serviceCollection = new ServiceCollection();
serviceCollection.AddRedaction(builder =>
{
    builder.SetHmacRedactor(
        Configuration.GetSection("HmacRedactorOptions"), MyTaxonomyClassifications.Personal);
});

Include this section in your JSON config file:

{
    "HmacRedactorOptions": {
        "KeyId": 1234567890,
        "Key": "1234567890abcdefghijklmnopqrstuvwxyz"
    }
}

• The HmacRedactorOptions requires its HmacRedactorOptions.Key and HmacRedactorOptions.KeyId 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.

Configure a custom redactor

To create a custom redactor, define a subclass that inherits from Redactor:

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 IRedactorProvider interface provides instances of redactors based on data classification. To create a custom redactor provider, inherit from IRedactorProvider as shown in the following example:

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;
}