Exemplos do AWS Encryption SDK for C

Os exemplos a seguir mostram como usar o AWS Encryption SDK for C para criptografar e descriptografar dados.

Esses exemplos mostram como usar as versões 2.0.x e posteriores do AWS Encryption SDK for C. Para obter exemplos que usam versões anteriores, encontre sua versão na lista de Versões do repositório aws-encryption-sdk-c no GitHub.

Ao instalar e criar o AWS Encryption SDK for C, o código-fonte para estes e outros exemplos está incluído no subdiretório examples e é compilado e criado no diretório build. Você também pode localizá-los no subdiretório examples do repositório do aws-encryption-sdk-c no GitHub.

Criptografar e descriptografar strings

O exemplo a seguir mostra como usar o AWS Encryption SDK for C para criptografar e descriptografar uma string.

Este exemplo apresenta o token de autenticação do AWS KMS, um tipo de token de autenticação que usa uma AWS KMS key no AWS Key Management Service (AWS KMS) para gerar e criptografar chaves de dados. O exemplo inclui código escrito em C++. O AWS Encryption SDK for C exige que o AWS SDK for C++ chame o AWS KMS ao usar o token de autenticação do AWS KMS. Se você estiver usando um token de autenticação que não interage com o AWS KMS, como um token de autenticação do AES bruto, um token de autenticação do RSA bruto ou um multitoken de autenticação que não inclui um token de autenticação do AWS KMS, o AWS SDK for C++ não será necessário.

Para obter ajuda na criação de uma AWS KMS key, consulte Criação de chaves no Guia do desenvolvedor do AWS Key Management Service. Para obter ajuda para identificar o AWS KMS keys em um token de autenticação do AWS KMS, consulte Identificar AWS KMS keys em um token de autenticação do AWS KMS.

Consulte o exemplo de código completo: string.cpp

Tópicos

• Criptografar uma string
• Descriptografar uma string

Criptografar uma string

A primeira parte deste exemplo usa um token de autenticação AWS KMS com uma AWS KMS key para criptografar uma string de texto simples.

Etapa 1. Carregar sequências de erro.

Chame o método aws_cryptosdk_load_error_strings() no código C++ ou C++. 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.

Criar um token de autenticação do AWS KMS para criptografia. O token de autenticação neste exemplo é configurado com uma AWS KMS key, mas você pode configurar um token de autenticação do AWS KMS com várias AWS KMS keys, inclusive AWS KMS keys em diferentes Regiões da AWS e contas.

Para identificar uma AWS KMS key em um token de autenticação de criptografia no AWS Encryption SDK for C, especifique um ARN de chave ou um ARN de alias. Em um token de autenticação de descriptografia, é necessário usar um ARN de chave. Para obter mais detalhes, consulte Identificar AWS KMS keys em um token de autenticação do AWS KMS.

Identificar AWS KMS keys em um token de autenticação do AWS KMS

Ao criar um token de autenticação com várias AWS KMS keys, você especifica a AWS KMS key usada para gerar e criptografar a chave de dados de texto simples e uma matriz opcional de AWS KMS keys adicionais que criptografam a mesma chave de dados de texto simples. Nesse caso, especificamos apenas a AWS KMS key geradora.

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 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 são dados autenticados adicionais arbitrários e que não são secretos. Quando você fornece um contexto de criptografia na criptografia, o AWS Encryption SDK vincula de forma criptográfica o contexto 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 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 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, 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 em 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++ ou C++. 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 no AWS KMS, você transmite a mensagem criptografada retornada pela API de criptografia. A API Decrypt não precisa de uma AWS KMS key como entrada. Em vez disso, o AWS KMS usa a mesma AWS KMS key para descriptografar o texto cifrado usado para criptografá-lo. No entanto, o AWS Encryption SDK permite especificar um token de autenticação do AWS KMS com AWS KMS keys ao criptografar e ao descriptografar.

Ao descriptografar, você pode configurar um token de autenticação com apenas as AWS KMS keys que você deseja usar para descriptografar a mensagem criptografada. Por exemplo, talvez você queira criar um token de autenticação com apenas a AWS KMS key usada por uma função específica em sua organização. O AWS Encryption SDK nunca usa uma AWS KMS key, a menos que ela apareça no token de autenticação de descriptografia. Se o SDK não puder descriptografar as chaves de dados criptografadas usando as AWS KMS keys no token de autenticação que você fornecer, seja porque nenhuma das AWS KMS keys no token de autenticação foi usada para criptografar nenhuma da chaves de dados ou porque o chamador não tem permissão para usar as AWS KMS keys no token de autenticação para descriptografar, ocorrerá uma falha na chamada de descriptografia.

Ao especificar uma AWS KMS key para um token de autenticação de descriptografia, é necessário usar seu ARN de chave. Os ARNs de alias são permitidos somente em tokens de autenticação de criptografia. . Para obter ajuda para identificar o AWS KMS keys em um token de autenticação do AWS KMS, consulte Identificar AWS KMS keys em um token de autenticação do AWS KMS.

Neste exemplo, especificamos um token de autenticação configurado com a mesma AWS KMS key usada 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 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 (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 é incluído na mensagem criptografada retornada pelo SDK. 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);