Gambaran umum API Konsumen untuk ASP.NET Core

Artikel
11/06/2024

Antarmuka IDataProtectionProvider dan IDataProtector adalah antarmuka dasar di mana konsumen menggunakan sistem perlindungan data. Mereka terletak di paket Microsoft.AspNetCore.DataProtection.Abstractions .

IDataProtectionProvider

Antarmuka penyedia mewakili akar sistem perlindungan data. Ini tidak dapat langsung digunakan untuk melindungi atau membatalkan perlindungan data. Sebaliknya, konsumen harus mendapatkan referensi ke IDataProtector dengan memanggil IDataProtectionProvider.CreateProtector(purpose), di mana tujuannya adalah string yang menjelaskan kasus penggunaan konsumen yang dimaksudkan. Lihat String Tujuan untuk informasi selengkapnya tentang niat parameter ini dan cara memilih nilai yang sesuai.

IDataProtector

Antarmuka pelindung dikembalikan oleh panggilan ke CreateProtector, dan antarmuka inilah yang dapat digunakan konsumen untuk melakukan operasi perlindungan dan pembatalan perlindungan.

Untuk melindungi sepotong data, teruskan data ke Protect metode . Antarmuka dasar mendefinisikan metode yang mengonversi byte[] -> byte[], tetapi ada juga kelebihan beban (disediakan sebagai metode ekstensi) yang mengonversi string -> string. Keamanan yang ditawarkan oleh dua metode tersebut identik; pengembang harus memilih kelebihan beban mana yang paling nyaman untuk kasus penggunaan mereka. Terlepas dari kelebihan beban yang dipilih, nilai yang dikembalikan oleh metode Lindungi sekarang dilindungi (disandikan dan dirusak), dan aplikasi dapat mengirimkannya ke klien yang tidak tepercaya.

Untuk membuka proteksi bagian data yang dilindungi sebelumnya, teruskan data yang dilindungi ke Unprotect metode . (Ada kelebihan beban berbasis byte[]dan berbasis string untuk kenyamanan pengembang.) Jika payload yang dilindungi dihasilkan oleh panggilan sebelumnya ke Protect pada hal yang sama IDataProtectorini, Unprotect metode akan mengembalikan payload asli yang tidak terlindungi. Jika payload yang dilindungi telah dirusak atau diproduksi oleh yang berbeda IDataProtector, Unprotect metode akan melemparkan CryptographicException.

Konsep ikatan yang sama vs. berbeda IDataProtector kembali ke konsep tujuan. Jika dua IDataProtector instans dihasilkan dari root IDataProtectionProvider yang sama tetapi melalui string tujuan yang berbeda dalam panggilan ke IDataProtectionProvider.CreateProtector, maka mereka dianggap sebagai pelindung yang berbeda, dan satu tidak akan dapat membatalkan perlindungan payload yang dihasilkan oleh yang lain.

Mengkonsumsi antarmuka ini

Untuk komponen sadar DI, penggunaan yang dimaksudkan adalah bahwa komponen mengambil IDataProtectionProvider parameter dalam konstruktornya dan bahwa sistem DI secara otomatis menyediakan layanan ini ketika komponen dibuat.

Catatan

Beberapa aplikasi (seperti aplikasi konsol atau aplikasi ASP.NET 4.x) mungkin tidak diketahui sehingga tidak dapat menggunakan mekanisme yang dijelaskan di sini. Untuk skenario ini, lihat dokumen Skenario Non DI Aware untuk informasi lebih lanjut tentang mendapatkan instans IDataProtection penyedia tanpa melalui DI.

Sampel berikut menunjukkan tiga konsep:

Tambahkan sistem perlindungan data ke kontainer layanan,
Menggunakan DI untuk menerima instans IDataProtectionProvider, dan
IDataProtector Membuat dari IDataProtectionProvider dan menggunakannya untuk melindungi dan membatalkan perlindungan data.

Aplikasi konsol

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

Aplikasi web

Panggil AddDataProtection(IServiceCollection, Action<DataProtectionOptions>) di Program.cs:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Kode yang disorot berikut menunjukkan cara menggunakan IDataProtector dalam pengontrol:

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 berisi metode GetDataProtector ekstensi sebagai kenyamanan pengembang. Ini merangkum sebagai operasi tunggal yang mengambil IDataProtectionProvider dari penyedia layanan dan memanggil IDataProtectionProvider.CreateProtector. Sampel berikut menunjukkan penggunaannya:

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

Instans IDataProtectionProvider dan IDataProtector aman untuk beberapa penelepon. Ini dimaksudkan bahwa setelah komponen mendapatkan referensi ke IDataProtector melalui panggilan ke CreateProtector, itu akan menggunakan referensi tersebut untuk beberapa panggilan ke Protect dan Unprotect. Panggilan ke Unprotect akan melempar CryptographicException jika payload yang dilindungi tidak dapat diverifikasi atau diurai. Beberapa komponen mungkin ingin mengabaikan kesalahan selama operasi yang tidak terlindungi; komponen yang membaca cookie autentikasi mungkin menangani kesalahan ini dan memperlakukan permintaan seolah-olah tidak cookie memiliki sama sekali daripada gagal permintaan secara langsung. Komponen yang menginginkan perilaku ini harus secara khusus menangkap CryptographicException alih-alih menelan semua pengecualian.

Bagikan melalui