Uso do AWS Encryption SDK para C - SDK de criptografia da AWS

Se fornecermos uma tradução da versão em inglês do guia, a versão em inglês prevalecerá caso haja qualquer conflito entre as versões. A tradução é fornecida com o uso de tradução por máquina.

Uso do AWS Encryption SDK para C

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

Para obter detalhes sobre programação com o AWS Encryption SDK para 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 para C.

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

Padrões para criptografar e descriptografar dados

Ao usar o AWS Encryption SDK para 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 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 Chave mestra do cliente (CMK) do AWS KMS, mas você pode usar qualquer tipo de token de autenticação em seu lugar.

Para identificar uma CMK do AWS KMS em um token de autenticação de criptografia, 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 CMKs em um token de autenticação do AWS KMS.

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);
2. Crie uma sessão.

No AWS Encryption SDK para 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 sua sessão com um localizador, um keyring e um modo: AWS_CRYPTOSDK_ENCRYPT ou AWS_CRYPTOSDK_DECRYPT. Se precisar de alterar o modo da sessão, utilize o aws_cryptosdk_session_reset método.

Ao criar uma sessão com um token de autenticação, o AWS Encryption SDK para 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(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
3. Defina o tamanho da mensagem.

Ao criptografar dados, você precisa chamar o método aws_cryptosdk_session_set_message_size, que informa ao SDK de criptografia da AWS o tamanho dos dados em texto simples. Você pode chamar esse método antes ou durante o processamento da sessão, mas deve chamá-lo uma vez. Caso contrário, o método de processamento da sessão não saberá onde os dados de entrada terminam.

Não chame esse método durante a descriptografia. O SDK de criptografia da AWS usa o rodapé da mensagem criptografada para determinar onde o texto cifrado termina.

const char *plaintext = "Hello world!"; const size_t plaintext_len = strlen(plaintext); aws_cryptosdk_session_set_message_size(session, plaintext_length)
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ê precisará chamar o método apenas uma vez. No entanto, se precisar lidar com dados de streaming, você poderá chamar o método em um loop. Para obter um exemplo, consulte o file_streaming.cpp .

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(session, ciphertext, ciphertext_buffer_size, ciphertext_length, plaintext, plaintext_length, &plaintext_consumed)

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.

// Decrypting data aws_cryptosdk_session_process(session, plaintext, plaintext_buffer_size, plaintext_length, ciphertext, ciphertext_length, &ciphertext_consumed)

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:

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(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 ao cache e ao 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(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm); // Release your references to the caching CMM. aws_cryptosdk_cmm_release(caching_cmm); // ... aws_cryptosdk_session_destroy(session);