コミットメントポリシーの設定 - AWS Encryption SDK

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

コミットメントポリシーの設定

キーコミットメントにより、暗号化されたデータは常に同じプレーンテキストに復号化されるようになります。このセキュリティプロパティを提供するため、バージョン 1.7 以降。 x、AWS Encryption SDKはキーコミットメント付きの新しいアルゴリズムスイートを使用しています。データをキーコミットメントで暗号化および復号化するかどうかを決めるには、コミットメントポリシー構成設定を使用します。キーコミットメントによるデータの暗号化と復号化は、AWS Encryption SDK のベストプラクティスです。

コミットメントポリシーの設定は、移行プロセスの 2 番目のステップ、つまり最新の 1 からの移行の重要な部分です。 2 つのバージョン 2.0AWS Encryption SDK の x バージョン x 以降。コミットメントポリシーを設定および変更したら、アプリケーションを徹底的にテストしてから本番環境にデプロイしてください。移行ガイダンスについては、「AWS Encryption SDK を移行してデプロイする方法」を参照してください。

バージョン 2.0. x では、コミットメントポリシー設定には次の 3 つの有効な値があります。 x 以降。最新では 1. x バージョン (バージョン 1.7 以降) x)ForbidEncryptAllowDecrypt のみ有効です。

  • ForbidEncryptAllowDecrypt — AWS Encryption SDK では、キーコミットメントで暗号化することはできません。キーコミットメントが使用されているかどうかにかかわらず、暗号化された暗号化テキストを復号化できます。

    最新では 1. x では、これが唯一の有効な値です。これにより、キーコミットメントで復号化する準備が完全に整うまで、キーコミットメントで暗号化しないようになります。値を明示的に設定すると、バージョン 2.0. x へのアップグレード時にコミットメントポリシーが自動的に 20. xrequire-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 への移行後。 x 以降は、準備が整い次第、コミットメントポリシーを段階的に変更できます。すべてのメッセージがキーコミットメントで暗号化されることが確認できるまで、コミットメントポリシーを RequireEncryptRequireDecrypt に更新しないでください。

以下の例では、最新のコミットメントポリシーの設定方法を示します。 x バージョンとバージョン 2.0 x 以降。この手法はプログラミング言語によって異なります。

移行の詳細

AWS Encryption SDK for Java、AWS Encryption SDK for Python、AWS Encryption CLI の場合は、マスターキープロバイダーへの必要な変更について AWS KMS マスターキープロバイダーの更新 で説明します。

AWS Encryption SDK for C および AWS Encryption SDK for JavaScript の場合は、キーリングのオプションのアップデートについて AWS KMS キーリングの更新 で説明します。

コミットメントポリシーの設定方法

コミットメントポリシーの設定に使用する手法は、言語実装ごとに若干異なります。以下の例ではその方法を示します。コミットメントポリシーを変更する前に、「移行してデプロイする方法」で多段階のアプローチを確認してください。

C

AWS Encryption SDK for C のバージョン 1.7.x 以降は、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_2aws_cryptosdk_session_new_from_cmm_2最新のバージョンでとを使用する場合 1. x バージョンでは、aws_cryptosdk_session_set_commitment_policyCOMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPTコミットメントポリシーの値を使用して関数を呼び出す必要があります。バージョン 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 for .NET のすべてのバージョンにおけるデフォルトのコミットメントポリシーです。ベストプラクティスとして明示的に設定できますが、必須ではありません。ただし、AWS Encryption SDK for .NET を使用してAWS Encryption SDK Without key Commitment の別の言語実装で暗号化された暗号文を復号化する場合は、REQUIRE_ENCRYPT_ALLOW_DECRYPTコミットメントポリシーの値をまたはに変更する必要がありますFORBID_ENCRYPT_ALLOW_DECRYPT。さもないと、暗号化テキストを復号化することができません。

AWS Encryption SDKfor .NET では、のインスタンスにコミットメントポリシーを設定しますAWS Encryption SDK。AwsEncryptionSdkConfigCommitmentPolicyパラメータを使用してオブジェクトをインスタンス化し、AWS Encryption SDK設定オブジェクトを使用してインスタンスを作成します。次に、Encrypt()Decrypt()AWS Encryption SDK設定したインスタンスのおよびメソッドを呼び出します。

この例ではコミットメントポリシーをに設定します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 Encryption CLI でコミットメントポリシーを設定するには、--commitment-policy パラメータを使用します。このパラメータはバージョン 1.8.x で導入されました。

最新では 1. x バージョンでは、--encrypt or--wrapping-keys--decrypt コマンドでパラメータを使用する場合は、--commitment-policyforbid-encrypt-allow-decrypt値を含むパラメータが必要です。そうでない場合、--commitment-policy パラメータは無効です。

バージョン 2.1. x の場合。 x 以降、--commitment-policyパラメータはオプションであり、デフォルトで、キーコミットメントなしで暗号化された暗号化テキストは暗号化または復号化されません。require-encrypt-require-decryptただし、メンテナンスとトラブルシューティングに役立つように、すべての暗号化および復号呼び出しでコミットメントポリシーを明示的に設定することをお勧めします。

この例ではコミットメントポリシーを設定します。また、バージョン 1.8.x 以降、--master-keys パラメータを置き換える --wrapping-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 .
Java

AWS Encryption SDK for Java のバージョン 1.7.x 以降、AWS Encryption SDK クライアントを表すオブジェクトである AwsCrypto のインスタンスにコミットメントポリシーを設定します。このコミットメントポリシーは、そのクライアントで呼び出されるすべての暗号化および復号オペレーションに適用されます。

AwsCrypto()コンストラクターは最新の1では廃止されました。 の x バージョンはAWS Encryption SDK for Java、バージョン 2.0 で削除されました。 x。これは、新しい Builder クラス、Builder.withCommitmentPolicy() メソッド、CommitmentPolicy 列挙型に置き換わります。

最新では 1. x バージョンでは、BuilderBuilder.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

AWS Encryption SDK for JavaScript のバージョン 1.7.x 以降では、AWS Encryption SDK クライアントをインスタンス化する新しい buildClient 関数を呼び出すときにコミットメントポリシーを設定できます。buildClient 関数は、コミットメントポリシーを表す列挙値を取ります。更新された encrypt 関数と decrypt 関数が返されて、暗号化および復号化時にコミットメントポリシーが適用されます。

最新では 1. x バージョンの場合、buildClientCommitmentPolicy.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)
Python

AWS Encryption SDK for Python のバージョン 1.7.x 以降、AWS Encryption SDK クライアントを表す新しいオブジェクトである EncryptionSDKClient のインスタンスにコミットメントポリシーを設定します。設定したコミットメントポリシーは、クライアントのインスタンスを使用するすべての encrypt 呼び出しと decrypt 呼び出しに適用されます。

最新では 1. x バージョンでは、EncryptionSDKClientCommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPTコンストラクターには列挙値が必要です。バージョン 2.0.x 以降、コミットメントポリシー引数はオプションであり、デフォルト値は CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT です。

この例では新しい EncryptionSDKClient コンストラクタを使用して、コミットメントポリシーを 1.7.x のデフォルト値に設定します。コンストラクタは、AWS Encryption SDK を表すクライアントをインスタンス化します。このクライアントで、encryptdecryptstream のいずれかのメソッドを呼び出すと、設定したコミットメントポリシーが適用されます。この例では、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 )