Gestione delle chiavi in ASP.NET CoreKey management in ASP.NET Core

Il sistema di protezione dei dati gestisce automaticamente la durata delle chiavi master utilizzate per proteggere e rimuovere la protezione dei payload.The data protection system automatically manages the lifetime of master keys used to protect and unprotect payloads. Ogni chiave può esistere in una delle quattro fasi seguenti:Each key can exist in one of four stages:

  • Creato: la chiave esiste nell'anello chiave, ma non è ancora stata attivata.Created - the key exists in the key ring but has not yet been activated. La chiave non deve essere usata per le nuove operazioni di protezione fino a quando non è trascorso tempo sufficiente che la chiave abbia avuto la possibilità di propagarsi a tutti i computer che utilizzano questo anello di chiave.The key shouldn't be used for new Protect operations until sufficient time has elapsed that the key has had a chance to propagate to all machines that are consuming this key ring.

  • Attivo: la chiave esiste nell'anello chiave e deve essere usata per tutte le nuove operazioni di protezione.Active - the key exists in the key ring and should be used for all new Protect operations.

  • Scaduto: la chiave ha eseguito la durata naturale e non deve più essere usata per le nuove operazioni di protezione.Expired - the key has run its natural lifetime and should no longer be used for new Protect operations.

  • Revocata: la chiave viene compromessa e non deve essere usata per le nuove operazioni di protezione.Revoked - the key is compromised and must not be used for new Protect operations.

È possibile utilizzare tutte le chiavi create, Active e expire per rimuovere la protezione dai payload in ingresso.Created, active, and expired keys may all be used to unprotect incoming payloads. Per impostazione predefinita, le chiavi revocate non possono essere usate per rimuovere la protezione dei payload, ma lo sviluppatore dell'applicazione può eseguire l'override di questo comportamento , se necessario.Revoked keys by default may not be used to unprotect payloads, but the application developer can override this behavior if necessary.

Avviso

Lo sviluppatore potrebbe essere tentato di eliminare una chiave dall'anello chiave, ad esempio eliminando il file corrispondente dal file system.The developer might be tempted to delete a key from the key ring (e.g., by deleting the corresponding file from the file system). A questo punto, tutti i dati protetti dalla chiave sono permanentemente decifrabili e non esiste alcun override di emergenza, ad esempio con chiavi revocate.At that point, all data protected by the key is permanently undecipherable, and there's no emergency override like there's with revoked keys. L'eliminazione di una chiave è effettivamente un comportamento distruttivo e, di conseguenza, il sistema di protezione dei dati non espone alcuna API di prima classe per l'esecuzione di questa operazione.Deleting a key is truly destructive behavior, and consequently the data protection system exposes no first-class API for performing this operation.

Selezione chiave predefinitaDefault key selection

Quando il sistema di protezione dei dati legge l'anello di chiave dal repository sottostante, tenterà di individuare una chiave "predefinita" dall'anello di chiave.When the data protection system reads the key ring from the backing repository, it will attempt to locate a "default" key from the key ring. La chiave predefinita viene usata per le nuove operazioni di protezione.The default key is used for new Protect operations.

L'euristica generale è che il sistema di protezione dei dati sceglie la chiave con la data di attivazione più recente come chiave predefinita.The general heuristic is that the data protection system chooses the key with the most recent activation date as the default key. (È presente un piccolo fattore di fudge per consentire lo sfasamento di clock da server a server). Se la chiave è scaduta o revocata e se l'applicazione non ha disabilitato la generazione automatica delle chiavi, verrà generata una nuova chiave con attivazione immediata in base alla scadenza della chiave e ai criteri in sequenza.(There's a small fudge factor to allow for server-to-server clock skew.) If the key is expired or revoked, and if the application has not disabled automatic key generation, then a new key will be generated with immediate activation per the key expiration and rolling policy below.

Il motivo per cui il sistema di protezione dei dati genera immediatamente una nuova chiave anziché eseguire il fallback a una chiave diversa consiste nel fatto che la nuova generazione di chiavi deve essere considerata come scadenza implicita di tutte le chiavi attivate prima della nuova chiave.The reason the data protection system generates a new key immediately rather than falling back to a different key is that new key generation should be treated as an implicit expiration of all keys that were activated prior to the new key. L'idea generale è che le nuove chiavi potrebbero essere state configurate con algoritmi diversi o con meccanismi di crittografia inattivi rispetto alle chiavi obsolete e il sistema deve preferire la configurazione corrente sul fallback.The general idea is that new keys may have been configured with different algorithms or encryption-at-rest mechanisms than old keys, and the system should prefer the current configuration over falling back.

Si è verificata un'eccezione.There's an exception. Se lo sviluppatore dell'applicazione ha disabilitato la generazione automatica delle chiavi, è necessario che il sistema di protezione dei dati scelga una chiave predefinita.If the application developer has disabled automatic key generation, then the data protection system must choose something as the default key. In questo scenario di fallback, il sistema sceglie la chiave non revocata con la data di attivazione più recente, con la preferenza assegnata alle chiavi che hanno avuto tempo per la propagazione ad altri computer del cluster.In this fallback scenario, the system will choose the non-revoked key with the most recent activation date, with preference given to keys that have had time to propagate to other machines in the cluster. Il sistema di fallback potrebbe quindi scegliere una chiave predefinita scaduta.The fallback system may end up choosing an expired default key as a result. Il sistema di fallback non sceglie mai una chiave revocata come chiave predefinita e se l'anello chiave è vuoto o ogni chiave è stata revocata, il sistema genera un errore durante l'inizializzazione.The fallback system will never choose a revoked key as the default key, and if the key ring is empty or every key has been revoked then the system will produce an error upon initialization.

Scadenza e sequenza di chiaviKey expiration and rolling

Quando viene creata una chiave, viene automaticamente fornita una data di attivazione di {Now + 2 giorni} e una data di scadenza di {Now + 90 giorni}.When a key is created, it's automatically given an activation date of { now + 2 days } and an expiration date of { now + 90 days }. Il ritardo di 2 giorni prima dell'attivazione consente di propagarsi nel sistema.The 2-day delay before activation gives the key time to propagate through the system. Ovvero consente ad altre applicazioni che puntano all'archivio di backup di osservare la chiave al successivo periodo di aggiornamento automatico, ottimizzando così le probabilità che, quando l'anello chiave diventa attivo, sia stato propagato a tutte le applicazioni che potrebbero dover utilizzarlo.That is, it allows other applications pointing at the backing store to observe the key at their next auto-refresh period, thus maximizing the chances that when the key ring does become active it has propagated to all applications that might need to use it.

Se la chiave predefinita scadrà entro 2 giorni e se l'anello chiave non dispone già di una chiave che sarà attiva dopo la scadenza della chiave predefinita, il sistema di protezione dei dati renderà automaticamente persistente una nuova chiave per l'anello di chiave.If the default key will expire within 2 days and if the key ring doesn't already have a key that will be active upon expiration of the default key, then the data protection system will automatically persist a new key to the key ring. La nuova chiave ha una data di attivazione di {data di scadenza della chiave predefinita} e una data di scadenza di {Now + 90 giorni}.This new key has an activation date of { default key's expiration date } and an expiration date of { now + 90 days }. Ciò consente al sistema di eseguire automaticamente il rollup delle chiavi a intervalli regolari senza interruzioni del servizio.This allows the system to automatically roll keys on a regular basis with no interruption of service.

Potrebbero esserci casi in cui una chiave verrà creata con attivazione immediata.There might be circumstances where a key will be created with immediate activation. Un esempio potrebbe essere quando l'applicazione non è stata eseguita per un periodo di tempo e tutte le chiavi nell'anello di chiave sono scadute.One example would be when the application hasn't run for a time and all keys in the key ring are expired. Quando si verifica questa situazione, alla chiave viene assegnata una data di attivazione di {Now} senza il normale ritardo di attivazione di 2 giorni.When this happens, the key is given an activation date of { now } without the normal 2-day activation delay.

La durata predefinita della chiave è di 90 giorni, sebbene sia configurabile come nell'esempio seguente.The default key lifetime is 90 days, though this is configurable as in the following example.

services.AddDataProtection()
       // use 14-day lifetime instead of 90-day lifetime
       .SetDefaultKeyLifetime(TimeSpan.FromDays(14));

Un amministratore può anche modificare l'impostazione predefinita a livello di sistema, anche se una chiamata esplicita a SetDefaultKeyLifetime eseguirà l'override di tutti i criteri a livello di sistema.An administrator can also change the default system-wide, though an explicit call to SetDefaultKeyLifetime will override any system-wide policy. La durata predefinita della chiave non può essere inferiore a 7 giorni.The default key lifetime cannot be shorter than 7 days.

Aggiornamento automatico dell'anello chiaveAutomatic key ring refresh

Quando il sistema di protezione dei dati viene inizializzato, legge l'anello chiave dal repository sottostante e lo memorizza nella memoria.When the data protection system initializes, it reads the key ring from the underlying repository and caches it in memory. Questa cache consente alle operazioni di protezione e di rimozione della protezione di procedere senza toccare l'archivio di backup.This cache allows Protect and Unprotect operations to proceed without hitting the backing store. Il sistema verificherà automaticamente l'archivio di backup per le modifiche approssimativamente ogni 24 ore o quando la chiave predefinita corrente scade, a seconda di quale sia la prima.The system will automatically check the backing store for changes approximately every 24 hours or when the current default key expires, whichever comes first.

Avviso

Gli sviluppatori dovrebbero molto raramente usare direttamente le API di gestione delle chiavi.Developers should very rarely (if ever) need to use the key management APIs directly. Il sistema di protezione dei dati eseguirà la gestione automatica delle chiavi come descritto in precedenza.The data protection system will perform automatic key management as described above.

Il sistema di protezione dei dati espone un'interfaccia IKeyManager che può essere usata per controllare e apportare modifiche all'anello di chiave.The data protection system exposes an interface IKeyManager that can be used to inspect and make changes to the key ring. Il sistema DI DI che ha fornito l'istanza di IDataProtectionProvider può anche fornire un'istanza di IKeyManager per l'utilizzo.The DI system that provided the instance of IDataProtectionProvider can also provide an instance of IKeyManager for your consumption. In alternativa, è possibile estrarre il IKeyManager direttamente dall'IServiceProvider come nell'esempio riportato di seguito.Alternatively, you can pull the IKeyManager straight from the IServiceProvider as in the example below.

Qualsiasi operazione che modifica l'anello della chiave (creando una nuova chiave in modo esplicito o che esegue una revoca) invalida la cache in memoria.Any operation which modifies the key ring (creating a new key explicitly or performing a revocation) will invalidate the in-memory cache. La chiamata successiva a Protect o Unprotect farà sì che il sistema di protezione dei dati legga nuovamente l'anello chiave e ricrei la cache.The next call to Protect or Unprotect will cause the data protection system to reread the key ring and recreate the cache.

Nell'esempio seguente viene illustrato l'utilizzo dell'interfaccia IKeyManager per controllare e modificare l'anello chiave, inclusa la revoca delle chiavi esistenti e la generazione manuale di una nuova chiave.The sample below demonstrates using the IKeyManager interface to inspect and manipulate the key ring, including revoking existing keys and generating a new key manually.

using System;
using System.IO;
using System.Threading;
using Microsoft.AspNetCore.DataProtection;
using Microsoft.AspNetCore.DataProtection.KeyManagement;
using Microsoft.Extensions.DependencyInjection;

public class Program
{
    public static void Main(string[] args)
    {
        var serviceCollection = new ServiceCollection();
        serviceCollection.AddDataProtection()
            // point at a specific folder and use DPAPI to encrypt keys
            .PersistKeysToFileSystem(new DirectoryInfo(@"c:\temp-keys"))
            .ProtectKeysWithDpapi();
        var services = serviceCollection.BuildServiceProvider();

        // perform a protect operation to force the system to put at least
        // one key in the key ring
        services.GetDataProtector("Sample.KeyManager.v1").Protect("payload");
        Console.WriteLine("Performed a protect operation.");
        Thread.Sleep(2000);

        // get a reference to the key manager
        var keyManager = services.GetService<IKeyManager>();

        // list all keys in the key ring
        var allKeys = keyManager.GetAllKeys();
        Console.WriteLine($"The key ring contains {allKeys.Count} key(s).");
        foreach (var key in allKeys)
        {
            Console.WriteLine($"Key {key.KeyId:B}: Created = {key.CreationDate:u}, IsRevoked = {key.IsRevoked}");
        }

        // revoke all keys in the key ring
        keyManager.RevokeAllKeys(DateTimeOffset.Now, reason: "Revocation reason here.");
        Console.WriteLine("Revoked all existing keys.");

        // add a new key to the key ring with immediate activation and a 1-month expiration
        keyManager.CreateNewKey(
            activationDate: DateTimeOffset.Now,
            expirationDate: DateTimeOffset.Now.AddMonths(1));
        Console.WriteLine("Added a new key.");

        // list all keys in the key ring
        allKeys = keyManager.GetAllKeys();
        Console.WriteLine($"The key ring contains {allKeys.Count} key(s).");
        foreach (var key in allKeys)
        {
            Console.WriteLine($"Key {key.KeyId:B}: Created = {key.CreationDate:u}, IsRevoked = {key.IsRevoked}");
        }
    }
}

/*
 * SAMPLE OUTPUT
 *
 * Performed a protect operation.
 * The key ring contains 1 key(s).
 * Key {1b948618-be1f-440b-b204-64ff5a152552}: Created = 2015-03-18 22:20:49Z, IsRevoked = False
 * Revoked all existing keys.
 * Added a new key.
 * The key ring contains 2 key(s).
 * Key {1b948618-be1f-440b-b204-64ff5a152552}: Created = 2015-03-18 22:20:49Z, IsRevoked = True
 * Key {2266fc40-e2fb-48c6-8ce2-5fde6b1493f7}: Created = 2015-03-18 22:20:51Z, IsRevoked = False
 */

Se si desidera visualizzare i commenti del codice tradotti in lingue diverse dall'inglese, fatecelo sapere in questo problema di discussione GitHub.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

Archiviazione chiaviKey storage

Il sistema di protezione dei dati ha un'euristica che tenta di dedurre automaticamente un percorso di archiviazione chiavi appropriato e un meccanismo di crittografia inattivo.The data protection system has a heuristic whereby it attempts to deduce an appropriate key storage location and encryption-at-rest mechanism automatically. Il meccanismo di persistenza delle chiavi è anche configurabile dallo sviluppatore di app.The key persistence mechanism is also configurable by the app developer. I documenti seguenti illustrano le implementazioni predefinite di questi meccanismi:The following documents discuss the in-box implementations of these mechanisms: