ASP.NET Core için tüketici API'lerine genel bakış

Makale
11/06/2024

IDataProtectionProvider ve IDataProtector arabirimleri, tüketicilerin veri koruma sistemini kullandığı temel arabirimlerdir. Microsoft.AspNetCore.DataProtection.Abstractions paketinde bulunurlar .

IDataProtectionProvider

Sağlayıcı arabirimi, veri koruma sisteminin kökünü temsil eder. Verileri korumak veya korumasını silmek için doğrudan kullanılamaz. Bunun yerine, tüketici çağrısı yaparak IDataProtectionProvider.CreateProtector(purpose)öğesine IDataProtector başvuru almalıdır; burada amaç, hedeflenen tüketici kullanım örneğini açıklayan bir dizedir. Bu parametrenin amacı ve uygun bir değerin nasıl seçileceği hakkında daha fazla bilgi için bkz . Amaç Dizeleri .

IDataProtector

Koruyucu arabirimi, CreateProtectorçağrısı tarafından döndürülür ve tüketicilerin koruma ve korumayı kaldırma işlemlerini gerçekleştirmek için kullanabileceği arabirimdir.

Bir veri parçasını korumak için, verileri yöntemine Protect geçirin. Temel arabirim bayt[] -> bayt[] dönüştüren bir yöntem tanımlar, ancak dize -> dizeyi dönüştüren bir aşırı yükleme (uzantı yöntemi olarak sağlanır) da vardır. İki yöntem tarafından sunulan güvenlik aynıdır; geliştirici, kullanım örneği için en uygun aşırı yüklemeyi seçmelidir. Seçilen aşırı yüklemeden bağımsız olarak, Protect yöntemi tarafından döndürülen değer artık korunur (şifrelenmiş ve kurcalamaya karşı korumalıdır) ve uygulama bunu güvenilmeyen bir istemciye gönderebilir.

Daha önce korunan bir veri parçasının korumasını silmek için korunan verileri yöntemine Unprotect geçirin. (Geliştirici kolaylığı için bayt[]tabanlı ve dize tabanlı aşırı yüklemeler vardır.) Korumalı yük bu aynı IDataProtectorUnprotect üzerinde önceki bir çağrısı Protect tarafından oluşturulduysa, yöntem özgün korumasız yükü döndürür. Korumalı yük üzerinde oynanmışsa veya farklı IDataProtectorUnprotect bir tarafından oluşturulduysa, yöntemi CryptographicException oluşturur.

Aynı kavram ile farklı IDataProtector bağlarının amaç kavramına geri dönmesi. aynı kökten ancak çağrısında IDataProtectionProvider.CreateProtectorfarklı amaçlı dizeler aracılığıyla iki IDataProtector örnek oluşturulduysa, bunlar farklı koruyucular olarak kabul edilir ve biri diğerinin oluşturduğu yüklerin korumasını kaldıramaz.IDataProtectionProvider

Bu arabirimleri kullanma

DI kullanan bir bileşen için amaçlanan kullanım, bileşenin oluşturucusunda bir IDataProtectionProvider parametre alması ve bileşen örneği oluşturulurken DI sisteminin bu hizmeti otomatik olarak sağlamasıdır.

Not

Bazı uygulamalar (konsol uygulamaları veya ASP.NET 4.x uygulamaları gibi) DI farkında olmayabilir, bu nedenle burada açıklanan mekanizmayı kullanamaz. Bu senaryolar için DI'den geçmeden bir IDataProtection sağlayıcı örneği alma hakkında daha fazla bilgi için DI'ye Duyarlı Olmayan Senaryolar belgesine başvurun.

Aşağıdaki örnekte üç kavram gösterilmektedir:

Veri koruma sistemini hizmet kapsayıcısına ekleyin,
bir ve örneğini IDataProtectionProvideralmak için DI kullanma
'den IDataProtectionProvider oluşturma IDataProtector ve verileri korumak ve korumasını kaldırmak için bunu kullanma.

Konsol uygulaması

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

Web uygulaması

çağrısı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();

Aşağıdaki vurgulanmış kod, denetleyicide nasıl kullanılacağını IDataProtector gösterir:

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

Paket Microsoft.AspNetCore.DataProtection.Abstractions , geliştirici kolaylığı olarak bir uzantı yöntemi GetDataProtector içerir. Hem hizmet sağlayıcısından alma hem de çağrısı IDataProtectionProvider.CreateProtectorgibi tek bir IDataProtectionProvider işlem olarak kapsüller. Aşağıdaki örnekte kullanımı gösterilmektedir:

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

İpucu

ve IDataProtector örnekleriIDataProtectionProvider, birden çok arayan için iş parçacığı açısından güvenlidir. Bir bileşen çağrısı aracılığıyla bir başvuru IDataProtector aldığında ve Unprotectöğesine yapılan birden çok çağrı CreateProtectoriçin bu başvuruyı Protect kullanması amaçlanmıştır. Unprotect Korumalı yük doğrulanamıyorsa veya deşifre edilemiyorsa çağrısı CryptographicException oluşturur. Bazı bileşenler korumasını kaldırma işlemleri sırasında hataları yoksaymak isteyebilir; kimlik doğrulama tanımlama bilgilerini okuyan bir bileşen bu hatayı işleyebilir ve isteğin başarısız olması yerine hiç yokmuş cookie gibi davranabilir. Bu davranışı isteyen bileşenler, tüm özel durumları yutmak yerine özellikle CryptographicException'ı yakalamalıdır.

Aracılığıyla paylaş