Usar a AWS Encryption SDK for C

Este tópico explica alguns recursos do AWS Encryption SDK for C que não são compatíveis em outras implementações de linguagem de programação.

Esses exemplos mostram como usar a versão 2.0.x e versões 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.

Para obter detalhes sobre programação com o AWS Encryption SDK for C, consulte os exemplos de C, os exemplos no repositório aws-encryption-sdk-c repository no GitHub e a documentação da API do AWS Encryption SDK for C.

Consulte também: Usar tokens de autenticação

Padrões para criptografar e descriptografar dados

Ao usar o AWS Encryption SDK for C, você segue um padrão semelhante a este: criar um token de autenticação, criar um CMM que usa o token de autenticação, criar uma sessão que usa o CMM (e o token de autenticação) e processar a sessão.

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

2. Crie um token de autenticação.

Configure o token de autenticação com as chaves de empacotamento que você deseja usar para criptografar suas chaves de dados. Este exemplo usa um token de autenticação do AWS KMS com uma AWS KMS key, mas você pode usar qualquer tipo de token de autenticação em seu lugar.

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 Identificação AWS KMS keys em um AWS KMS chaveiro.

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 para descriptografar uma única mensagem de texto cifrado, independentemente de seu 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.

Ao criar uma sessão com um token de autenticação, o AWS Encryption SDK for C cria 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_streaming.cpp . O aws_cryptosdk_session_process_full foi introduzido nas versões 1.9.x e 2.2.x. do AWS Encryption SDK.

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 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 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, como criar uma sessão com um token de autenticação

• Um gerenciador de materiais criptográficos (CMM) padrão, como criar uma sessão ou um CMM personalizado com um CMM padrão

• Um cache de chaves de dados, 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, 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ências também funciona quando você está usando CMMs alternativos, como o CMM de armazenamento em cache para o armazenamento em cache de chaves de dados. 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);