Definindo sua política de compromisso - AWS Encryption SDK

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á.

Definindo sua política de compromisso

Compromisso principalgarante que seus dados criptografados sempre sejam decodificados no mesmo texto sem formatação. Para fornecer essa propriedade de segurança, começando na versão 1.7.x, oAWS Encryption SDKusa novospacotes de algoritmoscom um compromisso fundamental. Para determinar se seus dados são criptografados e descriptografados com o comprometimento da chave, use opolítica de compromissodefinição de configurações. Criptografar e descriptografar dados com um compromisso fundamental é umaAWS Encryption SDKprática recomendada.

Definir uma política de compromisso é uma parte importante da segunda etapa do processo de migração — migrar da última 1.xversões doAWS Encryption SDKpara as versões 2.0.xe posterior. Depois de definir e alterar sua política de compromisso, certifique-se de testar seu aplicativo minuciosamente antes de implantá-lo na produção. Para obter orientações sobre migração, consulteComo migrar e implantar oAWS Encryption SDK.

A configuração da política de compromisso tem três valores válidos nas versões 2.0.xe posterior. No último 1.xversões (começando com a versão 1.7.x), somenteForbidEncryptAllowDecrypté válido.

  • ForbidEncryptAllowDecrypt— OAWS Encryption SDKnão pode criptografar com um compromisso fundamental. Ele pode descriptografar textos cifrados criptografados com ou sem comprometimento de chave.

    No último 1.xversões, este é o único valor válido. Isso garante que você não criptografe com o comprometimento da chave até que esteja totalmente preparado para descriptografar com o comprometimento da chave. Definir o valor de forma explícita impede que sua política de compromisso mude automaticamente pararequire-encrypt-require-decryptquando você atualiza para a versão 2.0.xou mais tarde. Em vez disso, você podemigre sua política de compromissoem etapas.

  • RequireEncryptAllowDecrypt— OAWS Encryption SDKsempre criptografa com um compromisso fundamental. Ele pode descriptografar textos cifrados criptografados com ou sem comprometimento de chave. Este valor foi adicionado na versão 2.0.x.

  • RequireEncryptRequireDecrypt— OAWS Encryption SDKsempre criptografa e descriptografa com o maior comprometimento. Este valor foi adicionado na versão 2.0.x. É o valor padrão nas versões 2.0.xe posterior.

No último 1.xversões, o único valor válido da política de compromisso éForbidEncryptAllowDecrypt. Depois de migrar para a versão 2.0.xou mais tarde, você podemude sua política de compromisso em etapasquando você estiver pronto. Não atualize sua política de compromisso paraRequireEncryptRequireDecryptaté ter certeza de que não tem nenhuma mensagem criptografada sem o comprometimento da chave.

Esses exemplos mostram como definir sua política de compromisso na última versão 1.xversões e nas versões 2.0.xe posterior. A técnica depende da sua linguagem de programação.

Saiba mais sobre a migração

ParaAWS Encryption SDK for Java,AWS Encryption SDK for Python, e oAWSCLI de criptografia, saiba mais sobre as mudanças necessárias nos provedores de chaves mestras emAtualizandoAWS KMSprovedores de chaves mestras.

ParaAWS Encryption SDK for CeAWS Encryption SDK para JavaScript, saiba mais sobre uma atualização opcional dos chaveiros emAtualizandoAWS KMSchaveiros.

Como definir sua política de compromisso

A técnica que você usa para definir sua política de compromisso difere um pouco com cada implementação de linguagem. Esses exemplos mostram como fazer isso. Antes de mudar sua política de compromisso, revise a abordagem de vários estágios emComo migrar e implantar.

C

A partir da versão 1.7.xdoAWS Encryption SDK for C, use oaws_cryptosdk_session_set_commitment_policyfunçã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 nessa sessão.

Oaws_cryptosdk_session_new_from_keyringeaws_cryptosdk_session_new_from_cmmas funções estão obsoletas na versão 1.7.xe removido na versão 2.0.x. Essas funções são substituídas poraws_cryptosdk_session_new_from_keyring_2eaws_cryptosdk_session_new_from_cmm_2funções que retornam uma sessão.

Quando você usa oaws_cryptosdk_session_new_from_keyring_2eaws_cryptosdk_session_new_from_cmm_2no último 1.xversões, você deve ligar para oaws_cryptosdk_session_set_commitment_policyfunção com oCOMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPTvalor da política de compromisso. Nas versões 2.0.xe, posteriormente, chamar essa função é opcional e usa todos os valores válidos. A política de compromisso padrão para as versões 2.0.xe depois éCOMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT.

Para obter um exemplo completo, consulte 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

Orequire-encrypt-require-decryptvalue é a política de compromisso padrão em todas as versões doAWS Encryption SDKpara .NET. Você pode defini-lo explicitamente como melhores práticas, mas ele não é obrigatório. No entanto, se você estiver usando oAWS Encryption SDKpara que .NET descriptografe texto cifrado que foi criptografado por outra implementação de linguagem doAWS Encryption SDKsem compromisso fundamental, você precisa alterar o valor da política de compromisso paraREQUIRE_ENCRYPT_ALLOW_DECRYPTouFORBID_ENCRYPT_ALLOW_DECRYPT. Caso contrário, as tentativas de decifrar o texto cifrado falharão.

NoAWS Encryption SDKpara .NET, você define a política de compromisso em uma instância doAWS Encryption SDK. Instanciar umAwsEncryptionSdkConfigobjeto com umCommitmentPolicyparâmetro e use o objeto de configuração para criar oAWS Encryption SDKexemplo. Em seguida, ligue para oEncrypt()eDecrypt()métodos do configuradoAWS Encryption SDKexemplo.

Este exemplo define a política de compromisso comorequire-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

Definir uma política de compromisso noAWSCLI de criptografia, use o--commitment-policyparâmetro. Este parâmetro foi apresentado na versão 1.8.x.

No último 1.xversão, quando você usa o--wrapping-keysparâmetro em um--encryptou--decryptcomando, um--commitment-policyparâmetro com oforbid-encrypt-allow-decrypté obrigatório o valor. Caso contrário, o--commitment-policyé inválido.

Nas versões 2.1.xe depois, o--commitment-policyé opcional e assume como padrão orequire-encrypt-require-decryptvalor, que não criptografará nem descriptografará nenhum texto cifrado criptografado sem o comprometimento da chave. No entanto, recomendamos que você defina explicitamente a política de compromisso 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. Ele também usa o--wrapping-keysparâmetro que substitui o--master-keysparâmetro começando na versão 1.8.x. Para obter detalhes, consulte AtualizandoAWS KMSprovedores de chaves mestras. Para obter exemplos completos, consulteExemplos doAWSCLI de criptografia.

\\ 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.xdoAWS Encryption SDK for Java, você define a política de compromisso em sua instância deAwsCrypto, o objeto que representa oAWS Encryption SDKCliente. Essa configuração de política de compromisso se aplica a todas as operações de criptografia e descriptografia chamadas para esse cliente.

OAwsCrypto()O construtor está obsoleto na última versão 1.xversões doAWS Encryption SDK for Javae foi removido na versão 2.0.x. É substituído por um novoBuilderclasse, umBuilder.withCommitmentPolicy()método e oCommitmentPolicytipo enumerado.

No último 1.xversões, oBuilderA classe requer oBuilder.withCommitmentPolicy()e oCommitmentPolicy.ForbidEncryptAllowDecryptargumento. A partir da versão 2.0.x, oBuilder.withCommitmentPolicy()o método é opcional; o valor padrão éCommitmentPolicy.RequireEncryptRequireDecrypt.

Para obter um exemplo completo, consulteSetCommitmentPolicyExample.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

A partir da versão 1.7.xdoAWS Encryption SDK para JavaScript, você pode definir a política de compromisso ao ligar para o novobuildClientfunção que instancia umAWS Encryption SDKCliente. ObuildClientA função assume um valor enumerado que representa sua política de compromisso. Ele retorna atualizadoencryptedecryptfunções que reforçam sua política de compromisso quando você criptografa e descriptografa.

No último 1.xversões, obuildClientA função requer oCommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPTargumento. 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 do Node.js e do 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 dados com umAWS KMSchaveiro. O novobuildClientfunção define a política de compromisso paraFORBID_ENCRYPT_ALLOW_DECRYPT, o valor padrão no último 1.xversões. O atualizadoencryptedecryptfunções quebuildClientos retornos impõem 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.xdoAWS Encryption SDK for Python, você define a política de compromisso em sua instância deEncryptionSDKClient, um novo objeto que representa oAWS Encryption SDKCliente. A política de compromisso que você define se aplica a todosencryptedecryptchamadas que usam essa instância do cliente.

No último 1.xversões, oEncryptionSDKClientconstrutor requer oCommitmentPolicy.ForbidEncryptAllowDecryptvalor enumerado. A partir da versão 2.0.x, o argumento da política de compromisso é opcional e o valor padrão éCommitmentPolicy.RequireEncryptRequireDecrypt.

Este exemplo usa o novoEncryptionSDKClientconstrutor e define a política de compromisso para o 1.7.xvalor padrão. O construtor instancia um cliente que representa oAWS Encryption SDK. Quando você liga para oencrypt,decrypt, oustreammétodos neste cliente, eles impõem a política de compromisso que você define. Esse exemplo também usa o novo construtor para oStrictAwsKmsMasterKeyProviderclasse, que especificaAWS KMS keysao criptografar e descriptografar.

Para obter um exemplo completo, consulteset_commitment.py.

# Instantiate the client client = EncryptionSDKClient(CommitmentPolicy.ForbidEncryptAllowDecrypt) // 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 )