AWS Encryption SDK 適用於 .NET 範例

從執行個體化 AWS Encryption SDK 和材料提供者程式庫開始。您將使用 中的方法來 AWS Encryption SDK 加密和解密資料。您將使用物料提供者程式庫中的方法，來建立 keyring，以指定哪些金鑰可保護您的資料。

您執行個體化 AWS Encryption SDK 和材料提供者程式庫的方式，在 AWS Encryption SDK .NET 的 3.x 和 4.x 版之間有所不同。適用於 .NET 的 3.x 版和 4 AWS Encryption SDK .x 版的所有下列步驟都相同。

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

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

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

在用於使用 AWS Encryption SDK for .NET 加密的 AWS KMS keyring 中，您可以使用金鑰 ID、金鑰 ARN、別名名稱或別名 ARN 來識別 KMS 金鑰。在用於解密的 AWS KMS keyring 中，您必須使用金鑰 ARN 來識別每個 KMS 金鑰。如果您打算重複使用加密 keyring 進行解密，請為所有 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
};

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

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

加密內容是選用的，但強烈建議在 中進行密碼編譯操作 AWS Encryption SDK。您可以定義一或多個非秘密金鑰值對。

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

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

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

Encrypt() 方法傳回EncryptOutput的 具有取得加密訊息 (Ciphertext)、加密內容和演算法套件的方法。

var encryptOutput = encryptionSdk.Encrypt(encryptInput);

AWS Encryption SDK 適用於 .NET 的 中Decrypt()的方法採用EncryptOutput執行個體Ciphertext的成員。

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

var encryptedMessage = encryptOutput.Ciphertext;

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

若要指定 keyring 方法的參數，請建立輸入物件。 AWS Encryption SDK 適用於 .NET 的 中的每個 keyring 方法都有對應的輸入物件。由於此範例使用 CreateAwsKmsKeyring()方法來建立 keyring，因此會執行個體化輸入CreateAwsKmsKeyringInput類別。

在解密 keyring 中，您必須使用金鑰 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
};

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

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

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

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

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

使用 EncryptionContext 參數來驗證加密上使用的加密內容是否包含在用於解密加密文字的加密內容中。如果您使用演算法套件搭配簽署，例如預設演算法套件， 會將配對 AWS Encryption SDK 新增至加密內容，包括數位簽章。

var encryptedMessage = encryptOutput.Ciphertext;

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

var decryptOutput = encryptionSdk.Decrypt(decryptInput);

AWS Encryption SDK 適用於 .NET 的 3.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");
}

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

若要指定 keyring 方法的參數，請建立輸入物件。 AWS Encryption SDK 適用於 .NET 的 中的每個 keyring 方法都有對應的輸入物件。由於此範例使用 CreateAwsKmsDiscoveryKeyring()方法來建立 keyring，因此會執行個體化輸入CreateAwsKmsDiscoveryKeyringInput類別。

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

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

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

var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);

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

使用適用於 .NET 的 4 AWS Encryption SDK .x 版，您可以使用選用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);

AWS Encryption SDK 適用於 .NET 的 3.x 版Decrypt()方法不會在 上套用加密內容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");
}