AWS Encryption SDK針對 .NET 範例

下列範例顯示使用 of .NET AWS Encryption SDK 進行程式設計時所使用的基本編碼模式。具體來說，您要具現化AWS Encryption SDK和材料提供者資源庫。然後，在呼叫每個方法之前，您可以具現化一個定義方法輸入的物件。這很像您在中使用的編碼模式AWS SDK for .NET。

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

如需使用 FOR .NET AWS Encryption SDK 進行程式設計的更多範例，請參閱上aws-encryption-sdk-dafny存放庫aws-encryption-sdk-net目錄中的範例 GitHub。

AWS Encryption SDK為 .NET 加密中的資料

此範例顯示加密資料的基本模式。它使用由一個AWS KMS包裝密鑰保護的數據密鑰對一個小文件進行加密。

步驟 1：實例化AWS Encryption SDK和材料提供者資源庫。

首先實例化AWS Encryption SDK和材料提供者資源庫。您將使用中的方法AWS Encryption SDK來加密和解密資料。您將使用材料提供者資料庫中的方法來建立金鑰環，以指定哪些金鑰保護您的資料。

在版本 3 之間，實例化AWS Encryption SDK和材料提供者資源庫的方式不同。 x 和 4. AWS Encryption SDK用於 .NET 的 x。以下所有步驟對於兩個版本 3 都是相同的。 x 和 4. AWS Encryption SDK用於 .NET 的 x。

Version 3.x

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

Version 4.x

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

步驟 2：為鑰匙圈創建一個輸入對象。

每個建立金鑰環的方法都有對應的輸入物件類別。例如，若要建立方CreateAwsKmsKeyring()法的輸入物件，請建立CreateAwsKmsKeyringInput類別的實體。

即使此金鑰環的輸入未指定產生器金鑰，KmsKeyId參數所指定的單一 KMS 金鑰就是產生器金鑰。它會產生並加密加密資料的資料金鑰。

此輸入物件需要 KMS 金鑰AWS 區域的AWS KMS用戶端。若要建立AWS KMS用戶端，請在中實例化AmazonKeyManagementServiceClient類別。AWS SDK for .NET呼叫沒有參數的建AmazonKeyManagementServiceClient()構函式會建立具有預設值的用戶端。

在用於為 .NET 加密的金AWS KMS鑰環中AWS Encryption SDK，您可以使用金鑰識別碼、金鑰 ARN、別名或別名 ARN 來識別 KMS 金鑰。在用於解密的金AWS KMS鑰圈中，您必須使用金鑰 ARN 來識別每個 KMS 金鑰。如果您打算重複使用加密金鑰圈進行解密，請為所有 KMS 金鑰使用金鑰 ARN 識別碼。

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
};

步驟 3：創建鑰匙圈。

若要建立金鑰圈，請使用金鑰圈輸入物件呼叫 keyring 方法。此範例使用的CreateAwsKmsKeyring()方法只需要一個 KMS 金鑰。

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

步驟 4：定義加密內容。

加密內容是選用的，但強烈建議您在AWS Encryption SDK. 您可以定義一或多個非秘密金鑰值配對。

注意

使用版本 4。 AWS Encryption SDK對於 .NET，您可以在具有必要加密內容 CMM 的所有加密請求中需要加密內容。

// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"purpose", "test"}
};

第 5 步：創建用於加密的輸入對象。

在呼叫Encrypt()方法之前，請先建立EncryptInput類別的執行個體。

string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
            
// Define the encrypt input
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    EncryptionContext = encryptionContext
};

第 6 步：加密明文。

使用的Encrypt()方法，使用您定義的金鑰環AWS Encryption SDK來加密純文字。

EncryptOutput該Encrypt() 方法返回的具有獲取加密消息（Ciphertext），加密上下文和算法套件的方法。

var encryptOutput = encryptionSdk.Encrypt(encryptInput);

步驟 7：獲取加密的消息。

.NET 中的Decrypt()方法會接受EncryptOutput執行個體的Ciphertext成員。AWS Encryption SDK

EncryptOutput物件的Ciphertext成員是加密訊息，這是一種可攜式物件，其中包含加密資料、加密資料金鑰和中繼資料 (包括加密內容)。您可以長時間安全地儲存加密的郵件，或將其提交給復原純文字的Decrypt()方法。

var encryptedMessage = encryptOutput.Ciphertext;

在 .NET 中以嚴格模式AWS Encryption SDK解密

最佳作法建議您指定用來解密資料的金鑰，這是一種稱為嚴格模式的選項。只會AWS Encryption SDK使用您在金鑰環中指定的 KMS 金鑰來解密密文。解密金鑰圈中的金鑰必須至少包含一個加密資料的金鑰。

此範例顯示了在嚴謹模式下使用 .NET 進行解密的基本模式。AWS Encryption SDK

步驟 1：具現化AWS Encryption SDK和材料提供者資源庫。

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

步驟 2：為您的鑰匙圈創建輸入對象。

若要指定金鑰圈方法的參數，請建立輸入物件。.NET 中的每個金鑰圈方AWS Encryption SDK法都有對應的輸入物件。因為這個範例會使用CreateAwsKmsKeyring()方法來建立 keyring，所以它會實體化輸入的CreateAwsKmsKeyringInput類別。

在解密金鑰圈中，您必須使用金鑰 ARN 來識別 KMS 金鑰。

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
};

步驟 3：創建鑰匙圈。

若要建立解密金鑰環，此範例會使用方CreateAwsKmsKeyring()法和金鑰環輸入物件。

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

步驟 4：創建用於解密的輸入對象。

若要建立方Decrypt()法的輸入物件，請實體化DecryptInput類別。

DecryptInput()建構函式的Ciphertext參數Ciphertext會接受Encrypt()方法傳回之EncryptOutput物件的成員。Ciphertext屬性代表加密的郵件，其中包括加密的資料、加密的資料金鑰和解密訊息所AWS Encryption SDK需的中繼資料。

使用版本 4。 x 的 AWS Encryption SDK .NET，您可以使用可選EncryptionContext參數在Decrypt()方法中指定您的加密內容。

使用EncryptionContext參數可驗證加密時使用的加密內容是否包含在用來解密密文的加密內容中。AWS Encryption SDK將配對添加到加密上下文中，包括數字簽名（如果您使用帶簽名的算法套件），例如默認算法套件。

var encryptedMessage = encryptOutput.Ciphertext;

var decryptInput = new DecryptInput
{
    Ciphertext = encryptedMessage,
    Keyring = keyring,
    EncryptionContext = encryptionContext // OPTIONAL
};

步驟 5：解密密文。

var decryptOutput = encryptionSdk.Decrypt(decryptInput);

步驟 6：驗證加密內容-版本 3。 x

版本 3 的Decrypt()方法。 .NET AWS Encryption SDK 的 x 不會採用加密內容。它會從加密郵件中的中繼資料取得加密內容值。不過，在傳回或使用純文字之前，最佳做法是確認用來解密密文的加密內容是否包含您在加密時提供的加密內容。

確認加密時使用的加密內容包含在用來解密密文的加密內容中。AWS Encryption SDK將配對添加到加密上下文中，包括數字簽名（如果您使用帶簽名的算法套件），例如默認算法套件。

// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";

if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
    || !decryptContextValue.Equals(contextValue))
{
    throw new Exception("Encryption context does not match expected values");
}

使用 .NET 中的探索金鑰圈進行AWS Encryption SDK解密

除了指定用於解密的 KMS 金鑰外，您還可以提供AWS KMS探索金鑰環，此金鑰圈是不會指定任何 KMS 金鑰的金鑰環。探索金鑰圈可讓您使用加AWS Encryption SDK密資料的任何 KMS 金鑰來解密資料，前提是呼叫者具有金鑰的解密權限。如需最佳做法，請新增探索篩選器，以限制可用於特定磁碟分割AWS 帳戶的 KMS 金鑰。

For .NET 提供了一個基本的探索金鑰圈，該金鑰圈需要AWS KMS用戶端和探索多重金鑰環，需要您指定一或多個。AWS Encryption SDK AWS 區域用戶端和區域都會限制可用來解密加密郵件的 KMS 金鑰。兩個金鑰圈的輸入物件均採用建議的探索篩選器。

下列範例顯示使用AWS KMS探索金鑰圈和探索篩選器解密資料的模式。

步驟 1：實例化AWS Encryption SDK和材料提供者資源庫。

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

步驟 2：為鑰匙圈創建輸入對象。

若要指定金鑰圈方法的參數，請建立輸入物件。.NET 中的每個金鑰圈方AWS Encryption SDK法都有對應的輸入物件。因為這個範例會使用CreateAwsKmsDiscoveryKeyring()方法來建立 keyring，所以它會實體化輸入的CreateAwsKmsDiscoveryKeyringInput類別。

List<string> accounts = new List<string> { "111122223333" };

var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = accounts,
        Partition = "aws"
    }
};

步驟 3：創建鑰匙圈。

若要建立解密金鑰環，此範例會使用方CreateAwsKmsDiscoveryKeyring()法和金鑰環輸入物件。

var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);

步驟 4：創建用於解密的輸入對象。

若要建立方Decrypt()法的輸入物件，請實體化DecryptInput類別。Ciphertext參數的值是方Encrypt()法傳回之EncryptOutput物件的Ciphertext成員。

使用版本 4。 x 的 AWS Encryption SDK .NET，您可以使用可選EncryptionContext參數在Decrypt()方法中指定您的加密內容。

使用此EncryptionContext參數可驗證加密時使用的加密內容是否包含在用來解密密文的加密內容中。AWS Encryption SDK將配對添加到加密上下文中，包括數字簽名（如果您使用帶簽名的算法套件），例如默認算法套件。

var ciphertext = encryptOutput.Ciphertext;

var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = discoveryKeyring,
    EncryptionContext = encryptionContext // OPTIONAL
    
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

步驟 5：驗證加密內容-版本 3。 x

版本 3 的Decrypt()方法。 .NET AWS Encryption SDK 的 x 不會在上接受加密上下文Decrypt()。它會從加密郵件中的中繼資料取得加密內容值。不過，在傳回或使用純文字之前，最佳做法是確認用來解密密文的加密內容是否包含您在加密時提供的加密內容。

確認用於加密的加密內容包含在用來解密密文的加密內容中。AWS Encryption SDK將配對添加到加密上下文中，包括數字簽名（如果您使用帶簽名的算法套件），例如默認算法套件。

// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";

if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
    || !decryptContextValue.Equals(contextValue))
{
    throw new Exception("Encryption context does not match expected values");
}