Windows および Azure での ASP.NET Core を使用した保存時のキーの暗号化

2025-06-30

データ保護システムでは、暗号化キーを保存時に暗号化する方法を決定するために、既定の検出メカニズムが採用されています。開発者は検出メカニズムをオーバーライドし、保存時にキーを暗号化する方法を手動で指定できます。

警告

明示的なキー永続化の場所を指定した場合、データ保護システムは保存時の既定のキー暗号化メカニズムを登録解除します。そのため、キーは保存されている状態ではもう暗号化されません。運用展開のためには、明示的なキー暗号化メカニズムを指定することをお勧めします。保存時の暗号化メカニズムのオプションについては、このトピックで説明します。

Azure Key Vault

詳細については、「ASP.NET Core データ保護の構成」を参照してください。

Windows DPAPI

Windows のデプロイのみに適用されます。

Windows DPAPI が使用されている場合、キーマテリアルは CryptProtectData によって暗号化されてから、ストレージへの永続化が行われます。 DPAPI は、現在のマシンの外部で読み取られることのないデータに適した暗号化メカニズムです (ただし、これらのキーを Active Directory にバックアップすることは可能です)。 DPAPI キー保存時暗号化を構成するには、ProtectKeysWithDpapi) 拡張メソッドのいずれかを呼び出します。

// Only the local user account can decrypt the keys
services.AddDataProtection()
    .ProtectKeysWithDpapi();

パラメーターを指定せずに ProtectKeysWithDpapi を呼び出した場合は、現在の Windows ユーザーアカウントのみが、永続化されたキーリングを解読できます。必要に応じて、(現在のユーザーアカウントだけでなく) マシン上のすべてのユーザーアカウントがキーリングを解読できることを指定できます。

// All user accounts on the machine can decrypt the keys
services.AddDataProtection()
    .ProtectKeysWithDpapi(protectToLocalMachine: true);

X.509 証明書

アプリが複数のマシンに分散されている場合は、共有 X.509 証明書 (.pfx 形式) をマシン間で配布し、保存キーの暗号化に証明書を使用するようにホストされているアプリを構成すると便利な場合があります。

次の例では、証明書の拇印が ProtectKeysWithCertificateに渡されます。

services.AddDataProtection()
    .ProtectKeysWithCertificate("{CERTIFICATE THUMBPRINT}");

次の例では、 X509Certificate2 が ProtectKeysWithCertificateに渡されます。

var cert = new X509Certificate2(...);

services.AddDataProtection()
    .ProtectKeysWithCertificate(cert);

証明書を作成するには、次のいずれかの方法、または他の適切なツールやオンラインサービスを使用します。

詳細については、「 .NET CLI を使用した自己署名証明書の生成」を参照してください。

.NET Framework の制限により、CAPI 秘密キーを持つ証明書のみがサポートされています。これらの制限の考えられる回避策については、下記のコンテンツを参照してください。

Windows DPAPI-NG

このメカニズムは Windows 8/Windows Server 2012 以降でのみ使用できます。

Windows 8 以降の Windows OS では、DPAPI-NG (CNG DPAPI とも呼ばれます) がサポートされています。詳細については、CNG DPAPI に関するページを参照してください。

プリンシパルは、保護記述子の規則としてエンコードされます。 ProtectKeysWithDpapiNG を呼び出す次の例では、指定された SID を持つドメインに参加しているユーザーのみがキーリングを解読できます。

public void ConfigureServices(IServiceCollection services)
{
    // Uses the descriptor rule "SID=S-1-5-21-..."
    services.AddDataProtection()
        .ProtectKeysWithDpapiNG("SID=S-1-5-21-...",
        flags: DpapiNGProtectionDescriptorFlags.None);
}

パラメーターがない、ProtectKeysWithDpapiNG のオーバーロードも存在します。この便利なメソッドを使用して、"SID={CURRENT_ACCOUNT_SID}" という規則を指定します。CURRENT_ACCOUNT_SID は、現在の Windows ユーザーアカウントの SID です。

public void ConfigureServices(IServiceCollection services)
{
    // Use the descriptor rule "SID={current account SID}"
    services.AddDataProtection()
        .ProtectKeysWithDpapiNG();
}

このシナリオでは、DPAPI-NG 操作によって使用される暗号化キーを配布する役割を担うのは AD ドメインコントローラーです。ターゲットユーザーは、ドメインに参加している任意のマシンから暗号化されたペイロードを解読できます (プロセスが ID で実行されている場合)。

Windows DPAPI-NG を使用した証明書ベースの暗号化

アプリが Windows 8.1/Windows Server 2012 R2 以降で実行されている場合は、Windows DPAPI-NG を使用して証明書ベースの暗号化を実行できます。規則記述子文字列 "CERTIFICATE=HashId:{CERTIFICATE THUMBPRINT}" を使用します。ここで、 {CERTIFICATE THUMBPRINT} プレースホルダーは証明書の 16 進エンコード SHA1 拇印です。

public void ConfigureServices(IServiceCollection services)
{
    services.AddDataProtection()
        .ProtectKeysWithDpapiNG("CERTIFICATE=HashId:{CERTIFICATE THUMBPRINT}",
            flags: DpapiNGProtectionDescriptorFlags.None);
}

キーの暗号を解除するには、このリポジトリで指し示されているすべてのアプリが Windows 8.1/Windows Server 2012 R2 以降で実行されている必要があります。

カスタムのキー暗号化

付属のメカニズムが適切でない場合には、カスタムの IXmlEncryptor を提供することで、開発者が独自のキー暗号化メカニズムを指定できます。