Utilización de la SDK de cifrado de AWS para C

En este tema se explican algunas de las características del SDK de cifrado de AWS para C que no son compatibles en otras implementaciones de lenguaje de programación.

Los ejemplos en esta sección muestran cómo usar la versión 2.0.x y posterior del SDK de cifrado de AWS para C. Para ver ejemplos que usan versiones anteriores, busque su versión en la lista de Versiones del repositorio aws-encryption-sdk-c repository en GitHub.

Para obtener información acerca de la programación con el SDK de cifrado de AWS para C, consulte los ejemplos de C, los ejemplos del repositorio aws-encryption-sdk-c de GitHub y la documentación de la API de SDK de cifrado de AWS para C.

Véase también: Uso de conjuntos de claves

Patrones para cifrar y descifrar datos

Cuando se utiliza el SDK de cifrado de AWS para C para C, se sigue un patrón similar a este: crear un llavero, crear un CMM que utilice el llavero, crear una sesión que utilice el CMM (y el llavero) y, a continuación, procesar la sesión.

1. Cargue cadenas de error.

Llame al método aws_cryptosdk_load_error_strings() en su código C o C++. Carga información de error que es muy útil para la depuración.

Solo necesita llamarlo una vez, por ejemplo, en su método main.

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

2. Cree un llavero.

Configure el llavero con las claves de empaquetado que desee utilizar para cifrar sus claves de datos. En este ejemplo se utiliza un llavero de AWS KMS con AWS KMS key, pero puede utilizar cualquier tipo de llavero en su lugar.

Para identificar un AWS KMS key en un llavero de cifrado en SDK de cifrado de AWS para C, especifique un ARN de clave o un ARN de alias. En un llavero de descifrado, debe usar un ARN de clave. Para obtener más información, consulte Identificarse AWS KMS keys en un AWS KMS llavero.

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. Cree una sesión.

En el SDK de cifrado de AWS para C, utilice una sesión para cifrar un mensaje único en texto no cifrado o para descifrar un mensaje único en texto cifrado, con independencia de su tamaño. La sesión mantiene el estado del mensaje a lo largo del procesamiento.

Configure la sesión con un asignador, un llavero y un modo: AWS_CRYPTOSDK_ENCRYPT o AWS_CRYPTOSDK_DECRYPT. Si tiene que cambiar el modo de la sesión, utilice el método aws_cryptosdk_session_reset.

Al crear una sesión con un llavero, el SDK de cifrado de AWS para C le crea automáticamente un administrador de materiales criptográficos (CMM) predeterminado. No es necesario crear, mantener o destruir este objeto.

Por ejemplo, en la sesión siguiente se utiliza el asignador y el llavero que se ha definido en el paso 1. Cuando se cifran datos, el modo es AWS_CRYPTOSDK_ENCRYPT.

struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);

4. Cifre o descifre los datos.

Para procesar los datos de la sesión, utilice el método aws_cryptosdk_session_process. Si el búfer de entrada es lo suficientemente grande como para contener todo el texto no cifrado y el búfer de salida es lo suficientemente grande como para contener todo el texto cifrado, puede llamar a aws_cryptosdk_session_process_full. Sin embargo, si tiene que gestionar un streaming de datos, puede llamar a aws_cryptosdk_session_process en un bucle. Para ver un ejemplo, consulte file_streaming.cpp. El aws_cryptosdk_session_process_full se introduce en las versiones 1.9.x y 2.2.x de AWS Encryption SDK.

Cuando la sesión se configura para cifrar los datos, los campos de texto no cifrado describen la entrada y los campos de texto cifrado describen la salida. El campo plaintext mantiene el mensaje que desea cifrar y el campo ciphertext recibe el mensaje cifrado que devuelve el método de cifrado.

/* Encrypting data */
aws_cryptosdk_session_process_full(session,
                                   ciphertext,
                                   ciphertext_buffer_size,
                                   &ciphertext_length,
                                   plaintext,
                                   plaintext_length)
                              

Cuando la sesión se configura para descifrar los datos, los campos de texto cifrado describen la entrada y los campos de texto no cifrado describen la salida. El campo ciphertext mantiene el mensaje cifrado que ha devuelto el método de cifrado y el campo plaintext recibe el mensaje de texto no cifrado que devuelve el método de descifrado.

Para descifrar los datos, llame al método aws_cryptosdk_session_process_full.

/* Decrypting data */
aws_cryptosdk_session_process_full(session,
                                   plaintext,
                                   plaintext_buffer_size,
                                   &plaintext_length,
                                   ciphertext,
                                   ciphertext_length)
                                   

Recuento de referencias

Para evitar pérdidas de memoria, libere las referencias a todos los objetos que cree cuando haya terminado con ellos. De lo contrario, acabará con fugas de memoria. El SDK proporciona métodos para facilitar esta tarea.

Cada vez que se crea un objeto principal con uno de los siguientes objetos secundarios, el objeto principal obtiene y mantiene una referencia al objeto secundario, como se indica a continuación:

• Un llavero, como crear una sesión con un llavero

• Un administrador de materiales criptográficos (CMM) predeterminado, como crear una sesión o un CMM personalizado con un CMM predeterminado

• Una caché de claves de datos, como crear un CMM de almacenamiento en caché con un llavero y una caché

A menos que necesite una referencia independiente al objeto secundario, puede liberar la referencia al objeto secundario tan pronto como cree el objeto principal. La referencia restante al objeto secundario se libera cuando se destruye el objeto principal. Este patrón garantiza que mantenga la referencia a cada objeto solo durante el tiempo que la necesite y no tener fugas de memoria debidas a referencias sin liberar.

Solo es responsable de liberar referencias a los objetos secundarios que cree explícitamente. No es responsable de administrar las referencias a ningún objeto que el SDK cree para usted. Si el SDK crea un objeto, como el predeterminado que el método aws_cryptosdk_caching_cmm_new_from_keyring agrega a una sesión, el SDK administra la creación y destrucción del objeto y sus referencias.

En el ejemplo siguiente, al crear una sesión con un llavero, la sesión obtiene una referencia al llavero y la mantiene hasta que se destruya la sesión. Si no necesita mantener una referencia adicional al llavero, puede utilizar el método aws_cryptosdk_keyring_release para liberar el objeto de llavero tan pronto como se cree la sesión. Este método reduce el recuento de referencias para el llavero. La referencia de la sesión al llavero se libera cuando se llama a aws_cryptosdk_session_destroy para destruir la sesión.

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

En el caso de tareas más complejas, como la reutilización de un llavero para varias sesiones o la especificación de un conjunto de algoritmos en un CMM, es posible que necesite mantener una referencia independiente al objeto. Si es así, no llame a los métodos de lanzamiento inmediatamente. En su lugar, además de destruir la sesión, libere las referencias cuando ya no use los objetos.

Esta técnica de recuento de referencias también funciona cuando se utilizan CMM alternativos, como el CMM de almacenamiento en caché para el almacenamiento en caché de claves de datos. Cuando crea un CMM de almacenamiento en caché a partir de una caché y un llavero, el CMM de almacenamiento en caché obtiene una referencia a ambos objetos. A menos que los necesite para otra tarea, puede liberar las referencias independientes a la caché y al llavero tan pronto como se cree el CMM de almacenamiento en caché. Luego, cuando cree una sesión con el CMM de almacenamiento en caché, puede liberar la referencia al CMM de almacenamiento en caché.

Observe que solo es responsable de liberar referencias a objetos que cree explícitamente. Los objetos que los métodos creen en su lugar, como el CMM predeterminado que subyace al CMM de almacenamiento en caché, se administran a través del 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);