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á.
# AWS Encryption SDK for C
O AWS Encryption SDK for C fornece uma biblioteca de criptografia do lado do cliente para desenvolvedores que estão escrevendo aplicativos em C. Ela também serve como base para implementações de linguagens de programação de nível superior. AWS Encryption SDK
Como todas as implementações do AWS Encryption SDK, o AWS Encryption SDK for C oferece recursos avançados de proteção de dados. Os recursos incluem [criptografia de envelope](concepts.md#envelope-encryption), AAD (additional authenticated data - dados autenticados adicionais) e [pacotes de algoritmos](concepts.md#crypto-algorithm) de chave simétrica segura e autenticada, como o AES-GCM de 256 bits com derivação de chave e assinatura.
Todas as implementações específicas de linguagem do AWS Encryption SDK são totalmente interoperáveis. [Por exemplo, você pode criptografar dados com o AWS Encryption SDK for C e descriptografá-los com [qualquer implementação de linguagem compatível](programming-languages.md), incluindo a CLI de criptografia.AWS](crypto-cli.md)
AWS Encryption SDK for C Isso requer que AWS SDK para C\$1\$1 o interaja com AWS Key Management Service (AWS KMS). Você precisa usá-lo somente se estiver usando o [AWS KMS token de autenticação](use-kms-keyring.md) opcional. No entanto, AWS Encryption SDK não requer AWS KMS nenhum outro AWS serviço.
**Saiba mais**
+ Para obter detalhes sobre a programação com o AWS Encryption SDK for C, consulte os [exemplos em C](c-examples.md), os [exemplos](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) no [aws-encryption-sdk-c repositório](https://github.com/aws/aws-encryption-sdk-c/) em GitHub e a [documentação da AWS Encryption SDK for C API](https://aws.github.io/aws-encryption-sdk-c/html/).
+ Para uma discussão sobre como usar o para criptografar dados AWS Encryption SDK for C para que você possa descriptografá-los em vários Regiões da AWS, consulte [Como descriptografar textos cifrados em várias regiões com o em C](https://aws.amazon.com/blogs/security/how-to-decrypt-ciphertexts-multiple-regions-aws-encryption-sdk-in-c/) no Blog de Segurança. AWS Encryption SDK AWS
**Topics**
+ [Instalar](c-language-installation.md)
+ [Uso do C SDK](c-language-using.md)
+ [Exemplos](c-examples.md)
# Instalando o AWS Encryption SDK for C
Instale a versão mais recente do AWS Encryption SDK for C.
**nota**
Todas as versões AWS Encryption SDK for C anteriores à 2.0.0 estão em [end-of-supportfase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle).
Você pode atualizar com segurança a partir da versão 2.0.*x* e posteriores até a versão mais recente do AWS Encryption SDK for C sem realizar alterações no código ou nos dados. No entanto, os [novos atributos de segurança](about-versions.md#version-2) introduzidos na versão 2.0.*x* não são compatíveis com versões anteriores. Para atualizar a partir de versões anteriores à 1.7.*x* até a versão 2.0. *x* e posteriores, primeiro será necessário atualizar para a versão 1.*x* mais recente do AWS Encryption SDK for C. Para obter detalhes, consulte [Migrando seu AWS Encryption SDK](migration.md).
Você pode encontrar instruções detalhadas para instalar e criar o AWS Encryption SDK for C no [arquivo README](https://github.com/aws/aws-encryption-sdk-c/#readme) do [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)repositório. Ele inclui instruções para criar nas plataformas Amazon Linux, Ubuntu, macOS e Windows.
Antes de começar, decida se deseja usar [tokens de autenticação do AWS KMS](use-kms-keyring.md) no AWS Encryption SDK. Se você usa um AWS KMS chaveiro, você precisa instalar o. AWS SDK para C\$1\$1 O AWS SDK é necessário para interagir com [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS). Quando você AWS Encryption SDK usa AWS KMS chaveiros, eles usam AWS KMS para gerar e proteger as chaves de criptografia que protegem seus dados.
Você não precisa instalar o AWS SDK para C\$1\$1 se estiver usando outro tipo de chaveiro, como um chaveiro AES bruto, um chaveiro RSA bruto ou um chaveiro múltiplo que não inclua um chaveiro. AWS KMS No entanto, ao usar um tipo de token de autenticação bruto, você precisa gerar e proteger suas próprias chaves de encapsulamento brutas.
Se você estiver com problemas com a instalação, [registre um problema](https://github.com/aws/aws-encryption-sdk-c/issues) no repositório do `aws-encryption-sdk-c` ou use os links de feedback desta página.
# Usando o AWS Encryption SDK for C
Este tópico explica alguns dos recursos do AWS Encryption SDK for C que não são suportados em outras implementações de linguagem de programação.
Esses exemplos mostram como usar a versão 2.0.[*x*](about-versions.md) e versões posteriores do AWS Encryption SDK for C. Para exemplos que usam versões anteriores, encontre sua versão na lista de [lançamentos](https://github.com/aws/aws-encryption-sdk-c/releases) do [aws-encryption-sdk-c repositório](https://github.com/aws/aws-encryption-sdk-c/) em. GitHub
Para obter detalhes sobre a programação com o AWS Encryption SDK for C, consulte os [exemplos em C](c-examples.md), os [exemplos](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) no [aws-encryption-sdk-c repositório](https://github.com/aws/aws-encryption-sdk-c/) em GitHub e a [documentação da AWS Encryption SDK for C API](https://aws.github.io/aws-encryption-sdk-c/html/).
Consulte também: [Tokens de autenticação](choose-keyring.md)
**Topics**
+ [Padrões para criptografar e descriptografar dados](#c-language-using-pattern)
+ [Contagem de referências](#c-language-using-release)
## Padrões para criptografar e descriptografar dados
Ao usar o AWS Encryption SDK for C, você segue um padrão semelhante a este: cria um [chaveiro](concepts.md#keyring), cria um [CMM](concepts.md#crypt-materials-manager) que usa o chaveiro, cria uma sessão que usa o CMM (e o chaveiro) e, em seguida, processa a sessão.
1. Carregar sequências de erro.
Chame o método `aws_cryptosdk_load_error_strings()` no código C\$1\$1 ou C\$1\$1. Ele carrega informações de erro que são muito úteis para depuração.
Você só precisa chamá-lo uma vez, como no método `main`.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
2. Crie um token de autenticação.
Configure o [token de autenticação](concepts.md#keyring) com as chaves de empacotamento que você deseja usar para criptografar suas chaves de dados. Este exemplo usa um [AWS KMS chaveiro](use-kms-keyring.md) com um AWS KMS key, mas você pode usar qualquer tipo de chaveiro em seu lugar.
Para identificar um AWS KMS key em um chaveiro de criptografia no AWS Encryption SDK for C, especifique o ARN da [chave ou o ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) do [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn). Em um token de autenticação de descriptografia, é necessário usar um ARN de chave. Para obter detalhes, consulte [Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id).
```
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);
```
3. Crie uma sessão.
No AWS Encryption SDK for C, você usa uma *sessão* para criptografar uma única mensagem de texto simples ou descriptografar uma única mensagem de texto cifrado, independentemente do tamanho. A sessão mantém o estado da mensagem durante todo o processamento.
Configure a sessão com um alocador, um token de autenticação e um modo: `AWS_CRYPTOSDK_ENCRYPT` ou `AWS_CRYPTOSDK_DECRYPT`. Se você precisar alterar o modo da sessão, use o método `aws_cryptosdk_session_reset`.
Quando você cria uma sessão com um chaveiro, ele cria AWS Encryption SDK for C automaticamente um gerenciador de materiais criptográficos (CMM) padrão para você. Você não precisa criar, manter ou destruir esse objeto.
Por exemplo, a sessão a seguir usa o alocador e o token de autenticação definido na etapa 1. Ao criptografar dados, o modo é o `AWS_CRYPTOSDK_ENCRYPT`.
```
struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
```
4. Criptografe ou descriptografe os dados.
Para processar os dados na sessão, use o método `aws_cryptosdk_session_process`. Se o buffer de entrada for grande o suficiente para conter todo o texto simples, e o buffer de saída for grande o suficiente para conter todo o texto cifrado, você pode chamar `aws_cryptosdk_session_process_full`. No entanto, se precisar lidar com dados de streaming, você poderá chamar `aws_cryptosdk_session_process` em um loop. Para obter um exemplo, consulte o [file\$1streaming.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/file_streaming.cpp) . O `aws_cryptosdk_session_process_full` é introduzido nas AWS Encryption SDK versões 1.9. *x* e 2.2. *x.*
Quando a sessão é configurada para criptografar dados, os campos em texto simples descrevem a entrada e os campos de texto cifrado descrevem a saída. O campo `plaintext` contém a mensagem que você deseja criptografar, e o campo `ciphertext` obtém a [mensagem criptografada](message-format.md) retornada pelo método de criptografia.
```
/* Encrypting data */
aws_cryptosdk_session_process_full(session,
ciphertext,
ciphertext_buffer_size,
&ciphertext_length,
plaintext,
plaintext_length)
```
Quando a sessão é configurada para descriptografar dados, os campos em texto cifrado descrevem a entrada e os campos em texto cifrado descrevem a saída. O campo `ciphertext` contém a [mensagem criptografada](message-format.md) retornada pelo método de criptografia, e o campo `plaintext` obtém a mensagem em texto simples retornada pelo método de descriptografia.
Para descriptografar os dados, chame o método `aws_cryptosdk_session_process_full`.
```
/* Decrypting data */
aws_cryptosdk_session_process_full(session,
plaintext,
plaintext_buffer_size,
&plaintext_length,
ciphertext,
ciphertext_length)
```
## Contagem de referências
Para evitar vazamentos de memória, libere as referências a todos os objetos que você criou ao concluir. Caso contrário, ocorrerão vazamentos de memória. O SDK fornece métodos para facilitar essa tarefa.
Sempre que você criar um objeto pai com um dos seguintes objetos filho, o objeto pai obtém e mantém uma referência ao objeto filho, da seguinte forma:
+ Um [token de autenticação](concepts.md#keyring), como criar uma sessão com um token de autenticação
+ Um [ gerenciador de materiais criptográficos](concepts.md#crypt-materials-manager) (CMM) padrão, como criar uma sessão ou um CMM personalizado com um CMM padrão
+ Um [cache de chaves de dados](data-key-caching.md), como criar um CMM de armazenamento em cache com um token de autenticação e um cache
A menos que precise de uma referência independente ao objeto filho, você pode liberar a referência ao objeto filho assim que criar o objeto pai. A referência restante ao objeto filho é liberada quando o objeto pai é destruído. Esse padrão garante que você mantenha a referência a cada objeto somente pelo tempo necessário e não ocorra vazamento de memória causado por referências não liberadas.
Você só é responsável por liberar referências aos objetos filho que cria explicitamente. Você não é responsável por gerenciar referências a objetos criados pelo SDK para você. Se o SDK criar um objeto, como o CMM padrão que o método `aws_cryptosdk_caching_cmm_new_from_keyring` adiciona a uma sessão, o SDK gerenciará a criação e a destruição do objeto e suas referências.
No exemplo a seguir, ao criar uma sessão com um [token de autenticação](concepts.md#keyring), a sessão obtém uma referência ao token de autenticação e mantém essa referência até que a sessão seja destruída. Se você não precisar manter uma referência adicional ao token de autenticação, poderá usar o método `aws_cryptosdk_keyring_release` para liberar o objeto do token de autenticação assim que a sessão for criada. Esse método diminui a contagem de referências para o token de autenticação. A referência da sessão ao token de autenticação é liberada quando você chama `aws_cryptosdk_session_destroy` para destruir a sessão.
```
// The session gets a reference to the keyring.
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, keyring);
// After you create a session with a keyring, release the reference to the keyring object.
aws_cryptosdk_keyring_release(keyring);
```
Para tarefas mais complexas, como reutilizar um token de autenticação para várias sessões ou especificar um pacote de algoritmos em um CMM, talvez seja necessário manter uma referência independente ao objeto. Se assim for, não chame os métodos de liberação imediatamente. Em vez disso, libere as referências quando você não estiver mais usando os objetos, além de destruir a sessão.
Essa técnica de contagem de referência também funciona quando você está usando alternativas CMMs, como o CMM de cache para armazenamento em cache de [chaves de dados](data-key-caching.md). Ao criar um CMM de armazenamento em cache de um cache e de um token de autenticação, o CMM de armazenamento em cache obtém uma referência aos dois objetos. A menos que precise delas para outra tarefa, você pode liberar suas referências independentes para cache e o token de autenticação assim que o CMM de armazenamento em cache for criado. Depois, ao criar uma sessão com o CMM de armazenamento em cache, você pode liberar sua referência para o CMM de armazenamento em cache.
Observe que você só é responsável por liberar referências a objetos que cria explicitamente. Os objetos criados pelos métodos para você, como o CMM padrão que é subjacente ao CMM de armazenamento em cache, são gerenciados pelo método.
```
/ Create the caching CMM from a cache and a keyring.
struct aws_cryptosdk_cmm *caching_cmm = aws_cryptosdk_caching_cmm_new_from_keyring(allocator, cache, kms_keyring, NULL, 60, AWS_TIMESTAMP_SECS);
// Release your references to the cache and the keyring.
aws_cryptosdk_materials_cache_release(cache);
aws_cryptosdk_keyring_release(kms_keyring);
// Create a session with the caching CMM.
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm);
// Release your references to the caching CMM.
aws_cryptosdk_cmm_release(caching_cmm);
// ...
aws_cryptosdk_session_destroy(session);
```
# AWS Encryption SDK for C exemplos
Os exemplos a seguir mostram como usar o para AWS Encryption SDK for C criptografar e descriptografar dados.
Esses exemplos mostram como usar as versões 2.0.*x* e posteriores do AWS Encryption SDK for C. Para exemplos que usam versões anteriores, encontre sua versão na lista de [lançamentos](https://github.com/aws/aws-encryption-sdk-c/releases) do [aws-encryption-sdk-c repositório](https://github.com/aws/aws-encryption-sdk-c/) em. GitHub
Quando você instala e constrói o AWS Encryption SDK for C, o código-fonte desses e de outros exemplos é incluído no `examples` subdiretório e eles são compilados e incorporados ao `build` diretório. Você também pode encontrá-los no subdiretório de [exemplos](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) do [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)repositório em. GitHub
**Topics**
+ [Criptografar e descriptografar strings](#c-example-strings)
## Criptografar e descriptografar strings
O exemplo a seguir mostra como usar o para AWS Encryption SDK for C criptografar e descriptografar uma string.
Este exemplo apresenta o [AWS KMS chaveiro](use-kms-keyring.md), um tipo de chaveiro que usa um AWS KMS key in [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/) para gerar e criptografar chaves de dados. O exemplo inclui código escrito em C\$1\$1. AWS Encryption SDK for C Isso exige que AWS SDK para C\$1\$1 você ligue AWS KMS ao usar AWS KMS chaveiros. Se você estiver usando um chaveiro que não interage com AWS KMS, como um chaveiro AES bruto, um chaveiro RSA bruto ou um chaveiro múltiplo que não inclui um AWS KMS chaveiro, isso não é necessário. AWS SDK para C\$1\$1
Para obter ajuda na criação de um AWS KMS key, consulte [Criação de chaves](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) no *Guia do AWS Key Management Service desenvolvedor*. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulte[Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id).
**Consulte o exemplo de código completo**: [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp)
**Topics**
+ [Criptografar uma string](#c-example-string-encrypt)
+ [Descriptografar uma string](#c-example-string-decrypt)
### Criptografar uma string
A primeira parte deste exemplo usa um AWS KMS chaveiro com um AWS KMS key para criptografar uma string de texto sem formatação.
Etapa 1. Carregar sequências de erro.
Chame o método `aws_cryptosdk_load_error_strings()` no código C\$1\$1 ou C\$1\$1. Ele carrega informações de erro que são muito úteis para depuração.
Você só precisa chamá-lo uma vez, como no método `main`.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
Etapa 2: estruturar o token de autenticação.
Crie um AWS KMS chaveiro para criptografia. O chaveiro neste exemplo é configurado com um AWS KMS key, mas você pode configurar um AWS KMS chaveiro com vários AWS KMS keys, inclusive AWS KMS keys em contas diferentes Regiões da AWS e diferentes.
Para identificar um AWS KMS key em um chaveiro de criptografia no AWS Encryption SDK for C, especifique o ARN da [chave ou o ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) do [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn). Em um token de autenticação de descriptografia, é necessário usar um ARN de chave. Para obter detalhes, consulte [Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id).
[Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id)
Ao criar um chaveiro com vários AWS KMS keys, você especifica o AWS KMS key usado para gerar e criptografar a chave de dados de texto simples e uma matriz opcional de outros AWS KMS keys que criptografam a mesma chave de dados de texto sem formatação. Nesse caso, você especifica somente o gerador AWS KMS key.
Antes de executar esse código, substitua o ARN da chave de exemplo por um válido.
```
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);
```
Etapa 3: Criar uma sessão.
Crie uma sessão usando o alocador, um enumerador de modo e o token de autenticação.
Cada sessão requer um modo: `AWS_CRYPTOSDK_ENCRYPT` para criptografar ou `AWS_CRYPTOSDK_DECRYPT` para descriptografar. Para alterar o modo de uma sessão existente, use o método `aws_cryptosdk_session_reset`.
Depois de criar um sessão com o token de autenticação, você poderá liberar sua referência ao token de autenticação usando o método fornecido pelo SDK. A sessão retém uma referência ao objeto token de autenticação durante sua vida útil. Referências ao token de autenticação e aos objetos de sessão são liberadas quando você destrói a sessão. Essa técnica de [contagem de referência](c-language-using.md#c-language-using-release) ajuda a evitar vazamentos de memória e a evitar que os objetos sejam liberados enquanto estão em uso.
```
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
```
Etapa 4: Definir o contexto de criptografia.
Um [contexto de criptografia](concepts.md#encryption-context) são dados autenticados adicionais arbitrários e que não são secretos. Quando você fornece um contexto de criptografia na criptografia, ele vincula AWS Encryption SDK criptograficamente o contexto de criptografia ao texto cifrado, de forma que o mesmo contexto de criptografia seja necessário para descriptografar os dados. O uso de um contexto de criptografia é opcional, mas o recomendamos como uma melhor prática.
Primeiro, crie uma tabela de hash que inclua as strings de contexto de criptografia.
```
/* Allocate a hash table for the encryption context */
int set_up_enc_ctx(struct aws_allocator *alloc, struct aws_hash_table *my_enc_ctx)
// Create encryption context strings
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key1, "Example");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value1, "String");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key2, "Company");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value2, "MyCryptoCorp");
// Put the key-value pairs in the hash table
aws_hash_table_put(my_enc_ctx, enc_ctx_key1, (void *)enc_ctx_value1, &was_created)
aws_hash_table_put(my_enc_ctx, enc_ctx_key2, (void *)enc_ctx_value2, &was_created)
```
Obtenha um ponteiro mutável para o contexto de criptografia na sessão. Depois, use a função `aws_cryptosdk_enc_ctx_clone` para copiar o contexto de criptografia na sessão. Mantemos a cópia em `my_enc_ctx` para que possamos validar o valor depois de descriptografar os dados.
O contexto de criptografia faz parte da sessão, não é um parâmetro transmitido para a função de processo da sessão. Isso garante que o mesmo contexto de criptografia seja usado para todos os segmentos de uma mensagem, mesmo se a função de processo de sessão for chamada várias vezes para criptografar a mensagem inteira.
```
struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_mut(session);
aws_cryptosdk_enc_ctx_clone(alloc, session_enc_ctx, my_enc_ctx)
```
Etapa 5: Criptografar a string.
Para criptografar a string em texto simples, use o método `aws_cryptosdk_session_process_full` com a sessão no modo de criptografia. Esse método, introduzido nas AWS Encryption SDK versões 1.9. *x* e 2.2. *x*, foi projetado para criptografia e decodificação sem streaming. Para lidar com dados de streaming, chame o `aws_cryptosdk_session_process` continuamente.
Na criptografia, os campos em texto simples são campos de entrada; os campos em texto cifrado são campos de saída. Concluído o processamento, o campo `ciphertext_output` conterá a [mensagem criptografada](concepts.md#message), incluindo o texto cifrado real, as chaves de dados criptografadas e o contexto de criptografia. Você pode descriptografar essa mensagem criptografada usando o AWS Encryption SDK para qualquer linguagem de programação compatível.
```
/* Gets the length of the plaintext that the session processed */
size_t ciphertext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
ciphertext_output,
ciphertext_buf_sz_output,
&ciphertext_len_output,
plaintext_input,
plaintext_len_input)) {
aws_cryptosdk_session_destroy(session);
return 8;
}
```
Passo 6: Limpar a sessão.
A etapa final destroi a sessão, inclusive as referências ao CMM e ao token de autenticação.
Se você preferir, em vez de destruir a sessão, reutilize-a com o mesmo token de autenticação e CMM para descriptografar a string, ou para criptografar ou descriptografar outras mensagens. Para usar a sessão para descriptografia, use o método `aws_cryptosdk_session_reset` para alterar o modo para `AWS_CRYPTOSDK_DECRYPT`.
### Descriptografar uma string
A segunda parte deste exemplo descriptografa uma mensagem criptografada que contém o texto cifrado da string original.
Etapa 1: carregar sequências de erro.
Chame o método `aws_cryptosdk_load_error_strings()` no código C\$1\$1 ou C\$1\$1. Ele carrega informações de erro que são muito úteis para depuração.
Você só precisa chamá-lo uma vez, como no método `main`.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
Etapa 2: estruturar o token de autenticação.
Ao descriptografar dados AWS KMS, você passa a [mensagem criptografada](concepts.md#message) que a API de criptografia retornou. A [API Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) não aceita uma AWS KMS key entrada. Em vez disso, AWS KMS usa o mesmo AWS KMS key para descriptografar o texto cifrado usado para criptografá-lo. No entanto, AWS Encryption SDK permite que você especifique um AWS KMS chaveiro sem AWS KMS keys criptografar e descriptografar.
Ao descriptografar, você pode configurar um chaveiro apenas com o AWS KMS keys que deseja usar para descriptografar a mensagem criptografada. Por exemplo, talvez você queira criar um chaveiro apenas com o AWS KMS key que é usado por uma função específica em sua organização. Eles nunca AWS Encryption SDK usarão um, AWS KMS key a menos que apareça no chaveiro de decodificação. Se o SDK não conseguir descriptografar as chaves de dados criptografadas usando o AWS KMS keys chaveiro fornecido por você, seja porque nada do chaveiro foi usado para criptografar nenhuma das AWS KMS keys chaves de dados ou porque o chamador não tem permissão para usar o chaveiro para descriptografar, a chamada de descriptografia falhará. AWS KMS keys
[Ao especificar um AWS KMS key para um chaveiro de decodificação, você deve usar o ARN da chave.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) Os [alias ARNs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) são permitidos somente em chaveiros de criptografia. Para obter ajuda para identificar o AWS KMS keys em um AWS KMS chaveiro, consulte[Identificação AWS KMS keys em um AWS KMS chaveiro](use-kms-keyring.md#kms-keyring-id).
Neste exemplo, especificamos um chaveiro configurado com o mesmo AWS KMS key usado para criptografar a string. Antes de executar esse código, substitua o ARN da chave de exemplo por um válido.
```
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);
```
Etapa 3: Criar uma sessão.
Crie uma sessão usando o alocador e o token de autenticação. Para configurar a sessão para descriptografia, configure a sessão com o modo `AWS_CRYPTOSDK_DECRYPT`.
Depois de criar uma sessão com um token de autenticação, você poderá liberar sua referência ao token de autenticação usando o método fornecido pelo SDK. A sessão mantém uma referência ao objeto token de autenticação durante sua vida útil, e a sessão e o token de autenticação são liberados quando você destrói a sessão. Essa técnica de contagem de referência ajuda a evitar vazamentos de memória e a evitar que os objetos sejam liberados enquanto estão em uso.
```
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
```
Etapa 4: Descriptografar a string.
Para descriptografar a string, use o método `aws_cryptosdk_session_process_full` com a sessão configurada para descriptografia. Esse método, introduzido nas versões 1.9.*x* e 2.2.*x* do AWS Encryption SDK , foi projetado para criptografia e descriptografia que não sejam de streaming. Para lidar com dados de streaming, chame o `aws_cryptosdk_session_process` continuamente.
Na descriptografia, os campos em texto cifrado são campos de entrada, e os campos em texto simples são campos de saída. O campo `ciphertext_input` contém a [mensagem criptografada](message-format.md) retornada pelo método de criptografia. Quando o processamento for concluído, o campo `plaintext_output` conterá a string em texto simples (descriptografada).
```
size_t plaintext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
plaintext_output,
plaintext_buf_sz_output,
&plaintext_len_output,
ciphertext_input,
ciphertext_len_input)) {
aws_cryptosdk_session_destroy(session);
return 13;
}
```
Etapa 5: Verificar o contexto de criptografia.
Verifique se o contexto de criptografia real, o que foi usado para descriptografar a mensagem, contém o contexto de criptografia fornecido ao criptografar a mensagem. O contexto de criptografia real pode incluir pares extras porque o [gerenciador de materiais criptográficos](concepts.md#crypt-materials-manager) (CMM) pode adicionar pares ao contexto de criptografia fornecido antes de criptografar a mensagem.
No AWS Encryption SDK for C, você não precisa fornecer um contexto de criptografia ao descriptografar porque o contexto de criptografia está incluído na mensagem criptografada que o SDK retorna. No entanto, antes que a mensagem em texto simples seja retornada, sua função de descriptografia deve verificar se todos os pares no contexto de criptografia fornecido aparecem no contexto que foi usado para descriptografar a mensagem.
Primeiro, obtenha um ponteiro somente leitura para a tabela de hash na sessão. Essa tabela de hash contém o contexto de criptografia que foi usado para descriptografar a mensagem.
```
const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);
```
Depois, percorra o contexto na tabela de hash `my_enc_ctx` que você copiou ao efetuar a criptografia. Verifique se cada par na tabela de hash `my_enc_ctx` que foi usada para efetuar a criptografia aparece na tabela de hash `session_enc_ctx` que foi usada para efetuar a descriptografia. Se alguma chave estiver ausente ou se essa chave tiver um valor diferente, interrompa o processamento e escreva uma mensagem de erro.
```
for (struct aws_hash_iter iter = aws_hash_iter_begin(my_enc_ctx); !aws_hash_iter_done(&iter);
aws_hash_iter_next(&iter)) {
struct aws_hash_element *session_enc_ctx_kv_pair;
aws_hash_table_find(session_enc_ctx, iter.element.key, &session_enc_ctx_kv_pair)
if (!session_enc_ctx_kv_pair ||
!aws_string_eq(
(struct aws_string *)iter.element.value, (struct aws_string *)session_enc_ctx_kv_pair->value)) {
fprintf(stderr, "Wrong encryption context!\n");
abort();
}
}
```
Passo 6: Limpar a sessão.
Depois de verificar o contexto de criptografia, destrua a sessão ou a reutilize. Se precisar reconfigurá-la, use o método `aws_cryptosdk_session_reset`.
```
aws_cryptosdk_session_destroy(session);
```