設定承諾產品原則 - AWS Encryption SDK
如何設定承諾政策

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

設定承諾產品原則

金鑰承諾可確保您的加密資料永遠解密為相同的純文字。若要提供此安全性屬性，請從 1.7 版開始。 x， AWS Encryption SDK 使用具有關鍵承諾的新算法套件。若要判斷您的資料是否已透過金鑰承諾進行加密和解密，請使用承諾產品原則組態設定。使用關鍵承諾對資料進行加密和解密是AWS Encryption SDK 最佳做法。

設定承諾產品原則是移轉程序第二個步驟的重要組成部分 — 從最新的 1 移轉。 x 版本的 AWS Encryption SDK 到 2.0 版本。 x 及更新版本。設定並變更承諾用戶原則之後，請務必先徹底測試您的應用程式，然後再將其部署到生產環境中。如需移轉指引，請參閱如何遷移和部署AWS Encryption SDK。

承諾用戶原則設定在 2.0 版中具有三個有效值。 x 及更新版本。在最新的 1. x 版本（從版本 1.7 開始。 x），只有ForbidEncryptAllowDecrypt有效。

  • ForbidEncryptAllowDecrypt— AWS Encryption SDK 無法使用密鑰承諾進行加密。它可以解密有或沒有密鑰承諾加密的密文。

    在最新的 1. x 版本，這是唯一有效的值。它可確保您在完全準備好使用金鑰承諾進行解密之前，不會使用金鑰承諾進行加密。明確設定值可防止承諾用戶原則在升級至 2.0 版require-encrypt-require-decrypt時自動變更為。 x 或更新版本。相反地，您可以分階段遷移承諾產品原則。

  • RequireEncryptAllowDecrypt— AWS Encryption SDK 始終使用關鍵承諾進行加密。它可以解密有或沒有密鑰承諾加密的密文。此值會在 2.0 版中加入。 x.

  • RequireEncryptRequireDecrypt— AWS Encryption SDK 始終使用關鍵承諾進行加密和解密。此值會在 2.0 版中加入。 x. 它是 2.0 版本中的默認值。 x 及更新版本。

在最新的 1. x 版本，唯一有效的承諾產品原則值為ForbidEncryptAllowDecrypt。在您移轉至 2.0 版之後。 x 或更新版本，您可以在準備就緒時分階段變更承諾產品原則。在您確定沒有任何沒有金鑰承諾的情況下加密的郵件RequireEncryptRequireDecrypt之前，請勿將承諾用量原則更新至。

這些範例說明如何在最新的 1 中設定承諾產品原則。 x 版本和 2.0 版本。 x 及更新版本。該技術取決於您的編程語言。

進一步了解移轉

對於 適用於 JAVA 的 AWS Encryption SDK 適用於 Python 的 AWS Encryption SDK、和 AWS 加密CLI，瞭解中對主要金鑰提供者所需的變更更新 AWS KMS 主要金鑰提供者。

對於 適用於 C 的 AWS Encryption SDK 和 適用於 JavaScript 的 AWS Encryption SDK，瞭解中正在更新AWS KMS鑰匙圈金鑰圈的選擇性更新。

如何設定承諾政策

您用來設定承諾產品原則的技術會因每種語言實作而略有不同。這些示例向您展示瞭如何做到這一點。在變更承諾政策之前，請先檢閱中的多階段方如何遷移和部署法。

C

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

aws_cryptosdk_session_new_from_keyring和aws_cryptosdk_session_new_from_cmm函數在 1.7 版中已淘汰。 x 並在 2.0 版中刪除。 x. 這些函數由aws_cryptosdk_session_new_from_keyring_2返回會話的aws_cryptosdk_session_new_from_cmm_2函數替換。

當您在最新aws_cryptosdk_session_new_from_keyring_2的 1 aws_cryptosdk_session_new_from_cmm_2 中使用和時。 x 版本中，您必須使用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)
C# / .NET

此require-encrypt-require-decrypt值是的所有版本中的預設承諾產品原則。 AWS Encryption SDK NET。您可以明確地將其設置為最佳實踐，但這不是必需的。但是，如果您使用 AWS Encryption SDK 的是. NET若要解密由其他語言實作 ( AWS Encryption SDK 不含金鑰承諾) 加密的加密文字，您必須將承諾原則值變更為或。REQUIRE_ENCRYPT_ALLOW_DECRYPT FORBID_ENCRYPT_ALLOW_DECRYPT否則，嘗試解密密文將失敗。

在對 AWS Encryption SDK 於. 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 Encryption CLI

若要在 AWS 加密中設定承諾產品原則CLI，請使用--commitment-policy參數。此參數在 1.8 版中引入。 x.

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

在 2.1 版本中。 x 及更高版本，該--commitment-policy參數是可選的，默認為該require-encrypt-require-decrypt值，如果沒有密鑰承諾，它不會加密或解密任何加密的加密文本。不過，我們建議您在所有加密和解密呼叫中明確設定承諾政策，以協助維護和疑難排解。

此範例會設定承諾產品原則。它也會使用從 --wrapping-keys 1.8 版開始取代--master-keys參數的參數。 x. 如需詳細資訊，請參閱 更新 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 .
Java

從 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();
JavaScript

從 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 范圍內。升級encrypt後的buildClient傳回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)
Python

從 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. 當您呼叫此用戶端上的encryptdecrypt、或stream方法時，它們會強制執行您設定的承諾原則。這個範例也會針對StrictAwsKmsMasterKeyProvider類別使用 new 建構函式，這個建構函式會在加密和解密 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
)