AWS Encryption SDK 適用於 。NET - AWS Encryption SDK
安裝和建置除錯AWS KMS 鍵環必要的加密內容 CMM

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

AWS Encryption SDK 適用於 。NET

AWS Encryption SDK for .NET 是適用於以 C# 和其他 .NET 程式設計語言撰寫應用程式的開發人員的用戶端加密程式庫。Windows、macOS 和 Linux 都提供支援。

注意

AWS Encryption SDK 適用於 的 4.0.NET0 版與 AWS Encryption SDK 訊息規格不同。因此，4.0.0 版加密的訊息只能由 AWS Encryption SDK 4.0.0 版或更新版本的 解密NET。任何其他程式設計語言實作都無法解密。

for 的 4.0.1 AWS Encryption SDK 版。NET 會根據訊息規格寫入 AWS Encryption SDK 訊息，並可與其他程式設計語言實作互操作。根據預設，4.0.1 版可以讀取 4.0.0 版加密的訊息。不過，如果您不想解密 4.0.0 版加密的訊息，您可以指定 NetV4_0_0_RetryPolicy 屬性，以防止用戶端讀取這些訊息。如需詳細資訊，請參閱 上 aws-encryption-sdk-dafny儲存庫中的 v4.0.1 版本備註 GitHub。

AWS Encryption SDK for .NET 與 的一些其他程式設計語言實作不同 AWS Encryption SDK ，方式如下：

AWS Encryption SDK for .NET 包含 2.0.x 版及更新版本中引入的所有安全功能，以及 的其他語言實作 AWS Encryption SDK。不過，如果您使用 AWS Encryption SDK for .NET 解密由 2.0.x 前版本另一個語言實作所加密的資料 AWS Encryption SDK，您可能需要調整您的承諾政策 。如需詳細資訊，請參閱 如何設定您的承諾政策。

AWS Encryption SDK for .NET 是 Dafny AWS Encryption SDK 中的 產品，這是一種正式的驗證語言，您可以在其中編寫規格、實作它們的程式碼，以及測試它們的證明。結果是程式庫，可在確保功能正確性的架構中實作 的功能 AWS Encryption SDK 。

進一步了解

  • 如需顯示如何在 中設定選項的範例 AWS Encryption SDK，例如指定替代演算法套件、限制加密的資料金鑰，以及使用 AWS KMS 多區域金鑰，請參閱 設定 AWS Encryption SDK。

  • 如需使用 AWS Encryption SDK for . 進行程式設計的詳細資訊NET，請參閱 上儲存庫的aws-encryption-sdk-net aws-encryption-sdk-dafny目錄 GitHub。

主題

AWS Encryption SDK 為 安裝 。NET

AWS Encryption SDK for .NET 可作為 中的AWS.Cryptography.EncryptionSDK套件使用 NuGet。如需安裝和建置 AWS Encryption SDK 適用於 的 的詳細資訊NET，請參閱 aws-encryption-sdk-net儲存庫中的 README.md 檔案。

3.x 版

AWS Encryption SDK 適用於 的 3.x 版。NET 支援 。NET 架構 4.5.2 – 4.8 僅適用於 Windows。它支援 。NET Core 3.0+ 和 。NET 5.0 及更新版本，適用於所有支援的作業系統。

4.x 版

AWS Encryption SDK 適用於 的 4.x 版。NET 支援 。NET 6.0 和 。NET 架構 net48 及更新版本。

AWS Encryption SDK 適用於 的 。NET 需要 ， AWS SDK for .NET 即使您未使用 AWS Key Management Service （AWS KMS） 金鑰。它會與 NuGet 套件一起安裝。不過，除非您使用 AWS KMS 金鑰， AWS Encryption SDK 否則 的 。NET 不需要 AWS 帳戶、 AWS 憑證，也不需要與任何 AWS 服務的互動。如需設定 AWS 帳戶的說明，請參閱 搭配 AWS KMS 使用 AWS Encryption SDK。

AWS Encryption SDK 為 偵錯 。NET

AWS Encryption SDK 適用於 的NET 不會產生任何日誌。中適用於 AWS Encryption SDK 的 例外狀況。NET 會產生例外狀況訊息，但不會產生堆疊追蹤。

為了協助您偵錯，請務必在 中啟用記錄 AWS SDK for .NET。來自 的日誌和錯誤訊息 AWS SDK for .NET 可協助您區分 中產生的錯誤 AWS SDK for .NET 與 AWS Encryption SDK 適用於 的 中的錯誤NET。如需 AWS SDK for .NET 記錄的協助，請參閱 開發人員指南AWSLogging中的 。 AWS SDK for .NET （若要查看主題，請展開開啟以檢視 。NET 架構內容區段。）

AWS KMS 適用於 AWS Encryption SDK 的 中鍵環。NET

AWS Encryption SDK 適用於 的 中的基本 AWS KMS 金鑰環。NET只需使用一個KMS金鑰。它們也需要 AWS KMS 用戶端，讓您有機會為KMS金鑰 AWS 區域 的 設定用戶端。

若要使用一或多個包裝 AWS KMS 金鑰建立金鑰集，請使用多金鑰集。 AWS Encryption SDK for .NET 有一個特殊的多金鑰環，其使用一或多個 AWS KMS 金鑰，以及一個標準多金鑰環，其使用任何支援類型的一或多個金鑰環。有些程式設計人員偏好使用多鍵控方法來建立其所有鍵控，而 AWS Encryption SDK for 的 則NET支援該策略。

AWS Encryption SDK for .NET 為所有典型的使用案例提供基本的單一金鑰金鑰環和多金鑰環，包括 AWS KMS 多區域金鑰 。

例如，若要使用一個 AWS KMS 索引 AWS KMS 鍵建立鍵環，您可以使用 CreateAwsKmsKeyring()方法。

Version 3.x

下列範例使用 AWS Encryption SDK for 的 3.NETx 版，為包含指定金鑰的區域建立預設 AWS KMS 用戶端。

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};

// Create the keyring
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
Version 4.x

下列範例使用 AWS Encryption SDK for 的 4.NETx 版，為包含指定金鑰的區域建立 AWS KMS 用戶端。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsArn
};

// Create the keyring
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);

若要使用一或多個金鑰建立 AWS KMS 鍵環，請使用 CreateAwsKmsMultiKeyring()方法。此範例使用兩個 AWS KMS 金鑰。若要指定一個KMS金鑰，請僅使用 Generator 參數。指定其他KMS金鑰的 KmsKeyIds 參數為選用。

此鍵環的輸入不需要 AWS KMS 用戶端。相反地， 會針對金鑰環中由索引KMS鍵表示的每個區域 AWS Encryption SDK 使用預設 AWS KMS 用戶端。例如，如果 Generator 參數值所識別的KMS金鑰位於美國西部 （奧勒岡） 區域 （us-west-2）， 會為該us-west-2區域 AWS Encryption SDK 建立預設 AWS KMS 用戶端。如果您需要自訂 AWS KMS 用戶端，請使用 CreateAwsKmsKeyring()方法。

下列範例使用 AWS Encryption SDK 適用於 的 4.NETx 版，以及自訂 AWS KMS 用戶端CreateAwsKmsKeyring()的方法。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKeys = new List<string> { "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" };

// Instantiate the keyring input object
var createEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKeys
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(createEncryptKeyringInput);

AWS Encryption SDK 適用於 的 4.NETx 版支援使用對稱加密 （SYMMETRIC_DEFAULT） 或非對稱RSAKMS金鑰的 AWS KMS 鍵環。使用非對稱RSAKMS金鑰建立的 AWS KMS 鍵環只能包含一個金鑰對。

若要使用非對稱RSA AWS KMS 金鑰集加密，您不需要 kms：GenerateDataKey 或 kms：Encrypt，因為您必須在建立金鑰集時指定要用於加密的公有金鑰材料。使用此金鑰環加密時不會進行任何 AWS KMS 呼叫。若要使用非對稱RSA AWS KMS 鍵控解密，您需要 kms：Decrypt 許可。

若要建立非對稱RSA AWS KMS 鍵控，您必須ARN提供非對稱金鑰中的公有金鑰和私有RSAKMS金鑰。公有金鑰必須PEM編碼。下列範例會建立具有非對稱 AWS KMS 金鑰對的RSA鍵環。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
var publicKey = new MemoryStream(Encoding.UTF8.GetBytes(AWS KMS RSA public key));

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsRsaKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = AWS KMS RSA private key ARN,
    PublicKey = publicKey,
    EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};

// Create the keyring
var kmsRsaKeyring = mpl.CreateAwsKmsRsaKeyring(createKeyringInput);

4.x 版中的必要加密內容

使用 AWS Encryption SDK 適用於 的 4.x 版NET，您可以使用所需的加密內容CMM，在密碼編譯操作中要求加密內容。加密內容是一組非秘密金鑰值對。加密內容以密碼編譯方式綁定到加密資料，因此需要相同的加密內容才能解密 欄位。當您使用必要的加密內容 時CMM，您可以指定一或多個必要的加密內容金鑰 （必要的金鑰），這些金鑰必須包含在所有加密和解密呼叫中。

注意

只有下列版本CMM支援所需的加密內容：

  • 3.x 版 適用於 JAVA 的 AWS Encryption SDK

  • AWS Encryption SDK 適用於 的 4.x 版。NET

  • 4.x 版 適用於 Python 的 AWS Encryption SDK，與選用的加密材料提供者程式庫 （MPL） 相依性搭配使用時。

如果您使用所需的加密內容 加密資料CMM，您只能使用其中一個支援的版本解密資料。

在加密時， 會 AWS Encryption SDK 驗證所有必要的加密內容金鑰是否包含在您指定的加密內容中。會 AWS Encryption SDK 簽署您指定的加密內容。只有非必要金鑰的鍵值對才會序列化，並以純文字儲存在加密操作傳回的加密訊息標頭中。

在解密時，您必須提供加密內容，其中包含代表必要金鑰的所有金鑰值對。 AWS Encryption SDK 使用此加密內容和存放在加密訊息標頭中的鍵值對，以重建您在加密操作中指定的原始加密內容。如果 AWS Encryption SDK 無法重建原始加密內容，則解密操作會失敗。如果您提供的金鑰值對包含具有不正確值的必要金鑰，則無法解密加密的訊息。您必須提供與加密時指定的相同鍵值對。

重要

仔細考慮您在加密內容中為必要金鑰選擇哪些值。您必須能夠在解密時再次提供相同的金鑰及其對應的值。如果您無法重現所需的金鑰，則無法解密加密的訊息。

下列範例會初始化具有所需加密內容 的 AWS KMS 金鑰環CMM。

var encryptionContext = new Dictionary<string, string>()
{
    {"encryption", "context"},
    {"is not", "secret"},
    {"but adds", "useful metadata"},
    {"that can help you", "be confident that"},
    {"the data you are handling", "is what you think it is"}
};

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsKey
};
 
// Create the keyring 
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);
        
var createCMMInput = new CreateRequiredEncryptionContextCMMInput
{
    UnderlyingCMM = mpl.CreateDefaultCryptographicMaterialsManager(new CreateDefaultCryptographicMaterialsManagerInput{Keyring = kmsKeyring}),
    // If you pass in a keyring but no underlying cmm, it will result in a failure because only cmm is supported.
    RequiredEncryptionContextKeys = new List<string>(encryptionContext.Keys)
};
 
// Create the required encryption context CMM
var requiredEcCMM = mpl.CreateRequiredEncryptionContextCMM(createCMMInput);

如果您使用 AWS KMS 鍵環，適用於 AWS Encryption SDK NET的 也會使用加密內容，在鍵環對 進行的呼叫中提供其他已驗證的資料 （AAD） AWS KMS。