設定您的承諾政策

從 1.7.x 版開始 適用於 C 的 AWS Encryption SDK，您可以使用 aws_cryptosdk_session_set_commitment_policy函數在加密和解密工作階段上設定承諾政策。您設定的承諾政策適用於在該工作階段上呼叫的所有加密和解密操作。

在 1.7.x 版中取代 aws_cryptosdk_session_new_from_keyring和 aws_cryptosdk_session_new_from_cmm函數，並在 2.0.x 版中移除 。這些函數會取代為 ，aws_cryptosdk_session_new_from_keyring_2而 aws_cryptosdk_session_new_from_cmm_2函數會傳回工作階段。

當您在最新的 1.x 版本aws_cryptosdk_session_new_from_cmm_2中使用 aws_cryptosdk_session_new_from_keyring_2和 時，您必須使用COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT承諾政策值呼叫 aws_cryptosdk_session_set_commitment_policy函數。在 2.0.x 版和更新版本中，呼叫此函數是選用的，它需要所有有效的值。2.0.x 版及更新版本的預設承諾政策為 COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT。

如需完整範例，請參閱 string.cpp。

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Create an AWS KMS keyring */
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);

/* Create an encrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_session *encrypt_session = aws_cryptosdk_session_new_from_keyring_2(
    alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);

aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(encrypt_session,
    COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);

...
/* Encrypt your data */

size_t plaintext_consumed_output;
aws_cryptosdk_session_process(encrypt_session,
                              ciphertext_output,
                              ciphertext_buf_sz_output,
                              ciphertext_len_output,
                              plaintext_input,
                              plaintext_len_input,
                              &plaintext_consumed_output)
...

/* Create a decrypt session with a CommitmentPolicy setting */

struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
struct aws_cryptosdk_session *decrypt_session = *aws_cryptosdk_session_new_from_keyring_2(
        alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(decrypt_session,
        COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);

/* Decrypt your ciphertext */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(decrypt_session,
                              plaintext_output,
                              plaintext_buf_sz_output,
                              plaintext_len_output,
                              ciphertext_input,
                              ciphertext_len_input,
                              &ciphertext_consumed_output)

此require-encrypt-require-decrypt值是 AWS Encryption SDK 所有版本 中的預設承諾政策NET。您可以明確將其設定為最佳實務，但並非必要。不過，如果您使用 AWS Encryption SDK for .NET 來解密 中其他語言實作加密的密碼文字， AWS Encryption SDK 而不需要金鑰承諾，則需要將承諾政策值變更為 REQUIRE_ENCRYPT_ALLOW_DECRYPT或 FORBID_ENCRYPT_ALLOW_DECRYPT。否則，嘗試解密密碼文字將會失敗。

在 AWS Encryption SDK for . 中NET，您可以在 的執行個體上設定承諾政策 AWS Encryption SDK。使用 CommitmentPolicy 參數實例化AwsEncryptionSdkConfig物件，並使用組態物件來建立 AWS Encryption SDK 執行個體。然後，呼叫已設定 AWS Encryption SDK 執行個體的 Encrypt()和 Decrypt() 方法。

此範例會將承諾政策設定為 require-encrypt-allow-decrypt。

// Instantiate the material providers
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
    CommitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);

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

var encryptionContext = new Dictionary<string, string>()
{
    {"purpose", "test"}encryptionSdk
};

var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);

// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);

// Decrypt your ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = keyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);

若要在 AWS 加密 中設定承諾政策CLI，請使用 --commitment-policy 參數。此參數會在 1.8.x 版中推出。

在最新的 1.x 版本中，當您在 --encrypt或 --decrypt命令中使用 --wrapping-keys 參數時，需要具有 forbid-encrypt-allow-decrypt值的 --commitment-policy 參數。否則， --commitment-policy 參數無效。

在 2.1.x 版及更新版本中， --commitment-policy 參數為選用，並預設為 require-encrypt-require-decrypt值，不會加密或解密任何加密的密碼文字，無需金鑰承諾。不過，我們建議您在所有加密和解密通話中明確設定承諾政策，以協助進行維護和疑難排解。

此範例會設定承諾政策。它也會使用 --wrapping-keys 參數來取代從 1.8.x 版開始的 --master-keys 參數。如需詳細資訊，請參閱 更新 AWS KMS 主金鑰提供者。如需完整範例，請參閱 示例AWS加密 CLI。

\\ To run this example, replace the fictitious key ARN with a valid value. 
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

\\ Encrypt your plaintext data - no change to algorithm suite used
$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyArn \
                     --commitment-policy forbid-encrypt-allow-decrypt \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .

\\ Decrypt your ciphertext - supports key commitment on 1.7 and later
$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$keyArn \
                     --commitment-policy forbid-encrypt-allow-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .

從 的 1.7.x 版開始 適用於 JAVA 的 AWS Encryption SDK，您可以在 執行個體上設定承諾政策AwsCrypto，即代表 AWS Encryption SDK 用戶端的物件。此承諾政策設定適用於該用戶端上呼叫的所有加密和解密操作。

AwsCrypto() 建構器在最新的 1.x 版本中取代， 適用於 JAVA 的 AWS Encryption SDK 並在 2.0.x 版本中移除。它被新Builder類別、Builder.withCommitmentPolicy()方法和CommitmentPolicy列舉類型取代。

在最新的 1.x 版本中， Builder類別需要 Builder.withCommitmentPolicy() 方法和 CommitmentPolicy.ForbidEncryptAllowDecrypt 引數。從 2.0.x 版開始，Builder.withCommitmentPolicy()方法為選用；預設值為 CommitmentPolicy.RequireEncryptRequireDecrypt。

如需完整範例，請參閱 SetCommitmentPolicyExample.java。

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
    .build();

// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);

// Encrypt your plaintext data
CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(
    masterKeyProvider,
    sourcePlaintext,
    encryptionContext);
byte[] ciphertext = encryptResult.getResult();

// Decrypt your ciphertext
CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(
        masterKeyProvider,
        ciphertext);
byte[] decrypted = decryptResult.getResult();

從 1.7.x 版開始 適用於 JavaScript 的 AWS Encryption SDK，您可以在呼叫可實例化 AWS Encryption SDK 用戶端的新buildClient函數時設定承諾政策。buildClient 函數會取得列舉值，代表您的承諾政策。它會傳回更新 encrypt和 decrypt函數，在您加密和解密時強制執行您的承諾政策。

在最新的 1.x 版本中，buildClient函數需要 CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT引數。從 2.0.x 版開始，承諾政策引數為選用，預設值為 CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT。

為此目的，Node.js 和瀏覽器的程式碼完全相同，但瀏覽器需要 陳述式來設定憑證。

下列範例使用 AWS KMS 鍵環加密資料。新buildClient函數會將承諾政策設定為 FORBID_ENCRYPT_ALLOW_DECRYPT，預設值為最新的 1.x 反之亦然。buildClient 傳回的升級 encrypt和 decrypt函數會強制執行您設定的承諾政策。

import { buildClient } from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)

// Create an AWS KMS keyring
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })

// Encrypt your plaintext data
const { ciphertext } = await encrypt(keyring, plaintext, { encryptionContext: context })

// Decrypt your ciphertext
const { decrypted, messageHeader } = await decrypt(keyring, ciphertext)

從 1.7.x 版開始 適用於 Python 的 AWS Encryption SDK，您可以在 執行個體上設定承諾政策EncryptionSDKClient，這是代表 AWS Encryption SDK 用戶端的新物件。您設定的承諾政策會套用至使用該用戶端執行個體的所有 encrypt和 decrypt呼叫。

在最新的 1.x EncryptionSDKClient 版本中，建構器需要CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT列舉的值。從 2.0.x 版開始，承諾政策引數為選用，預設值為 CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT。

此範例使用新的EncryptionSDKClient建構器，並將承諾政策設定為 1.7.x 預設值。建構器會實例化代表 的用戶端 AWS Encryption SDK。當您呼叫此用戶端上的 encrypt、 decrypt或 stream方法時，它們會強制執行您設定的承諾政策。此範例也會使用StrictAwsKmsMasterKeyProvider類別的新建構器，指定加密和解密 AWS KMS keys 的時間。

如需完整範例，請參閱 set_commitment.py 。

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)

// Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
        key_ids=[aws_kms_key]
)

# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
        source=source_plaintext,
        encryption_context=encryption_context,
        master_key_provider=aws_kms_strict_master_key_provider
)

# Decrypt your ciphertext
decrypted, decrypt_header = client.decrypt(
        source=ciphertext,
        master_key_provider=aws_kms_strict_master_key_provider
)