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

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

  • Created: la chiave presente nel gruppo di chiavi, ma non è ancora stata attivata.Created - the key exists in the key ring but has not yet been activated. La chiave non deve essere utilizzata per nuove operazioni di protezione fino a quando non è trascorso tempo sufficiente che la chiave abbia avuto la possibilità di propagare a tutti i computer che utilizzano questo gruppo di chiavi.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 nel gruppo di chiavi e deve essere utilizzato per tutte le nuove operazioni di protezione.Active - the key exists in the key ring and should be used for all new Protect operations.

  • La chiave scaduta - è stata eseguita la relativa durata naturale e non deve più essere utilizzata per le nuove operazioni di protezione.Expired - the key has run its natural lifetime and should no longer be used for new Protect operations.

  • Revocato - 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.

Chiavi create, attive e scadute tutti consente di rimuovere la protezione di payload in ingresso.Created, active, and expired keys may all be used to unprotect incoming payloads. Revocati chiavi per impostazione predefinita non possono essere usate per rimuovere la protezione di payload, ma lo sviluppatore dell'applicazione possa ignorare tale 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 dal gruppo di chiavi (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 è definitivamente decifrabili e non vi è alcun override emergenza si è verificato 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 è realmente distruttivo comportamento e, di conseguenza, il sistema di protezione dati non espone alcuna API di prima classe per eseguire 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 dati legge il Keyring dal repository di backup, tenterà di individuare una chiave "default" dal gruppo di chiavi.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 dati viene scelta la chiave con la data più recente di attivazione 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. (Si è un fattore di fudge piccole destinato dello sfasamento dell'orologio server-to-server.) Se la chiave è scaduta o revocata, e se l'applicazione non ha disabilitato automatica della chiave di generazione, quindi verrà generata una nuova chiave con l'attivazione immediata per la scadenza e l'implementazione della chiave criterio riportato di seguito.(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 il sistema di protezione dei dati genera immediatamente una nuova chiave, anziché eseguire il fallback su un'altra chiave è di nuova generazione delle chiavi deve essere considerata una scadenza implicita di tutte le chiavi che sono stati attivati prima la 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 meccanismi di crittografia dei dati inattivi delle chiavi precedenti e il sistema deve preferire eseguire il fallback alla configurazione corrente.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 verifica un'eccezione.There's an exception. Se lo sviluppatore dell'applicazione ha generazione della chiave automatico disabilitato, quindi il sistema di protezione dati è necessario scegliere un elemento come 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 sceglierà la chiave non revocato con la data più recente di attivazione, usando preferibilmente delle chiavi che hanno avuto tempo per propagare ad altri computer nel 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 può finire la scelta di una chiave scaduta predefinito di conseguenza.The fallback system may end up choosing an expired default key as a result. Il sistema di fallback non sceglierà mai una chiave revocata come chiave predefinita e se il gruppo di chiavi è vuoto o è stato revocato ogni chiave quindi il sistema genererà un errore in fase di 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 della chiave e l'implementazione diKey expiration and rolling

Quando viene creata una chiave, gli ha assegnato automaticamente una data di attivazione del {ora + 2 giorni} e una data di scadenza del {ora + 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 fornisce la chiave temporale a propagarsi nel sistema.The 2-day delay before activation gives the key time to propagate through the system. Vale a dire, consente ad altre applicazioni che punta all'archivio di backup di osservare la chiave nel successivo periodo di aggiornamento automatico, ottimizzando così le probabilità che quando la chiave di ring fa diventare attivo sia stata propagata a tutte le applicazioni che potrebbe essere necessario usano.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 scade entro 2 giorni e il gruppo di chiavi non la contiene già una chiave che sarà attiva allo scadere della chiave predefinita, il sistema di protezione dati mantiene automaticamente una nuova chiave per il gruppo di chiavi.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. Questa nuova chiave ha una data di attivazione della {data di scadenza della chiave predefinita} e una data di scadenza del {ora + 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 aggiornare automaticamente le chiavi regolarmente senza interruzione del servizio.This allows the system to automatically roll keys on a regular basis with no interruption of service.

Potrebbero esserci casi in cui verrà creata una chiave con l'attivazione immediata.There might be circumstances where a key will be created with immediate activation. Un esempio sarebbe quando l'applicazione non è stata eseguita per un periodo di tempo e tutte le chiavi presenti il gruppo di chiavi sono scadute.One example would be when the application hasn't run for a time and all keys in the key ring are expired. In questo caso, la chiave ha una data di attivazione del {ora} senza il ritardo di attivazione di 2 giorni normali.When this happens, the key is given an activation date of { now } without the normal 2-day activation delay.

Durata della chiave predefinita è 90 giorni, anche se questa opzione è 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 il valore predefinito a livello di sistema, anche se una chiamata esplicita a SetDefaultKeyLifetime eseguirà l'override di qualsiasi criterio 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 di chiave non può essere inferiore a 7 giorni.The default key lifetime cannot be shorter than 7 days.

Aggiornamento automatico KeyringAutomatic key ring refresh

Quando il sistema di protezione dati viene inizializzato, legge il Keyring dall'archivio sottostante e memorizza nella cache in memoria.When the data protection system initializes, it reads the key ring from the underlying repository and caches it in memory. Questa cache consente operazioni di protezione e Unprotect procedere senza raggiungere l'archivio di backup.This cache allows Protect and Unprotect operations to proceed without hitting the backing store. Il sistema controllerà l'archivio di backup per le modifiche automaticamente circa ogni 24 ore oppure quando scade la chiave predefinita corrente, a seconda del valore raggiunto per primo.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 devono molto raramente (se applicabile) necessario usare direttamente la gestione delle chiavi API.Developers should very rarely (if ever) need to use the key management APIs directly. Come descritto in precedenza, il sistema di protezione dati eseguirà la gestione delle chiavi automatica.The data protection system will perform automatic key management as described above.

Il sistema di protezione dati espone un'interfaccia IKeyManager che può essere utilizzato per controllare e modificare il gruppo di chiavi.The data protection system exposes an interface IKeyManager that can be used to inspect and make changes to the key ring. Il sistema di inserimento delle dipendenze che ha fornito l'istanza di IDataProtectionProvider può anche fornire un'istanza di IKeyManager per la quota di utilizzo.The DI system that provided the instance of IDataProtectionProvider can also provide an instance of IKeyManager for your consumption. In alternativa, è possibile effettuare il pull il IKeyManager direttamente dal IServiceProvider come nell'esempio seguente.Alternatively, you can pull the IKeyManager straight from the IServiceProvider as in the example below.

Qualsiasi operazione che modifica il gruppo di chiavi (creazione di una nuova chiave in modo esplicito o eseguendo 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 causerà il sistema di protezione dati esegua la rilettura il gruppo di chiavi e la ricreazione della cache.The next call to Protect or Unprotect will cause the data protection system to reread the key ring and recreate the cache.

L'esempio seguente viene illustrato l'utilizzo di IKeyManager interfaccia di ispezionare e manipolare il gruppo di chiavi, tra cui revoca delle chiavi esistente e 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
 */

Archiviazione delle chiaviKey storage

Il sistema di protezione dati ha un'euristica in base al quale tenta di dedurre automaticamente un meccanismo di crittografia dei dati inattivi e il percorso di archiviazione delle chiavi appropriata.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 chiave è anche configurabile dallo sviluppatore dell'app.The key persistence mechanism is also configurable by the app developer. I documenti seguenti illustrano le implementazioni in arrivo di questi meccanismi:The following documents discuss the in-box implementations of these mechanisms: