Redação de dados no .NET

O processo de redação ajuda você a sanitizar ou mascarar informações confidenciais em logs, mensagens de erro ou outros resultados. Isso mantém você em conformidade com as regras de privacidade e protege dados confidenciais. É útil em aplicativos que lidam com dados pessoais, informações financeiras ou outros pontos de dados confidenciais.

Instalar o pacote de redação

Para iniciar, instale o pacote NuGet 📦 Microsoft.Extensions.Compliance.Redaction:

dotnet add package Microsoft.Extensions.Compliance.Redaction

dotnet package add Microsoft.Extensions.Compliance.Redaction

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Compliance.Redaction"
                    Version="*" />
</ItemGroup>

Redatores disponíveis

Os redatores são responsáveis pelo ato de remover dados confidenciais. Eles redigim, substituem ou mascaram informações confidenciais. Considere os seguintes redatores disponíveis fornecidos pela biblioteca.

• O ErasingRedactor substitui qualquer entrada por uma cadeia de caracteres vazia.
• O HmacRedactor usa HMACSHA256 para codificar dados que estão em processo de redação.

Exemplo de utilização

Para usar os redatores internos, você precisa registrar os serviços necessários. Registre os serviços usando um dos métodos de AddRedaction disponíveis, conforme descrito na seguinte lista:

• AddRedaction(IServiceCollection): registra uma implementação de IRedactorProvider no IServiceCollection.
• AddRedaction(IServiceCollection, Action<IRedactionBuilder>): registra uma implementação de IRedactorProvider no IServiceCollection e configura os redatores disponíveis com o delegado configure fornecido.

Configurar um redator

Obter redatores em tempo de execução usando um IRedactorProvider. Você pode implementar seu próprio provedor e registrá-lo dentro da chamada AddRedaction ou usar o provedor padrão. Configure redatores usando estes métodos IRedactionBuilder:

// 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>();

Considerando essa classificação de dados em seu código:

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

Configurar o redator HMAC

Configure o redator HMAC usando estes métodos IRedactionBuilder:

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

Como alternativa, configure-o dessa forma:

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

Inclua esta seção no arquivo de configuração JSON:

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

• O HmacRedactorOptions requer que suas propriedades HmacRedactorOptions.Key e HmacRedactorOptions.KeyId sejam definidas.
• O Key deve estar no formato base 64 e com pelo menos 44 caracteres. Use uma chave distinta para cada implantação principal de um serviço. Mantenha o material da chave em segredo e renove-o regularmente.
• O KeyId é acrescentado a cada valor redigido para identificar a chave usada para hash dos dados.
• IDs de chave diferentes significam que os valores não estão relacionados e não podem ser usados para correlação.

Configurar um redator personalizado

Para criar um redator personalizado, defina uma subclasse que herda de Redactor:

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

Criar um provedor de editor personalizado

A interface IRedactorProvider fornece instâncias de redatores com base na classificação de dados. Para criar um provedor de redator personalizado, herde de IRedactorProvider conforme mostrado no exemplo a seguir:

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

Registrar informações confidenciais em log

O registro em log é uma fonte comum de exposição acidental de dados. Informações confidenciais, como dados pessoais, credenciais ou detalhes financeiros, nunca devem ser gravadas em logs em texto sem formatação. Para evitar isso, sempre use a redação ao registrar dados potencialmente confidenciais.

Etapas para registrar dados confidenciais em log

1. Instale o pacote de extensões de telemetria: instale Microsoft.Extensions.Telemetry para poder usar o logger estendido para ativar o recurso de redação.
2. Configurar redação: Integre os redatores ao pipeline de registros chamando o AddRedaction(IServiceCollection) método para limpar ou mascarar automaticamente os campos confidenciais antes que eles sejam gravados nos logs.
3. Identificar campos confidenciais: saiba quais dados em seu aplicativo são confidenciais e exigem proteção e marque-os com a classificação de dados apropriada.
4. Examine a saída do log: audite regularmente seus logs para garantir que nenhum dado confidencial seja exposto.

Exemplo: Redigir dados em logs

Ao usar o Microsoft.Extensions.Logging, você pode combinar a redação com o log da seguinte maneira:

using Microsoft.Extensions.Telemetry;
using Microsoft.Extensions.Compliance.Redaction;

var services = new ServiceCollection();
services.AddLogging(builder =>
{
    // Enable redaction.
    builder.EnableRedaction();
});

services.AddRedaction(builder =>
{
    // configure redactors for your data classifications
    builder.SetRedactor<StarRedactor>(MyTaxonomyClassifications.Private);
});
// Use annotations to mark sensitive data.
// For example, apply the Private classification to SSN data.
[LoggerMessage(0, LogLevel.Information, "User SSN: {SSN}")]
public static partial void LogPrivateInformation(
    this ILogger logger,
    [MyTaxonomyClassifications.Private] string SSN);

public void TestLogging()
{
    LogPrivateInformation("MySSN");
}

A saída deve ser assim:

User SSN: *****

Isso garante que os dados confidenciais sejam redigidos antes de serem registrados, reduzindo o risco de vazamentos de dados.