AWS Encryption SDK 適用於 。NET 範例

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

的 3.x 和 4.x 版的 AWS Encryption SDK 與材料提供者程式庫的實例化方式不同 AWS Encryption SDK NET。3.x 和 4.x 版的 的所有下列步驟都相同 AWS Encryption SDK NET。

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

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

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

在使用 AWS Encryption SDK for . 加密的 AWS KMS 鍵環中NET，您可以使用KMS金鑰 ID、金鑰 、別名名稱或別名 來識別金鑰ARN。 ARN在用於解密的 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
};

若要建立鍵環，請使用鍵環輸入物件呼叫鍵環方法。此範例使用 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 ，使用您定義的鍵環加密純文字。

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

var encryptOutput = encryptionSdk.Encrypt(encryptInput);

AWS Encryption SDK 適用於 的 中Decrypt()的方法。NET 會取得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());

若要指定鍵控方法的參數，請建立輸入物件。 AWS Encryption SDK 適用於 的 中的每個鍵環方法。NET 具有對應的輸入物件。由於此範例使用 CreateAwsKmsKeyring()方法建立鍵環，因此會實例化輸入的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
};

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

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

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

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

使用 AWS Encryption SDK 適用於 的 4.x 版NET，您可以使用選用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 適用於 的 3.x 版Decrypt()方法。NET 不會採用加密內容。它從加密訊息中的中繼資料取得加密內容值。不過，在傳回或使用純文字之前，最佳實務是驗證用來解密加密文字的加密內容包含您在加密時提供的加密內容。

確認用於加密的加密內容包含在用來解密加密文字的加密內容中。如果您使用具有簽署的演算法套件，例如預設演算法套件， 新增 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());

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

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

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

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

var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);

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

對於 AWS Encryption SDK 適用於 的 4.x 版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);

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