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 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);
```