Přehled uživatelských rozhraní API pro ASP.NET Core

Článek
11/30/2023

Rozhraní IDataProtectionProvider jsou IDataProtector základní rozhraní, pomocí kterých spotřebitelé používají systém ochrany dat. Nachází se v balíčku Microsoft.AspNetCore.DataProtection.Abstractions .

IDataProtectionProvider

Rozhraní zprostředkovatele představuje kořen systému ochrany dat. Nelze ji použít přímo k ochraně nebo zrušení ochrany dat. Místo toho musí příjemce získat odkaz na IDataProtector volání IDataProtectionProvider.CreateProtector(purpose), kde účel je řetězec, který popisuje zamýšlený případ použití příjemce. Další informace o záměru tohoto parametru a o tom, jak zvolit odpovídající hodnotu, najdete v tématu Řetězce účelu.

IDataProtector

Rozhraní ochrany je vráceno voláním CreateProtectora je to toto rozhraní, které uživatelé mohou použít k provádění operací ochrany a zrušení ochrany.

Pokud chcete chránit část dat, předejte data metodě Protect . Základní rozhraní definuje metodu, která převádí bajt[] -> bajt[], ale existuje také přetížení (poskytnuté jako rozšiřující metoda), která převádí řetězec -> řetězec. Zabezpečení nabízené dvěma metodami je identické; vývojář by měl zvolit, které přetížení je pro jejich případ použití nejvhodnější. Bez ohledu na zvolené přetížení je teď hodnota vrácená metodou Protect chráněná (šifrovaná a manipulovaná) a aplikace ji může odeslat nedůvěryhodnému klientovi.

Pokud chcete odemknout dříve chráněnou část dat, předejte chráněná data metodě Unprotect . (Pro usnadnění vývoje existují bajty[]založené na bajtech a přetížení založená na řetězcích.) Pokud byla chráněná datová část vygenerována dřívějším voláním Protect této stejné IDataProtector, Unprotect metoda vrátí původní nechráněnou datovou část. Pokud byla chráněná datová část manipulována nebo byla vytvořena jinou IDataProtector, Unprotect metoda vyvolá kryptografickýexception.

Koncept stejných vs. různých IDataProtector vazeb zpět k konceptu účelu. Pokud byly dvě IDataProtector instance vygenerovány ze stejného kořenového adresáře IDataProtectionProvider , ale prostřednictvím různých řetězců účelu IDataProtectionProvider.CreateProtectorvolání , pak se považují za různé ochrany a jedna nebude schopna zrušit ochranu datových částí vygenerovaných druhou instancí.

Využívání těchto rozhraní

Pro komponentu pracující s di-aware je zamýšlené použití, že komponenta přebírá IDataProtectionProvider parametr v jeho konstruktoru a že systém DI automaticky poskytuje tuto službu při vytvoření instance komponenty.

Poznámka

Některé aplikace (například konzolové aplikace nebo aplikace ASP.NET 4.x) nemusí znát di-aware, takže nelze použít mechanismus popsaný zde. V těchto scénářích najdete další informace o získání instance IDataProtection poskytovatele bez nutnosti procházení distancí.

Následující ukázka ukazuje tři koncepty:

Přidání systému ochrany dat do kontejneru služby
Použití DI k přijetí instance objektu IDataProtectionProvidera
Vytvoření z objektu IDataProtectorIDataProtectionProvider a jeho použití k ochraně a zrušení ochrany dat

Konzolová aplikace

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!
 */

Webová aplikace

VoláníAddDataProtection(IServiceCollection, Action<DataProtectionOptions>):Program.cs

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Následující zvýrazněný kód ukazuje, jak se používá IDataProtector v kontroleru:

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

Microsoft.AspNetCore.DataProtection.Abstractions Balíček obsahuje metodu GetDataProtector rozšíření pro usnadnění vývoje. Zapouzdřuje se jako jedna operace, která načítá IDataProtectionProvider z poskytovatele služeb i volání IDataProtectionProvider.CreateProtector. Následující ukázka ukazuje její využití:

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

Tip

IDataProtectionProvider Instance a IDataProtector jsou bezpečné pro více volajících. Je zamýšleno, že jakmile komponenta získá odkaz na IDataProtector prostřednictvím volání CreateProtector, použije tento odkaz pro více volání a ProtectUnprotect. Volání Unprotect vyvolá kryptografickou výjimkuException, pokud chráněnou datovou část nelze ověřit nebo dešifrovat. Některé komponenty mohou chtít ignorovat chyby během nechráněných operací; Komponenta, která čte ověřování cookie, může tuto chybu zpracovat a zacházet s požadavkem, jako by vůbec neměla, cookie a ne přímo selhat požadavek. Komponenty, které chtějí toto chování, by měly konkrétně zachytit kryptografickou výjimku místo polykání všech výjimek.

Share via