Dela via

Översikt över konsument-API:er för ASP.NET Core

Gränssnitten IDataProtectionProvider och IDataProtector är de grundläggande gränssnitt genom vilka konsumenterna använder dataskyddssystemet. De finns i paketet Microsoft.AspNetCore.DataProtection.Abstractions .

IDataProtectionProvider

Providergränssnittet representerar roten i dataskyddssystemet. Den kan inte användas direkt för att skydda eller ta bort skydd mot data. I stället måste konsumenten hämta en referens till en IDataProtector genom att anropa IDataProtectionProvider.CreateProtector(purpose), där syftet är en sträng som beskriver det avsedda konsumentanvändningsfallet. Se Användningssträngar för mycket mer information om avsikten med den här parametern och hur du väljer ett lämpligt värde.

IDataProtector

Skyddsgränssnittet returneras av ett anrop till CreateProtector, och det är det här gränssnittet som konsumenter kan använda för att utföra skydds- och oskyddade åtgärder.

För att skydda en del data skickar du data till Protect metoden. Det grundläggande gränssnittet definierar en metod som konverterar byte[] -> byte[], men det finns också en överlagrad metod (en tilläggsmetod) som konverterar sträng -> sträng. Säkerheten som erbjuds av de två metoderna är identisk; utvecklaren bör välja vilken överlagring som passar bäst för deras användningsfall. Oavsett vilken överbelastning som valts är det värde som returneras av Protect-metoden nu skyddat (krypterat och förfalskningsskyddat) och programmet kan skicka det till en obetrodd klient.

Om du vill ta bort skyddet av ett tidigare skyddat datastycke skickar du skyddade data till Unprotect metoden. (Det finns byte[]-baserade och strängbaserade överlagringar för utvecklarens bekvämlighet.) Om den skyddade nyttolasten genererades av ett tidigare anrop till Protect på samma IDataProtectorsätt Unprotect returnerar metoden den ursprungliga oskyddade nyttolasten. Om den skyddade nyttolasten har manipulerats eller skapats av en annan IDataProtector, Unprotect genererar metoden CryptographicException.

Begreppet samma kontra olika IDataProtector kopplas tillbaka till begreppet syfte. Om två IDataProtector instanser genererades från samma rot IDataProtectionProvider men via olika syften i anropen till IDataProtectionProvider.CreateProtector, betraktas de som olika skyddsinstanser, och den ena kommer inte att kunna ta bort skyddet från nyttolaster som genereras av den andra.

Förbruka dessa gränssnitt

För en DI-medveten komponent är den avsedda användningen att komponenten tar en IDataProtectionProvider parameter i konstruktorn och att DI-systemet automatiskt tillhandahåller den här tjänsten när komponenten instansieras.

Anmärkning

Vissa program (till exempel konsolprogram eller ASP.NET 4.x-program) kanske inte är DI-medvetna, så de kan inte använda den mekanism som beskrivs här. För dessa scenarier, konsultera dokumentet Icke DI-medvetna scenarier för mer information om hur du hämtar en instans av en IDataProtection provider utan att gå via DI.

Följande exempel visar tre begrepp:

  1. Lägg till dataskyddssystemet i tjänstcontainern,

  2. Genom att använda DI för att ta emot en instans av en IDataProtectionProvider, och

  3. Skapa en IDataProtector från en IDataProtectionProvider och använda den för att skydda och ta bort skydd mot data.

Konsolapp

using System;
using Microsoft.AspNetCore.DataProtection;
using Microsoft.Extensions.DependencyInjection;

public class Program
{
    public static void Main(string[] args)
    {
        // add data protection services
        var serviceCollection = new ServiceCollection();
        serviceCollection.AddDataProtection();
        var services = serviceCollection.BuildServiceProvider();

        // create an instance of MyClass using the service provider
        var instance = ActivatorUtilities.CreateInstance<MyClass>(services);
        instance.RunSample();
    }

    public class MyClass
    {
        IDataProtector _protector;

        // the 'provider' parameter is provided by DI
        public MyClass(IDataProtectionProvider provider)
        {
            _protector = provider.CreateProtector("Contoso.MyClass.v1");
        }

        public void RunSample()
        {
            Console.Write("Enter input: ");
            string input = Console.ReadLine();

            // protect the payload
            string protectedPayload = _protector.Protect(input);
            Console.WriteLine($"Protect returned: {protectedPayload}");

            // unprotect the payload
            string unprotectedPayload = _protector.Unprotect(protectedPayload);
            Console.WriteLine($"Unprotect returned: {unprotectedPayload}");
        }
    }
}

/*
 * SAMPLE OUTPUT
 *
 * Enter input: Hello world!
 * Protect returned: CfDJ8ICcgQwZZhlAlTZT...OdfH66i1PnGmpCR5e441xQ
 * Unprotect returned: Hello world!
 */

Webbapp

Ring AddDataProtection(IServiceCollection, Action<DataProtectionOptions>) in Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews();
builder.Services.AddDataProtection();

var app = builder.Build();

Följande markerade kod visar hur du använder IDataProtector i en kontrollant:

public class HomeController : Controller
{
    private readonly IDataProtector _dataProtector;

    public HomeController(IDataProtectionProvider dataProtectionProvider)
    {
        _dataProtector = dataProtectionProvider.CreateProtector("HomeControllerPurpose");
    }

    // ...

    public IActionResult Privacy()
    {
        // The original data to protect
        string originalData = "original data";

        // Protect the data (encrypt)
        string protectedData = _dataProtector.Protect(originalData);
        Console.WriteLine($"Protected Data: {protectedData}");

        // Unprotect the data (decrypt)
        string unprotectedData = _dataProtector.Unprotect(protectedData);
        Console.WriteLine($"Unprotected Data: {unprotectedData}");

        return View();
    }
    
    // ...

Paketet Microsoft.AspNetCore.DataProtection.Abstractions innehåller en tilläggsmetod GetDataProtector som en bekvämlighet för utvecklare. Som en enda åtgärd kapslar den in både hämtning av en IDataProtectionProvider från tjänstleverantören och anrop av IDataProtectionProvider.CreateProtector. Följande exempel visar dess användning:

using System;
using Microsoft.AspNetCore.DataProtection;
using Microsoft.Extensions.DependencyInjection;
 
public class Program
{
    public static void Main(string[] args)
    {
        // add data protection services
        var serviceCollection = new ServiceCollection();
        serviceCollection.AddDataProtection();
        var services = serviceCollection.BuildServiceProvider();
 
        // get an IDataProtector from the IServiceProvider
        var protector = services.GetDataProtector("Contoso.Example.v2");
        Console.Write("Enter input: ");
        string input = Console.ReadLine();
 
        // protect the payload
        string protectedPayload = protector.Protect(input);
        Console.WriteLine($"Protect returned: {protectedPayload}");
 
        // unprotect the payload
        string unprotectedPayload = protector.Unprotect(protectedPayload);
        Console.WriteLine($"Unprotect returned: {unprotectedPayload}");
    }
}

Tips/Råd

Instanser av IDataProtectionProvider och IDataProtector är trådsäkra för flera anropare. Det är avsett att när en komponent hämtar en referens till en IDataProtector via ett anrop till CreateProtectoranvänder den referensen för flera anrop till Protect och Unprotect. Ett anrop till Unprotect genererar CryptographicException om den skyddade nyttolasten inte kan verifieras eller dechiffreras. Vissa komponenter kanske vill ignorera fel under oskyddade åtgärder. en komponent som läser autentiseringscookies kan hantera det här felet och behandla begäran som om den inte alls hade någon cookie i stället för att misslyckas med begäran direkt. Komponenter som vill ha det här beteendet bör specifikt fånga CryptographicException i stället för att svälja alla undantag.

  • Last updated on