As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Como definir sua política de compromisso
O [confirmação de chave](concepts.md#key-commitment) assegura que seus dados criptografados sempre sejam descriptografados para o mesmo texto simples. Para fornecer essa propriedade de segurança, começando na versão 1.7. *x*, o AWS Encryption SDK usa novos [conjuntos de algoritmos](supported-algorithms.md) com comprometimento fundamental. Para determinar se seus dados são criptografados e descriptografados com confirmação de chave, use a definição de configuração da [política de compromisso](concepts.md#commitment-policy). Criptografar e descriptografar dados com [confirmação de chave](best-practices.md) é uma prática recomendada do AWS Encryption SDK .
Definir uma política de compromisso é uma parte importante da segunda etapa do processo de migração — migrar da última 1. versões *x* das AWS Encryption SDK duas versões 2.0. *x* e mais tarde. Após definir e alterar sua política de compromisso, certifique-se de testar a aplicação minuciosamente antes de implantá-la em produção. Para obter orientação sobre migração, consulte [Como migrar e implantar o AWS Encryption SDK](migration-guide.md).
A configuração da política de compromisso tem três valores válidos nas versões 2.0. *x* posteriores. Nas versões 1.*x* mais recentes (a partir da versão 1.7.*x*), somente `ForbidEncryptAllowDecrypt` é válido.
+ `ForbidEncryptAllowDecrypt`— Eles AWS Encryption SDK não podem criptografar com comprometimento chave. Ele pode descriptografar textos cifrados criptografados com ou sem confirmação de chave.
Na mais recente versão 1.*x*, esse é o único valor válido. Isso garante que você não criptografe com confirmação de chave até que esteja totalmente preparado para descriptografar com confirmação de chave. Definir o valor explicitamente impede que sua política de compromisso seja alterada automaticamente para `require-encrypt-require-decrypt` quando você atualizar para as versões 2.0.*x* ou posteriores. Em vez disso, você pode [migrar sua política de compromisso](#migrate-commitment-policy) em etapas.
+ `RequireEncryptAllowDecrypt`— AWS Encryption SDK Sempre criptografa com comprometimento fundamental. Ele pode descriptografar textos cifrados criptografados com ou sem confirmação de chave. Esse valor foi adicionado na versão 2.0.*x.*.
+ `RequireEncryptRequireDecrypt`— AWS Encryption SDK Sempre criptografa e descriptografa com comprometimento fundamental. Esse valor foi adicionado na versão 2.0.*x.*. É o valor padrão em versões 2.0.*x.* e posteriores.
Na versão 1.*x* mais recente, o único valor de política de compromisso válido é `ForbidEncryptAllowDecrypt`. Depois de migrar para a versão 2.0. *x* ou posterior, você pode [alterar sua política de compromisso em etapas](migration-guide.md) conforme estiver pronto. Não atualize sua política de compromisso `RequireEncryptRequireDecrypt` até ter certeza de que não tem nenhuma mensagem criptografada sem o confirmação de chave.
Esses exemplos mostram como definir sua política de compromisso na última versão 1.*x* e nas versões 2.0.*x* posteriores. A técnica depende da sua linguagem de programação.
**Saiba mais sobre migração**
Para AWS Encryption SDK for Java, AWS Encryption SDK for Python, e a CLI de AWS criptografia, saiba mais sobre as mudanças necessárias nos provedores de chaves mestras em. [Atualizando provedores de chaves AWS KMS mestras](migrate-mkps-v2.md)
Para AWS Encryption SDK for C e AWS Encryption SDK para JavaScript, saiba mais sobre uma atualização opcional dos chaveiros em[Atualizando AWS KMS chaveiros](migrate-keyrings-v2.md).
## Como definir sua política de compromisso
A técnica que você usa para definir sua política de compromisso difere um pouco em cada implementação de linguagem. Esses exemplos .mostram a você como fazer isso. Antes de alterar sua política de compromisso, revise a abordagem de vários estágios em [Como migrar e implantar](migration-guide.md).
------
#### [ C ]
A partir da versão 1.7. *x* do AWS Encryption SDK for C, você usa a `aws_cryptosdk_session_set_commitment_policy` função para definir a política de compromisso em suas sessões de criptografia e descriptografia. A política de compromisso que você define se aplica a todas as operações de criptografia e descriptografia chamadas na sua sessão.
As funções `aws_cryptosdk_session_new_from_keyring` e `aws_cryptosdk_session_new_from_cmm` foram descontinuadas na versão 1.7.*x* e foram removidas na versão 2.0.*x.*. Essas funções foram substituídas pelas funções `aws_cryptosdk_session_new_from_keyring_2` e `aws_cryptosdk_session_new_from_cmm_2` que retornam uma sessão.
Ao usar `aws_cryptosdk_session_new_from_keyring_2` e `aws_cryptosdk_session_new_from_cmm_2` na versão 1.*x* mais recentes, você deve chamar a função `aws_cryptosdk_session_set_commitment_policy` com o valor da política de compromisso `COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT`. Nas versões 2.0.*x* e posteriores, chamar essa função é opcional, e ela aceita todos os valores válidos. A política de compromisso padrão para as versões 2.0. *x* e posteriores é `COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Para obter um exemplo completo, consulte [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 ]
O `require-encrypt-require-decrypt` valor é a política de compromisso padrão em todas as versões do AWS Encryption SDK para.NET. Você pode definir isso explicitamente como uma prática recomendadas, mas isso não é necessário. No entanto, se você estiver usando o for.NET AWS Encryption SDK para descriptografar texto cifrado que foi criptografado por outra implementação de linguagem do AWS Encryption SDK sem compromisso de chave, você precisará alterar o valor da política de compromisso para ou. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` Caso contrário, ocorrerá uma falha na tentativa de descriptografar o texto cifrado.
No AWS Encryption SDK para.NET, você define a política de compromisso em uma instância do AWS Encryption SDK. Instancie um `AwsEncryptionSdkConfig` objeto com um `CommitmentPolicy` parâmetro e use o objeto de configuração para criar a AWS Encryption SDK instância. Em seguida, chame os `Decrypt()` métodos `Encrypt()` e da AWS Encryption SDK instância configurada.
Este exemplo define a política de compromisso como `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 ]
Para definir uma política de compromisso na CLI de AWS criptografia, use o `--commitment-policy` parâmetro. Esse parâmetro foi apresentado na versão 1.8.*x.*.
No versão 1.*x* mais recente, quando você usa o parâmetro `--wrapping-keys` em um comando `--encrypt`ou `--decrypt`, é necessário um parâmetro `--commitment-policy` com o valor `forbid-encrypt-allow-decrypt`. Caso contrário, o parâmetro `--commitment-policy` será inválido.
Nas versões 2.1.*x* e posteriores, o parâmetro `--commitment-policy` é opcional e usa como padrão o valor `require-encrypt-require-decrypt`, que não criptografará nem descriptografará nenhum texto cifrado criptografado sem confirmação de chave. No entanto, recomendamos definir a política de compromisso de forma explícita em todas as chamadas de criptografia e descriptografia, para ajudar na manutenção e na solução de problemas.
Este exemplo define a política de compromisso como . Ele também usa o parâmetro `--wrapping-keys`, que substituiu o parâmetro `--master-keys` a partir da versão 1.8.*x.*. Para obter detalhes, consulte [Atualizando provedores de chaves AWS KMS mestras](migrate-mkps-v2.md). Para obter exemplos completos, consulte [Exemplos da CLI AWS de criptografia](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 ]
A partir da versão 1.7. *x* do AWS Encryption SDK for Java, você define a política de compromisso em sua instância do `AwsCrypto` objeto que representa o AWS Encryption SDK cliente. Essa definição política de compromisso se aplica a todas as operações de criptografia e descriptografia chamadas nesse cliente.
O `AwsCrypto()` construtor está obsoleto na última versão 1. As versões *x* do AWS Encryption SDK for Java e são removidas na versão 2.0. *x.* Ele foi substituído por uma nova classe `Builder`, um método `Builder.withCommitmentPolicy()` e pelo tipo enumerado `CommitmentPolicy`.
Nas versões 1.*x* mais recentes, a classe `Builder` requer o método `Builder.withCommitmentPolicy()` e o argumento`CommitmentPolicy.ForbidEncryptAllowDecrypt`. A partir da versão 2.0.*x*, o método `Builder.withCommitmentPolicy()` é opcional. O valor padrão é `CommitmentPolicy.RequireEncryptRequireDecrypt`.
Para ver um exemplo completo, consulte [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 ]
A partir da versão 1.7. *x* do AWS Encryption SDK para JavaScript, você pode definir a política de compromisso ao chamar a nova `buildClient` função que instancia um AWS Encryption SDK cliente. A função `buildClient` assume um valor enumerado que representa sua política de compromisso. Ela retorna as funções `encrypt` e `decrypt` atualizadas, que reforçam sua política de compromisso quando você criptografa e descriptografa.
Nas versões 1.*x* mais recentes, a função `buildClient` requer o argumento `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT`. A partir da versão 2.0.*x*, o argumento da política de compromisso é opcional, e o valor padrão é `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
O código para Node.js e o navegador são idênticos para essa finalidade, exceto que o navegador precisa de uma instrução para definir as credenciais.
O exemplo a seguir criptografa os dados com um AWS KMS chaveiro. A nova função `buildClient` define a política de compromisso como`FORBID_ENCRYPT_ALLOW_DECRYPT`, o valor padrão nas versões 1.*x.* mais recentes. A funções `encrypt` e `decrypt` atualizadas retornadas por `buildClient` reforçam a política de compromisso que você definiu.
```
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 ]
A partir da versão 1.7. *x* do AWS Encryption SDK for Python, você define a política de compromisso em sua instância de`EncryptionSDKClient`, um novo objeto que representa o AWS Encryption SDK cliente. A política de compromisso que você define se aplica a todas as chamadas `encrypt` e `decrypt` que usam essa instância do cliente.
Nas versões 1.*x* mais recentes, o construtor `EncryptionSDKClient` requer o valor enumerado `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT`. A partir da versão 2.0.*x*, o argumento da política de compromisso é opcional, e o valor padrão é `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT`.
Este exemplo usa o novo construtor`EncryptionSDKClient` e define a política de compromisso como o valor padrão de 1.7.*x*. O construtor instancia um cliente que representa o AWS Encryption SDK. Quando você chama os métodos `encrypt`,`decrypt` ou `stream` desse cliente, eles aplicam a política de compromisso que você definiu. Esse exemplo também usa o novo construtor da `StrictAwsKmsMasterKeyProvider` classe, que especifica AWS KMS keys quando criptografar e descriptografar.
Para obter um exemplo completo, consulte [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 ]
O `require-encrypt-require-decrypt` valor é a política de compromisso padrão em todas as versões do AWS Encryption SDK for Rust. Você pode definir isso explicitamente como uma prática recomendadas, mas isso não é necessário. No entanto, se você estiver usando o for Rust AWS Encryption SDK para descriptografar texto cifrado que foi criptografado por outra implementação de linguagem do AWS Encryption SDK sem compromisso de chave, você precisará alterar o valor da política de compromisso para ou. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` Caso contrário, ocorrerá uma falha na tentativa de descriptografar o texto cifrado.
No AWS Encryption SDK for Rust, você define a política de compromisso em uma instância do AWS Encryption SDK. Instancie um `AwsEncryptionSdkConfig` objeto com um `comitment_policy` parâmetro e use o objeto de configuração para criar a AWS Encryption SDK instância. Em seguida, chame os `Decrypt()` métodos `Encrypt()` e da AWS Encryption SDK instância configurada.
Este exemplo define a política de compromisso como `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)
}
```
------