Gestion de clés dans ASP.NET CoreKey management in ASP.NET Core

Le système de protection de données gère automatiquement la durée de vie des clés principales utilisées pour protéger et déprotéger les charges utiles.The data protection system automatically manages the lifetime of master keys used to protect and unprotect payloads. Chaque clé peut exister dans un des quatre phases :Each key can exist in one of four stages:

  • A été créé : la clé existe dans le key ring, mais n’a pas encore été activée.Created - the key exists in the key ring but has not yet been activated. La clé ne doit pas être utilisée pour les nouvelles opérations de protéger jusqu'à ce que suffisamment de temps écoulé que la clé a eu l’occasion d’être propagées à tous les ordinateurs qui utilisent ce porte-clés.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.

  • Actif - la clé existe dans le key ring et doit être utilisé pour toutes les opérations de protéger de nouveau.Active - the key exists in the key ring and should be used for all new Protect operations.

  • Expiré - la clé a exécuté sa durée de vie naturelle et ne doit plus être utilisée pour les nouvelles opérations de protéger.Expired - the key has run its natural lifetime and should no longer be used for new Protect operations.

  • La clé révoquée - est compromise et ne doit pas être utilisée pour les nouvelles opérations de protéger.Revoked - the key is compromised and must not be used for new Protect operations.

Clés créées, actifs et expirés peuvent utilisés pour ôter la protection des charges utiles entrants.Created, active, and expired keys may all be used to unprotect incoming payloads. Clés révoqués par défaut ne peuvent pas servir pour ôter la protection des charges utiles, mais le développeur d’applications peut remplacer ce comportement si nécessaire.Revoked keys by default may not be used to unprotect payloads, but the application developer can override this behavior if necessary.

Avertissement

Le développeur peut être tenté de supprimer une clé à partir de l’anneau de clé (par exemple, en supprimant le fichier correspondant du système de fichiers).The developer might be tempted to delete a key from the key ring (e.g., by deleting the corresponding file from the file system). À ce stade, toutes les données protégées par la clé est définitivement indéchiffrables, et il n’existe aucun remplacement d’urgence, comme avec les clés révoqués.At that point, all data protected by the key is permanently undecipherable, and there's no emergency override like there's with revoked keys. Suppression d’une clé est réellement destructive comportement, et, par conséquent, le système de protection des données n’expose aucune API de première classe pour effectuer cette opération.Deleting a key is truly destructive behavior, and consequently the data protection system exposes no first-class API for performing this operation.

Sélection de la clé par défautDefault key selection

Lorsque le système de protection de données lit le key ring à partir du référentiel de sauvegarde, il tente de localiser une clé « default » à partir de l’anneau de clé.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 clé par défaut est utilisée pour les nouvelles opérations de protéger.The default key is used for new Protect operations.

L’heuristique général est que le système de protection de données choisit la clé avec la dernière date d’activation en tant que la clé par défaut.The general heuristic is that the data protection system chooses the key with the most recent activation date as the default key. (Il existe un petit manœuvre pour permettre un décalage d’horloge de serveur à serveur.) Si la clé est arrivé à expiration ou révoquée, et si l’application n’a pas désactivé automatique de génération de clés, une nouvelle clé est générée avec l’activation immédiate par le d’expiration et la restauration de clé stratégie ci-dessous.(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.

La raison pour laquelle le système de protection des données génère une nouvelle clé immédiatement au lieu de revenir à une autre clé est que la nouvelle génération de clé doit être traitée comme un délai d’expiration implicite de toutes les clés qui ont été activés avant la nouvelle clé.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’idée générale est que les nouvelles clés ont été configurés avec différents algorithmes ou de mécanismes de chiffrement au repos que les anciennes clés, et le système doit préférer le retour de la configuration actuelle.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.

Il existe une exception.There's an exception. Si le développeur d’applications a désactivé la génération automatique de la clé, puis le système de protection des données doit choisir quelque chose comme la clé par défaut.If the application developer has disabled automatic key generation, then the data protection system must choose something as the default key. Dans ce scénario de secours, le système choisira la clé non révoqué avec la dernière date d’activation, de préférence vers les clés qui ont eu le temps de se propager à d’autres machines du 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. Le système de secours peut retrouver en choisissant une clé ayant expiré par défaut en conséquence.The fallback system may end up choosing an expired default key as a result. Le système de secours ne sera jamais choisir une clé révoquée en tant que la clé par défaut, et si le key ring est vide ou de chaque clé a été révoqué le système produira une erreur lors de l’initialisation.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.

Expiration de la clé et le déploiementKey expiration and rolling

Lorsqu’une clé est créée, elle a automatiquement donné une date d’activation de {now + 2 jours} et une date d’expiration de {now + 90 jours}.When a key is created, it's automatically given an activation date of { now + 2 days } and an expiration date of { now + 90 days }. Le délai de 2 jours avant l’activation donne le temps clé pour se propager via le système.The 2-day delay before activation gives the key time to propagate through the system. Autrement dit, il permet aux autres applications pointant vers le magasin de stockage observer la clé à leur prochaine période d’actualisation automatique, optimisant ainsi les chances que lorsque la clé en anneau actif effectue deviennent propagation à toutes les applications devront peut-être l’utiliser.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.

Si la clé par défaut va expirer dans les 2 jours et si le key ring n’a pas encore une clé qui est active à l’expiration de la clé par défaut, le système de protection des données persistera automatiquement une nouvelle clé dans le key ring.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. Cette nouvelle clé a une date d’activation de {date d’expiration de la clé par défaut} et une date d’expiration de {now + 90 jours}.This new key has an activation date of { default key's expiration date } and an expiration date of { now + 90 days }. Cela permet au système déployer automatiquement des clés sur une base régulière sans aucune interruption de service.This allows the system to automatically roll keys on a regular basis with no interruption of service.

Il peut y avoir des circonstances où une clé sera créée avec l’activation immédiate.There might be circumstances where a key will be created with immediate activation. Un exemple serait lorsque l’application n’a pas exécuté pendant une période et que toutes les clés dans le key ring arrivées à expiration.One example would be when the application hasn't run for a time and all keys in the key ring are expired. Dans ce cas, la clé porte une date d’activation de {maintenant} sans le délai d’activation de 2 jours normal.When this happens, the key is given an activation date of { now } without the normal 2-day activation delay.

La durée de vie de clé par défaut est 90 jours, si cela est configurable dans l’exemple suivant.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 administrateur peut également modifier la valeur par défaut au niveau du système, même si un appel explicite à SetDefaultKeyLifetime remplacent toute stratégie de l’échelle du système.An administrator can also change the default system-wide, though an explicit call to SetDefaultKeyLifetime will override any system-wide policy. La durée de vie de clé par défaut ne peut pas être inférieure à 7 jours.The default key lifetime cannot be shorter than 7 days.

Actualisation automatique de porte-clésAutomatic key ring refresh

Quand le système de protection des données s’initialise, il lit le key ring à partir du référentiel sous-jacent et met en cache en mémoire.When the data protection system initializes, it reads the key ring from the underlying repository and caches it in memory. Ce cache autorise les opérations Protect et Unprotect continuer sans s’appuyer sur le magasin de stockage.This cache allows Protect and Unprotect operations to proceed without hitting the backing store. Le système vérifie automatiquement le magasin de stockage pour les modifications environ toutes les 24 heures ou de l’expiration de la clé par défaut actuelle, le premier prévalant.The system will automatically check the backing store for changes approximately every 24 hours or when the current default key expires, whichever comes first.

Avertissement

Les développeurs doivent très rarement (le cas échéant) à utiliser la gestion des clés API directement.Developers should very rarely (if ever) need to use the key management APIs directly. Le système de protection de données effectue la gestion automatique des clés comme décrit ci-dessus.The data protection system will perform automatic key management as described above.

Le système de protection des données expose une interface IKeyManager qui peut être utilisé pour inspecter et modifier le key ring.The data protection system exposes an interface IKeyManager that can be used to inspect and make changes to the key ring. Le système d’injection de dépendance qui a fourni l’instance de IDataProtectionProvider peut également fournir une instance de IKeyManager votre consommation.The DI system that provided the instance of IDataProtectionProvider can also provide an instance of IKeyManager for your consumption. Vous pouvez également extraire le IKeyManager directement à partir de la IServiceProvider comme dans l’exemple ci-dessous.Alternatively, you can pull the IKeyManager straight from the IServiceProvider as in the example below.

Toute opération qui modifie le key ring (création d’une nouvelle clé explicitement ou effectuer une révocation) invalide le cache en mémoire.Any operation which modifies the key ring (creating a new key explicitly or performing a revocation) will invalidate the in-memory cache. L’appel suivant à Protect ou Unprotect entraîne le système de protection des données de relecture par le key ring et de recréer le cache.The next call to Protect or Unprotect will cause the data protection system to reread the key ring and recreate the cache.

L’exemple ci-dessous montre comment utiliser le IKeyManager interface pour inspecter et manipuler le key ring, y compris révocation existant de clés et générer une nouvelle clé manuellement.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
 */

Stockage de clésKey storage

Le système de protection de données a une méthode heuristique par laquelle il tente de déduire un mécanisme de chiffrement au repos et un emplacement de stockage de clé approprié automatiquement.The data protection system has a heuristic whereby it attempts to deduce an appropriate key storage location and encryption-at-rest mechanism automatically. Le mécanisme de persistance des clés est également configurable par le développeur de l’application.The key persistence mechanism is also configurable by the app developer. Les documents suivants décrivent les implémentations de l’emploi de ces mécanismes :The following documents discuss the in-box implementations of these mechanisms: