Panoramica delle API consumer per ASP.NET CoreConsumer APIs overview for ASP.NET Core

Il IDataProtectionProvider e IDataProtector interfacce sono le interfacce di base tramite cui i consumer utilizzano il sistema di protezione dati.The IDataProtectionProvider and IDataProtector interfaces are the basic interfaces through which consumers use the data protection system. Che si trovano nel Microsoft.AspNetCore.DataProtection.Abstractions pacchetto.They're located in the Microsoft.AspNetCore.DataProtection.Abstractions package.

IDataProtectionProviderIDataProtectionProvider

L'interfaccia del provider rappresenta la radice del sistema di protezione dati.The provider interface represents the root of the data protection system. Non è direttamente utilizzabile per proteggere o rimuovere la protezione dei dati.It cannot directly be used to protect or unprotect data. Al contrario, il consumer deve ottenere un riferimento a un IDataProtector chiamando IDataProtectionProvider.CreateProtector(purpose), in cui scopo è una stringa che descrive il caso d'uso previsto consumer.Instead, the consumer must get a reference to an IDataProtector by calling IDataProtectionProvider.CreateProtector(purpose), where purpose is a string that describes the intended consumer use case. Visualizzare stringhe di scopi per molte più informazioni all'obiettivo di questo parametro e come scegliere un valore appropriato.See Purpose Strings for much more information on the intent of this parameter and how to choose an appropriate value.

IDataProtectorIDataProtector

L'interfaccia di protezione viene restituito da una chiamata a CreateProtectored è questa interfaccia che gli utenti possono usare per eseguire proteggere e rimuovere la protezione di operazioni.The protector interface is returned by a call to CreateProtector, and it's this interface which consumers can use to perform protect and unprotect operations.

Per proteggere una porzione di dati, passare i dati per il Protect (metodo).To protect a piece of data, pass the data to the Protect method. L'interfaccia di base definisce un metodo che converte byte [] -> byte [], ma è presente anche un overload (fornito come metodo di estensione) che lo converte in stringa -> stringa.The basic interface defines a method which converts byte[] -> byte[], but there's also an overload (provided as an extension method) which converts string -> string. La sicurezza offerta da due metodi è identica. lo sviluppatore deve scegliere qualsiasi overload è più semplice per i casi d'uso.The security offered by the two methods is identical; the developer should choose whichever overload is most convenient for their use case. Indipendentemente dall'overload scelto, il valore restituito da Protect metodo è ora protetto (cifrati e prova di manomissione) e l'applicazione può inviare a un client non attendibile.Irrespective of the overload chosen, the value returned by the Protect method is now protected (enciphered and tamper-proofed), and the application can send it to an untrusted client.

Per disattivare la protezione una porzione di dati protetti in precedenza, passare i dati protetti per il Unprotect (metodo).To unprotect a previously-protected piece of data, pass the protected data to the Unprotect method. (Sono presenti byte []-overload in base e basate su stringhe per comodità dello sviluppatore.) Se il payload protetto è stato generato da una precedente chiamata a Protect questa stessa IDataProtector, il Unprotect metodo restituirà il payload non protetto originale.(There are byte[]-based and string-based overloads for developer convenience.) If the protected payload was generated by an earlier call to Protect on this same IDataProtector, the Unprotect method will return the original unprotected payload. Se il payload protetto è stato alterato o è stato generato da un'altra IDataProtector, il Unprotect metodo genererà CryptographicException.If the protected payload has been tampered with or was produced by a different IDataProtector, the Unprotect method will throw CryptographicException.

Il concetto di uguale e diversi IDataProtector ties indietro al concetto di utilizzo generico.The concept of same vs. different IDataProtector ties back to the concept of purpose. Se due IDataProtector istanze sono state generate dalla stessa radice IDataProtectionProvider ma tramite stringhe di scopi diversi nella chiamata a IDataProtectionProvider.CreateProtector, quindi considerate protezioni diversi, e uno non saranno in grado di rimuovere la protezione payload generati dagli altri.If two IDataProtector instances were generated from the same root IDataProtectionProvider but via different purpose strings in the call to IDataProtectionProvider.CreateProtector, then they're considered different protectors, and one won't be able to unprotect payloads generated by the other.

Utilizzo di queste interfacceConsuming these interfaces

Per un componente compatibile con l'inserimento delle dipendenze, l'utilizzo previsto è che il componente accetta un IDataProtectionProvider parametro nel relativo costruttore e che il sistema di inserimento delle dipendenze offre questo servizio automaticamente quando viene creata un'istanza al componente.For a DI-aware component, the intended usage is that the component takes an IDataProtectionProvider parameter in its constructor and that the DI system automatically provides this service when the component is instantiated.

Nota

Alcune applicazioni (ad esempio applicazioni console o applicazioni ASP.NET 4.x) potrebbero non essere l'inserimento delle dipendenze in grado di riconoscere in modo che non è possibile utilizzare il meccanismo descritto di seguito.Some applications (such as console applications or ASP.NET 4.x applications) might not be DI-aware so cannot use the mechanism described here. Per questi scenari, consultare il scenari Non compatibili con documento per altre informazioni su come ottenere un'istanza di un IDataProtection provider senza passare attraverso l'inserimento delle dipendenze.For these scenarios consult the Non DI Aware Scenarios document for more information on getting an instance of an IDataProtection provider without going through DI.

L'esempio seguente illustra tre concetti:The following sample demonstrates three concepts:

  1. Aggiungere il sistema di protezione dati al contenitore del servizio,Add the data protection system to the service container,

  2. Tramite l'inserimento delle dipendenze per la ricezione di un'istanza di un IDataProtectionProvider, eUsing DI to receive an instance of an IDataProtectionProvider, and

  3. Creazione di un' IDataProtector da un IDataProtectionProvider e usandolo per proteggere e rimuovere la protezione dei dati.Creating an IDataProtector from an IDataProtectionProvider and using it to protect and unprotect data.

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

Il pacchetto Microsoft.AspNetCore.DataProtection.Abstractions contiene un metodo di estensione IServiceProvider.GetDataProtector comodità per gli sviluppatori.The package Microsoft.AspNetCore.DataProtection.Abstractions contains an extension method IServiceProvider.GetDataProtector as a developer convenience. Incapsula un'unica operazione entrambi il recupero di un IDataProtectionProvider dal provider del servizio e chiamare il metodo IDataProtectionProvider.CreateProtector.It encapsulates as a single operation both retrieving an IDataProtectionProvider from the service provider and calling IDataProtectionProvider.CreateProtector. L'esempio seguente viene illustrato l'utilizzo.The following sample demonstrates its usage.

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

Suggerimento

Le istanze di IDataProtectionProvider e IDataProtector sono thread-safe per i chiamanti di più.Instances of IDataProtectionProvider and IDataProtector are thread-safe for multiple callers. È destinato che una volta che un componente ottiene un riferimento a un IDataProtector tramite una chiamata verso CreateProtector, che fanno riferimento a verranno utilizzate per più chiamate a Protect e Unprotect.It's intended that once a component gets a reference to an IDataProtector via a call to CreateProtector, it will use that reference for multiple calls to Protect and Unprotect. Una chiamata a Unprotect genererà CryptographicException se il payload protetto non può essere verificato o decifrato.A call to Unprotect will throw CryptographicException if the protected payload cannot be verified or deciphered. Alcuni componenti può essere utile ignorare gli errori durante rimuovere la protezione di operazioni; un componente che legge i cookie di autenticazione può gestire questo errore e trattare la richiesta come se non avesse alcun cookie affatto anziché Nega la richiesta direttamente.Some components may wish to ignore errors during unprotect operations; a component which reads authentication cookies might handle this error and treat the request as if it had no cookie at all rather than fail the request outright. I componenti che questo comportamento devono in particolare intercettare CryptographicException invece di assorbimento di tutte le eccezioni.Components which want this behavior should specifically catch CryptographicException instead of swallowing all exceptions.