Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Uso del SDK de cifrado de AWS para C
En este tema se explican algunas de las funciones del SDK de cifrado de AWS para C que no se admiten en otras implementaciones de lenguajes de programación.
Los ejemplos en esta sección muestran cómo usar la [versión 2.0.](about-versions.md)*x* y versiones posteriores de SDK de cifrado de AWS para C. Para ver ejemplos que utilizan versiones anteriores, busca tu versión en la lista de [versiones](https://github.com/aws/aws-encryption-sdk-c/releases) del [aws-encryption-sdk-c repositorio](https://github.com/aws/aws-encryption-sdk-c/) de GitHub.
Para obtener más información sobre la programación con SDK de cifrado de AWS para C, consulta los [ejemplos en C](c-examples.md), los [ejemplos](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) del [aws-encryption-sdk-c repositorio](https://github.com/aws/aws-encryption-sdk-c/) y la [documentación de la SDK de cifrado de AWS para C API](https://aws.github.io/aws-encryption-sdk-c/html/). GitHub
Véase también: [Conjuntos de claves](choose-keyring.md)
**Topics**
+ [Patrones para cifrar y descifrar datos](#c-language-using-pattern)
+ [Recuento de referencias](#c-language-using-release)
## Patrones para cifrar y descifrar datos
Al utilizar el SDK de cifrado de AWS para C, se sigue un patrón similar al siguiente: crear un anillo de [claves, crear una [CMM](concepts.md#crypt-materials-manager) que utilice el anillo](concepts.md#keyring) de claves, crear una sesión que utilice el CMM (y el anillo de claves) 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\$1\$1. 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 conjunto de claves.
Configure el [conjunto de claves](concepts.md#keyring) con las claves de encapsulamiento que desee utilizar para cifrar sus claves de datos. En este ejemplo, se utiliza un [AWS KMS llavero](use-kms-keyring.md) con otro AWS KMS key, pero se puede utilizar cualquier tipo de llavero en su lugar.
Para identificar un AWS KMS key en un anillo de claves de cifrado en SDK de cifrado de AWS para C, especifique un ARN de [clave o un ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) de [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn). En un conjunto de claves de descifrado, debe usar un ARN de clave. Para obtener más información, consulte [Identificarse AWS KMS keys en un AWS KMS llavero](use-kms-keyring.md#kms-keyring-id).
```
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. Crear una sesión.
En el SDK de cifrado de AWS para C, se utiliza una *sesión* para cifrar un solo mensaje de texto sin formato o descifrar un solo mensaje de texto cifrado, independientemente 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 conjunto de claves 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, se crea SDK de cifrado de AWS para C automáticamente un gestor de materiales criptográficos (CMM) predeterminado para usted. No es necesario crear, mantener o destruir este objeto.
Por ejemplo, en la sesión siguiente se utiliza el asignador y el conjunto de claves 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\$1streaming.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/file_streaming.cpp). `aws_cryptosdk_session_process_full`Se presenta en AWS Encryption SDK las versiones 1.9. *x* y 2.2. *x*.
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](message-format.md) 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](message-format.md) 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 [conjunto de claves](concepts.md#keyring), como crear una sesión con un conjunto de claves
+ Un [administrador de materiales criptográficos](concepts.md#crypt-materials-manager) (CMM) predeterminado, como crear una sesión o un CMM personalizado con un CMM predeterminado
+ Una [caché de claves de datos](data-key-caching.md), como crear un CMM de almacenamiento en caché con un conjunto de claves 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 [conjunto de claves](concepts.md#keyring), la sesión obtiene una referencia al conjunto de claves y la mantiene hasta que se destruya la sesión. Si no necesita mantener una referencia adicional al conjunto de claves, puede utilizar el método `aws_cryptosdk_keyring_release` para liberar el objeto de conjunto de claves tan pronto como se cree la sesión. Este método reduce el recuento de referencias para el conjunto de claves. La referencia de la sesión al conjunto de claves 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 conjunto de claves 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 utiliza una alternativa CMMs, como la CMM de almacenamiento en caché para el almacenamiento en caché de [claves de datos](data-key-caching.md). Cuando crea un CMM de almacenamiento en caché a partir de una caché y un conjunto de claves, 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 conjunto de claves 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);
```