使用 ASP.NET Core 在 Windows 和 Azure 中待用金鑰加密

發行項
11/30/2023

資料保護系統預設會採用探索機制來判斷待用密碼編譯金鑰的加密方式。開發人員可以覆寫探索機制，並手動指定待用金鑰的加密方式。

警告

如果您指定明確金鑰持續性位置，資料保護系統就會取消註冊待用的預設金鑰加密機制。因此，金鑰不再在待用時加密。建議您為生產部署指定明確的金鑰加密機制。本主題說明待用加密機制選項。

Azure Key Vault

若要將金鑰儲存在 Azure Key Vault 中，請使用 Startup 類別中的 ProtectKeysWithAzureKeyVault 設定系統：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDataProtection()
        .PersistKeysToAzureBlobStorage(new Uri("<blobUriWithSasToken>"))
        .ProtectKeysWithAzureKeyVault("<keyIdentifier>", "<clientId>", "<clientSecret>");
}

如需詳細資訊，請參閱設定 ASP.NET Core Data Protection：ProtectKeysWithAzureKeyVault。

Windows DPAPI

僅適用於 Windows 部署。

使用 Windows DPAPI 時，金鑰資料會先使用 CryptProtectData 加密，再保存到儲存體。 DPAPI 是一種適當的加密機制，適用於從未在目前電腦外部讀取的資料 (雖然可以將這些金鑰備份至 Active Directory)。若要設定 DPAPI 待用金鑰加密，請呼叫下列其中 ProtectKeysWithDpapi 一個擴充方法：

public void ConfigureServices(IServiceCollection services)
{
    // Only the local user account can decrypt the keys
    services.AddDataProtection()
        .ProtectKeysWithDpapi();
}

如果沒有參數呼叫 ProtectKeysWithDpapi，則只有目前的 Windows 使用者帳戶可以解碼保存的金鑰通道。您可以選擇性地指定電腦上的任何使用者帳戶 (不只是目前的使用者帳戶) 能夠解密金鑰通道：

public void ConfigureServices(IServiceCollection services)
{
    // All user accounts on the machine can decrypt the keys
    services.AddDataProtection()
        .ProtectKeysWithDpapi(protectToLocalMachine: true);
}

X.509 憑證

如果應用程式分散在多部電腦上，將共用 X.509 憑證分散到機器上，並設定託管應用程式使用憑證進行待用金鑰加密可能很方便：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDataProtection()
        .ProtectKeysWithCertificate("3BCE558E2AD3E0E34A7743EAB5AEA2A9BD2575A0");
}

由於 .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();
}

在此案例中，AD 網域控制站負責散發 DPAPI-NG 作業所使用的加密金鑰。目標使用者可以從任何已加入網域的電腦解密加密承載 (前提是流程在其身分識別下執行)。

使用 Windows DPAPI-NG 進行憑證式加密

如果應用程式是在 Windows 8.1/Windows Server 2012 R2 或更新版本上執行，您可以使用 Windows DPAPI-NG 來執行憑證式加密。使用規則描述元字串 "CERTIFICATE=HashId:THUMBPRINT"，其中 THUMBPRINT 是憑證的十六進位編碼 SHA1 指紋：

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

指向此存放庫的任何應用程式都必須在 Windows 8.1/Windows Server 2012 R2 或更新版本上執行，才能解密金鑰。

自訂金鑰加密

如果內建機制不合適，開發人員可以藉由提供自訂 IXmlEncryptor 來指定自己的金鑰加密機制。