ASP.NET Core でのキーの管理Key management in ASP.NET Core

データ保護システムは、自動的に保護し、ペイロードの保護を解除するために使用するマスター _ キーの有効期間を管理します。The data protection system automatically manages the lifetime of master keys used to protect and unprotect payloads. 各キーは、4 つの段階のいずれかで存在できます。Each key can exist in one of four stages:

  • 作成したキーをキー リング内に存在するが認証されていません。Created - the key exists in the key ring but has not yet been activated. キーの使用できません新しい保護操作十分な時間が経過するまで、キーがこのキー リングを使用しているすべてのマシンに反映されるまでの可能性を持っています。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.

  • アクティブな - キーはキー リング内に存在して、すべての新しい保護操作のために使用する必要があります。Active - the key exists in the key ring and should be used for all new Protect operations.

  • キーは、有効期限切れ - 自然な有効期間にわたって実行し、保護操作では使用できなくする必要があります。Expired - the key has run its natural lifetime and should no longer be used for new Protect operations.

  • 失効のキーが侵害され、新しい保護操作には使用しないでください。Revoked - the key is compromised and must not be used for new Protect operations.

受信したペイロードを解除するために、作成された、アクティブ、および有効期限が切れたキーをすべてに使用する可能性があります。Created, active, and expired keys may all be used to unprotect incoming payloads. 既定では失効したキーが、ペイロードを解除するために使用できませんが、アプリケーション開発者はこの動作をオーバーライド必要な場合。Revoked keys by default may not be used to unprotect payloads, but the application developer can override this behavior if necessary.

警告

開発者は、(例: ファイル システムから対応するファイルを削除する) をキー リングからキーを削除したくなるかもしれません。The developer might be tempted to delete a key from the key ring (e.g., by deleting the corresponding file from the file system). その時点では、キーによって保護されているすべてのデータが完全に解読し、失効したキーであるような緊急のオーバーライドはありません。At that point, all data protected by the key is permanently undecipherable, and there's no emergency override like there's with revoked keys. 、本当に破壊的な動作は、キーの削除と、その結果、データ保護システムを公開しませんファーストクラス API この操作を実行するためです。Deleting a key is truly destructive behavior, and consequently the data protection system exposes no first-class API for performing this operation.

既定のキーの選択Default key selection

データ保護システムでは、バックアップ リポジトリからキー リングを読み取り、ときに、"default"キーをキー リングから検出を試みます。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. 既定のキーは、新しい保護操作に使用されます。The default key is used for new Protect operations.

一般的なヒューリスティックは、データ保護システムは、既定のキーとして、最新のアクティブ化日付のキーを選択します。The general heuristic is that the data protection system chooses the key with the most recent activation date as the default key. (はサーバー間のクロックのずれを許可する一種の小さな) です。かどうか、アプリケーションが無効になっていない自動とキーの生成、キーが期限切れか失効してかどうかは、即時のライセンス認証ごとに新しいキーが生成されます、キーの有効期限とローリング以下のポリシー。(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.

新しいキーの生成を新しいキーの前にアクティブ化されたすべてのキーの有効期限が暗黙の型として扱うことが別のキーへのフォールバックするのではなく、データ保護システム理由がすぐに新しいキーを生成します。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. 一般的な考え方は、新しいキーが異なるアルゴリズムまたはより古いキーは、保存時の暗号化メカニズムで構成されている、システムは、フォールバックより現在の構成を優先する必要がありますです。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.

例外が発生します。There's an exception. アプリケーション開発者が自動キーの生成を無効になっている、データ保護システムは、既定のキーとして何かを選択する必要があります。If the application developer has disabled automatic key generation, then the data protection system must choose something as the default key. このフォールバックのシナリオでは、システムは、クラスター内の他のコンピューターに反映されるまでの時間があるキーに指定された基本設定、最新のライセンス認証日、失効していないキーを選択します。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. その結果、既定の有効期限が切れたキーを選択すること、フォールバック システムになります。The fallback system may end up choosing an expired default key as a result. フォールバック システムは既定のキーと失効したキーを選択しないでくださいとキー リングが空か、すべてのキーが失効している場合は、システムが初期化時にエラーが発生します。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.

キーの有効期限とロールKey expiration and rolling

キーが作成されるをアクティブ化する日の {0} 現在 + 2 日} と {現在 + 90 日間} の有効期限の日付が提供されて自動的に。When a key is created, it's automatically given an activation date of { now + 2 days } and an expiration date of { now + 90 days }. アクティブ化する前に 2 日間の遅延は、キーに反映されるまで、システム時刻を示します。The 2-day delay before activation gives the key time to propagate through the system. つまり、強まることキー リングが反映されることになるはアクティブなときにする必要があるすべてのアプリケーションを使用して、その確率で、[次へ] の自動更新期間、キーを観察するその他のアプリケーション、バッキング ストアをポイントできます。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.

2 日以内の既定のキーを有効期限が切れると、既定のキーの期限切れ時にアクティブになるキーをキー リングを持っていない場合は、新しいキーをキー リングが自動的にデータ保護システムに保持します。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. この新しいキーについては、アクティブ化する日の既定のキーの有効期限日} と {現在 + 90 日間} の有効期限の日付。This new key has an activation date of { default key's expiration date } and an expiration date of { now + 90 days }. これにより、サービスの中断することなくが定期的にキーを自動的にロールバックするシステムです。This allows the system to automatically roll keys on a regular basis with no interruption of service.

ある可能性がありますの状況で即時のライセンス認証キーが作成される場所。There might be circumstances where a key will be created with immediate activation. 1 つの例は、時間、アプリケーションが実行されていないし、キー リング内のすべてのキーが期限切れになります。One example would be when the application hasn't run for a time and all keys in the key ring are expired. この場合、キーには、通常 2 日間のアクティブ化の待機時間なしの {0} には現在} のアクティブ化日付が与えられます。When this happens, the key is given an activation date of { now } without the normal 2-day activation delay.

これが次の例のようには構成可能な既定キーの有効期間が 90 日間です。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));

明示的に呼び出す場合、管理者は、システム全体の既定値を変更もできますSetDefaultKeyLifetimeシステム全体のポリシーよりも優先されます。An administrator can also change the default system-wide, though an explicit call to SetDefaultKeyLifetime will override any system-wide policy. 既定キーの有効期間は 7 日間より短くすることはできません。The default key lifetime cannot be shorter than 7 days.

キー リングを自動更新Automatic key ring refresh

データ保護システムでは、初期化時にキー リングを基になるリポジトリから読み取るし、メモリにキャッシュします。When the data protection system initializes, it reads the key ring from the underlying repository and caches it in memory. このキャッシュは、保護と保護の解除の操作をバッキング ストアにアクセスせずに続行を許可します。This cache allows Protect and Unprotect operations to proceed without hitting the backing store. システムでは、約 24 時間ごと、または現在の既定のキーの有効期限、先に達したときに、変更のバッキング ストアは自動的にチェックします。The system will automatically check the backing store for changes approximately every 24 hours or when the current default key expires, whichever comes first.

警告

場合は、開発者が非常にまれには、キーの管理 Api を直接使用する必要があります。Developers should very rarely (if ever) need to use the key management APIs directly. データ保護システムは前述のように、自動キー管理を実行します。The data protection system will perform automatic key management as described above.

データ保護システム インターフェイスを公開するIKeyManagerを使用して、検査し、キー リングを変更することができます。The data protection system exposes an interface IKeyManager that can be used to inspect and make changes to the key ring. インスタンスを提供する DI システムIDataProtectionProviderのインスタンスを指定できますもIKeyManagerの使用量に対する。The DI system that provided the instance of IDataProtectionProvider can also provide an instance of IKeyManager for your consumption. また、プルすることができます、IKeyManagerから直接、IServiceProvider次の例のようにします。Alternatively, you can pull the IKeyManager straight from the IServiceProvider as in the example below.

すべての操作 (新しいキーを明示的に作成または失効を実行する) のキー リングを変更するには、メモリ内キャッシュが無効になります。Any operation which modifies the key ring (creating a new key explicitly or performing a revocation) will invalidate the in-memory cache. 次回の呼び出しProtectまたはUnprotectにより、データ保護システムをキー リングを読み込んで、キャッシュを再作成します。The next call to Protect or Unprotect will cause the data protection system to reread the key ring and recreate the cache.

次の例では、使用方法を示します、IKeyManagerインターフェイスを検査して取り消しの既存のキーと新しいキーを手動で生成するなど、キー リングを操作します。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
 */

キー ストレージKey storage

データ保護システムでは、ヒューリスティックを適切なキー記憶域の場所と保存時の暗号化メカニズムを自動的に推定しようとすることがあります。The data protection system has a heuristic whereby it attempts to deduce an appropriate key storage location and encryption-at-rest mechanism automatically. キーの永続化メカニズムでは、アプリ開発者によって構成も。The key persistence mechanism is also configurable by the app developer. 次のドキュメントでは、これらのメカニズムのボックスでの実装について説明します。The following documents discuss the in-box implementations of these mechanisms: