翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# コミットメントポリシーの設定
[キーコミットメント](concepts.md#key-commitment)により、暗号化されたデータは常に同じプレーンテキストに復号化されるようになります。このセキュリティプロパティを提供するために、バージョン 1.7.*x* 以降、 はキーコミットメントを持つ新しい[アルゴリズムスイート](supported-algorithms.md) AWS Encryption SDK を使用します。データをキーコミットメントで暗号化および復号化するかどうかを決めるには、[コミットメントポリシー](concepts.md#commitment-policy)構成設定を使用します。キーコミットメントによるデータの暗号化と復号化は、[AWS Encryption SDK のベストプラクティス](best-practices.md)です。
コミットメントポリシーの設定は、 の最新の 1.*x* バージョンからバージョン 2.0.*x* 以降に移行 AWS Encryption SDK する移行プロセスの 2 番目のステップの重要な部分です。コミットメントポリシーを設定および変更したら、アプリケーションを徹底的にテストしてから本番環境にデプロイしてください。移行ガイダンスについては、「[を移行およびデプロイする方法 AWS Encryption SDK](migration-guide.md)」を参照してください。
バージョン 2.0.x 以降に、コミットメントポリシー設定には 3 つの有効な値があります。最新の 1.x バージョン (バージョン 1.7.x 以降) では、`ForbidEncryptAllowDecrypt` のみ有効です。
+ `ForbidEncryptAllowDecrypt` — はキーコミットメントで暗号化 AWS Encryption SDK できません。キーコミットメントが使用されているかどうかにかかわらず、暗号化された暗号化テキストを復号化できます。
最新の 1.x バージョンでは、これが唯一の有効な値です。これにより、キーコミットメントで復号化する準備が完全に整うまで、キーコミットメントで暗号化しないようになります。値を明示的に設定すると、バージョン 2.0.x 以降へアップグレード時にコミットメントポリシーが自動的に `require-encrypt-require-decrypt` へ変更されるのを防ぎます。その代わりに、[コミットメントポリシーを段階的に移行](#migrate-commitment-policy)できます。
+ `RequireEncryptAllowDecrypt` — AWS Encryption SDK は常にキーコミットメントで暗号化します。キーコミットメントが使用されているかどうかにかかわらず、暗号化された暗号化テキストを復号化できます。この値はバージョン 2.0.*x* で追加されました。
+ `RequireEncryptRequireDecrypt` — AWS Encryption SDK は常にキーコミットメントで暗号化および復号します。この値はバージョン 2.0.*x* で追加されました。バージョン 2.0.x 以降では、これがデフォルト値です。
最新の 1.x バージョンでは、唯一の有効なコミットメントポリシー値は `ForbidEncryptAllowDecrypt` です。バージョン 2.0.x 以降に移行した後、準備が整ったら、[コミットメントポリシーを段階的に変更](migration-guide.md)できます。すべてのメッセージがキーコミットメントで暗号化されることが確認できるまで、コミットメントポリシーを `RequireEncryptRequireDecrypt` に更新しないでください。
これらの例では、最新の 1.x バージョンおよび バージョン 2.0.x 以降でコミットメントポリシーを設定する方法を示します。この手法はプログラミング言語によって異なります。
**移行の詳細**
AWS Encryption SDK for Java、 AWS Encryption SDK for Python、および AWS Encryption CLI で、 のマスターキープロバイダーに必要な変更について説明します[AWS KMS マスターキープロバイダーの更新](migrate-mkps-v2.md)。
AWS Encryption SDK for C および については AWS Encryption SDK for JavaScript、「」のキーリングのオプションの更新について説明します[AWS KMS キーリングの更新](migrate-keyrings-v2.md)。
## コミットメントポリシーの設定方法
コミットメントポリシーの設定に使用する手法は、言語実装ごとに若干異なります。以下の例ではその方法を示します。コミットメントポリシーを変更する前に、「[移行してデプロイする方法](migration-guide.md)」で多段階のアプローチを確認してください。
------
#### [ C ]
のバージョン 1.7.*x* 以降では AWS Encryption SDK for C、 `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` 関数に置き換わります。
最新の 1.x バージョンで `aws_cryptosdk_session_new_from_keyring_2` および `aws_cryptosdk_session_new_from_cmm_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](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/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\$1 / .NET ]
`require-encrypt-require-decrypt` 値は、.NET AWS Encryption SDK 用 のすべてのバージョンのデフォルトのコミットメントポリシーです。ベストプラクティスとして明示的に設定することもできますが、必須ではありません。ただし、 AWS Encryption SDK for .NET を使用して、キーコミットメント AWS Encryption SDK なしで の別の言語実装によって暗号化された暗号文を復号する場合は、コミットメントポリシーの値を `REQUIRE_ENCRYPT_ALLOW_DECRYPT`または に変更する必要があります`FORBID_ENCRYPT_ALLOW_DECRYPT`。含まれていない場合、暗号文の復号は失敗します。
for 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()
{
{"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 ]
Encryption CLI AWS でコミットメントポリシーを設定するには、 `--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` 値になっており、キーコミットメントなしで暗号化された暗号化テキストは暗号化または復号されません。ただし、メンテナンスとトラブルシューティングに役立つように、すべての暗号化および復号呼び出しでコミットメントポリシーを明示的に設定することをお勧めします。
この例ではコミットメントポリシーを設定します。また、バージョン 1.8.*x* 以降、`--master-keys` パラメータを置き換える `--wrapping-keys` パラメータを使用します。詳細については、「[AWS KMS マスターキープロバイダーの更新](migrate-mkps-v2.md)」を参照してください。完全な例については、「[Encryption AWS CLI の例](crypto-cli-examples.md)」を参照してください。
```
\\ 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* 以降では AWS Encryption SDK for Java、 AWS Encryption SDK クライアントを表すオブジェクト`AwsCrypto`である のインスタンスにコミットメントポリシーを設定します。このコミットメントポリシーは、そのクライアントで呼び出されるすべての暗号化および復号オペレーションに適用されます。
コン`AwsCrypto()`ストラクタは の最新の 1.*x* バージョンでは廃止 AWS Encryption SDK for Java され、バージョン 2.0.*x* では削除されます。これは、新しい `Builder` クラス、`Builder.withCommitmentPolicy()` メソッド、`CommitmentPolicy` 列挙型に置き換わります。
最新 1.x バージョンでは、`Builder` クラスには `Builder.withCommitmentPolicy()` メソッドと `CommitmentPolicy.ForbidEncryptAllowDecrypt` 引数が必要です。バージョン 2.0.*x* 以降、`Builder.withCommitmentPolicy()` メソッドはオプションであり、デフォルト値は `CommitmentPolicy.RequireEncryptRequireDecrypt` です。
詳しい例については、「[SetCommitmentPolicyExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/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 encryptResult = crypto.encryptData(
masterKeyProvider,
sourcePlaintext,
encryptionContext);
byte[] ciphertext = encryptResult.getResult();
// Decrypt your ciphertext
CryptoResult decryptResult = crypto.decryptData(
masterKeyProvider,
ciphertext);
byte[] decrypted = decryptResult.getResult();
```
------
#### [ JavaScript ]
のバージョン 1.7.*x* 以降では AWS Encryption SDK for JavaScript、 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` 関数は、コミットメントポリシーを最新 1.x バージョンでのデフォルト値の `FORBID_ENCRYPT_ALLOW_DECRYPT` に設定します。`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 ]
のバージョン 1.7.*x* 以降では AWS Encryption SDK for Python、 AWS Encryption SDK クライアントを表す新しいオブジェクト`EncryptionSDKClient`である のインスタンスにコミットメントポリシーを設定します。設定したコミットメントポリシーは、クライアントのインスタンスを使用するすべての `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\$1commitment.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/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
)
```
------
#### [ Rust ]
`require-encrypt-require-decrypt` 値は、 for AWS Encryption SDK Rust のすべてのバージョンのデフォルトのコミットメントポリシーです。ベストプラクティスとして明示的に設定することもできますが、必須ではありません。ただし、 AWS Encryption SDK for Rust を使用して、キーコミットメント AWS Encryption SDK なしで の別の言語実装によって暗号化された暗号文を復号する場合は、コミットメントポリシー値を `REQUIRE_ENCRYPT_ALLOW_DECRYPT`または に変更する必要があります`FORBID_ENCRYPT_ALLOW_DECRYPT`。含まれていない場合、暗号文の復号は失敗します。
AWS Encryption SDK for Rust で、 のインスタンスにコミットメントポリシーを設定します AWS Encryption SDK。`comitment_policy` パラメータを使用して`AwsEncryptionSdkConfig`オブジェクトをインスタンス化し、設定オブジェクトを使用して AWS Encryption SDK インスタンスを作成します。次に、設定済み AWS Encryption SDK インスタンスの メソッド`Encrypt()`と `Decrypt()`メソッドを呼び出します。
この例では、コミットメントポリシーを `forbid-encrypt-allow-decrypt` に設定します。
```
// Configure the commitment policy on the AWS Encryption SDK instance
let esdk_config = AwsEncryptionSdkConfig::builder()
.commitment_policy(ForbidEncryptAllowDecrypt)
.build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create an AWS KMS client
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
// Create your encryption context
let encryption_context = HashMap::from([
("encryption".to_string(), "context".to_string()),
("is not".to_string(), "secret".to_string()),
("but adds".to_string(), "useful metadata".to_string()),
("that can help you".to_string(), "be confident that".to_string()),
("the data you are handling".to_string(), "is what you think it is".to_string()),
]);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create an AWS KMS keyring
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
// Encrypt your plaintext data
let plaintext = example_data.as_bytes();
let encryption_response = esdk_client.encrypt()
.plaintext(plaintext)
.keyring(kms_keyring.clone())
.encryption_context(encryption_context.clone())
.send()
.await?;
// Decrypt your ciphertext
let decryption_response = esdk_client.decrypt()
.ciphertext(ciphertext)
.keyring(kms_keyring)
// Provide the encryption context that was supplied to the encrypt method
.encryption_context(encryption_context)
.send()
.await?;
```
------
#### [ Go ]
```
import (
"context"
mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
)
// Instantiate the AWS Encryption SDK client
commitPolicyForbidEncryptAllowDecrypt := mpltypes.ESDKCommitmentPolicyForbidEncryptAllowDecrypt
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{CommitmentPolicy: &commitPolicyForbidEncryptAllowDecrypt})
if err != nil {
panic(err)
}
// Create an AWS KMS client
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
kmsClient := kms.NewFromConfig(cfg, func(o *kms.Options) {
o.Region = KmsKeyRegion
})
// Optional: Create an encryption context
encryptionContext := map[string]string{
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
// Instantiate the material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create an AWS KMS keyring
awsKmsKeyringInput := mpltypes.CreateAwsKmsKeyringInput{
KmsClient: kmsClient,
KmsKeyId: kmsKeyId,
}
awsKmsKeyring, err := matProv.CreateAwsKmsKeyring(context.Background(), awsKmsKeyringInput)
if err != nil {
panic(err)
}
// Encrypt your plaintext data
res, err := forbidEncryptClient.Encrypt(context.Background(), esdktypes.EncryptInput{
Plaintext: []byte(exampleText),
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
// Decrypt your ciphertext
decryptOutput, err := forbidEncryptClient.Decrypt(context.Background(), esdktypes.DecryptInput{
Ciphertext: res.Ciphertext,
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
```
------