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.
# SDK de cifrado de AWS para C
SDK de cifrado de AWS para C Proporciona una biblioteca de cifrado del lado del cliente para los desarrolladores que escriben aplicaciones en C. También sirve como base para las implementaciones AWS Encryption SDK en lenguajes de programación de nivel superior.
Como todas las implementaciones de, SDK de cifrado de AWS para C ofrece funciones avanzadas de AWS Encryption SDK protección de datos. Esto incluye el [cifrado de sobre](concepts.md#envelope-encryption), la información autenticada adicional (AAD) y los [conjuntos de algoritmos](concepts.md#crypto-algorithm) de clave simétrica autenticados y seguros, tales como AES-GCM de 256 bits con derivación de clave y firma.
Todas las implementaciones específicas del idioma son totalmente interoperables. AWS Encryption SDK Por ejemplo, puede cifrar datos con SDK de cifrado de AWS para C y descifrarlos con [cualquier implementación de lenguaje compatible](programming-languages.md), incluida la [AWS CLI](crypto-cli.md) de cifrado.
SDK de cifrado de AWS para C Requiere interactuar AWS SDK para C\$1\$1 con AWS Key Management Service ()AWS KMS. Solo debe usarlo si está usando el [conjunto de claves de AWS KMS](use-kms-keyring.md) opcional. Sin embargo, AWS Encryption SDK no requiere AWS KMS ningún otro AWS servicio.
**Más información**
+ 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
+ Para obtener información sobre cómo utilizar el código SDK de cifrado de AWS para C para cifrar datos y poder descifrarlos en varias partes Regiones de AWS, consulte [Cómo descifrar textos cifrados en varias regiones con la letra en C AWS Encryption SDK en el blog](https://aws.amazon.com/blogs/security/how-to-decrypt-ciphertexts-multiple-regions-aws-encryption-sdk-in-c/) de seguridad. AWS
**Topics**
+ [Instalación](c-language-installation.md)
+ [Uso del SDK de C](c-language-using.md)
+ [Ejemplos](c-examples.md)
# Instalación del SDK de cifrado de AWS para C
Instale la versión más reciente de SDK de cifrado de AWS para C.
**nota**
Todas las versiones SDK de cifrado de AWS para C anteriores a la 2.0.0 están en [end-of-supportfase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle).
Puede actualizar de forma segura desde la versión 2.0.*x* y versiones posteriores a la última versión de SDK de cifrado de AWS para C sin cambios en el código ni en los datos. Sin embargo, [nuevas características de seguridad](about-versions.md#version-2) que se introdujeron en la versión 2.0.*x* no son compatibles con versiones anteriores. Para actualizar desde versiones anteriores a la 1.7.*x* a la versión 2.0.*x* y posteriores, primero debe actualizar a la última versión 1.*x* de SDK de cifrado de AWS para C. Para obtener más información, consulte [Migrando su AWS Encryption SDK](migration.md).
Encontrará instrucciones detalladas para instalarlo y compilarlo SDK de cifrado de AWS para C en el [archivo README](https://github.com/aws/aws-encryption-sdk-c/#readme) del [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)repositorio. Incluye instrucciones para crear en las plataformas Amazon Linux, Ubuntu, macOS y Windows.
Antes de empezar, decida si desea utilizar [conjuntos de claves de AWS KMS](use-kms-keyring.md) en el AWS Encryption SDK. Si utilizas un AWS KMS llavero, tendrás que instalar el. AWS SDK para C\$1\$1 Se requiere el AWS SDK para interactuar con [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS). Cuando utilizas AWS KMS anillos de claves, se AWS Encryption SDK utilizan AWS KMS para generar y proteger las claves de cifrado que protegen tus datos.
No necesita instalarlo AWS SDK para C\$1\$1 si utiliza otro tipo de anillo de claves, como un anillo de claves AES sin procesar, un anillo de claves RSA sin procesar o un anillo de claves múltiples que no incluye un anillo de claves. AWS KMS Sin embargo, cuando utilice un tipo de conjunto de claves sin procesar, tendrá que generar y proteger sus propias claves de encapsulamiento sin procesar.
Si tiene problemas con la instalación, [registre un problema](https://github.com/aws/aws-encryption-sdk-c/issues) en el repositorio `aws-encryption-sdk-c` o utilice cualquiera de los enlaces de comentarios de esta página.
# 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);
```
# SDK de cifrado de AWS para C ejemplos
Los siguientes ejemplos muestran cómo utilizarlos SDK de cifrado de AWS para C para cifrar y descifrar datos.
Los ejemplos en esta sección muestran cómo usar las versiones 2.0.*x* y posteriores del SDK de cifrado de AWS para C. Para ver ejemplos que utilizan versiones anteriores, busque su 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
Al instalar y compilar SDK de cifrado de AWS para C, el código fuente de estos y otros ejemplos se incluye en el `examples` subdirectorio y se compila e integra en el `build` directorio. También puedes encontrarlos en el subdirectorio de [ejemplos](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) del [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/)repositorio en. GitHub
**Topics**
+ [Cifrado y descifrado de cadenas](#c-example-strings)
## Cifrado y descifrado de cadenas
El siguiente ejemplo muestra cómo utilizar el SDK de cifrado de AWS para C para cifrar y descifrar una cadena.
En este ejemplo se incluye el [AWS KMS anillo de claves](use-kms-keyring.md), un tipo de anillo de claves que utiliza un AWS KMS key in [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/) para generar y cifrar claves de datos. El ejemplo incluye código escrito en C\$1\$1. SDK de cifrado de AWS para C Requiere llamar AWS KMS cuando se utilizan AWS SDK para C\$1\$1 anillos de claves. AWS KMS Si utilizas un llavero con el que no interactúa AWS KMS, como un llavero AES puro, un llavero RSA puro o un llavero múltiple que no incluye un AWS KMS llavero, no es obligatorio. AWS SDK para C\$1\$1
[https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) Si necesita ayuda para AWS KMS keys identificarlas en un AWS KMS llavero, consulte[Identificarse AWS KMS keys en un AWS KMS llavero](use-kms-keyring.md#kms-keyring-id).
**Vea la muestra de código completa**: [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp)
**Topics**
+ [Cifrado de una cadena](#c-example-string-encrypt)
+ [Descifrado de una cadena](#c-example-string-decrypt)
### Cifrado de una cadena
En la primera parte de este ejemplo, se utiliza un AWS KMS anillo de claves con otro AWS KMS key para cifrar una cadena de texto sin formato.
Paso 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();
```
Paso 2: crear el conjunto de claves.
Cree un anillo de AWS KMS claves para el cifrado. El anillo de claves de este ejemplo está configurado con uno AWS KMS key, pero puede configurar un AWS KMS anillo de claves con varios AWS KMS keys, incluso AWS KMS keys en cuentas diferentes Regiones de AWS y diferentes.
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).
[Identificarse AWS KMS keys en un AWS KMS llavero](use-kms-keyring.md#kms-keyring-id)
Al crear un conjunto de claves con varios AWS KMS keys, se especifica la que AWS KMS key se utiliza para generar y cifrar la clave de datos de texto sin formato y una matriz opcional de claves adicionales AWS KMS keys que cifran la misma clave de datos de texto sin formato. En este caso, solo se especifica el generador. AWS KMS key
Antes de ejecutar este código, reemplace el ARN de clave de ejemplo por uno 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);
```
Paso 3: crear una sesión.
Cree una sesión. Para ello, use el asignador, un enumerador de modos y el conjunto de claves.
Cada sesión requiere un modo: bien `AWS_CRYPTOSDK_ENCRYPT` para cifrar o `AWS_CRYPTOSDK_DECRYPT` para descifrar. Para cambiar el modo de una sesión existente, utilice el método `aws_cryptosdk_session_reset`.
Después de crear una sesión con el conjunto de claves, puede liberar la referencia al conjunto de claves con el método que el SDK proporciona. La sesión conserva una referencia al objeto conjunto de claves durante su vida útil. Las referencias al conjunto de claves y a los objetos de sesión se liberan cuando se destruye la sesión. Esta técnica de [recuento de referencias](c-language-using.md#c-language-using-release) ayuda a evitar fugas de memoria y que los objetos se liberen mientras están en 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);
```
Paso 4: establecer el contexto de cifrado.
Un [contexto de cifrado](concepts.md#encryption-context) son datos autenticados adicionales que son arbitrarios y no son secretos. Al proporcionar un contexto de cifrado al cifrar, este vincula AWS Encryption SDK criptográficamente el contexto de cifrado al texto cifrado, de modo que se requiere el mismo contexto de cifrado para descifrar los datos. El uso de un contexto de cifrado es opcional, pero es una práctica recomendada que le aconsejamos.
En primer lugar, cree una tabla hash que incluya las cadenas del contexto de cifrado.
```
/* 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)
```
Obtenga un puntero mutable al contexto de cifrado en la sesión. A continuación, utilice la función `aws_cryptosdk_enc_ctx_clone` para copiar el contexto de cifrado en la sesión. Conserve la copia en `my_enc_ctx` para poder validar el valor después de descifrar los datos.
El contexto de cifrado forma parte de la sesión, no es un parámetro transferido a la función de proceso de la sesión. Esto garantiza que se utilice el mismo contexto de cifrado para cada segmento de un mensaje, incluso si se llama varias veces a la función de proceso de la sesión para cifrar todo el mensaje.
```
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)
```
Paso 5: cifrar la cadena.
Para cifrar la cadena de texto no cifrado, utilice el método `aws_cryptosdk_session_process_full` con la sesión en modo de cifrado. Este método, introducido en las versiones 1.9. AWS Encryption SDK *x* y 2.2. *x*, está diseñado para el cifrado y el descifrado sin transmisión. Para gestionar el streaming de datos, utilice el comando `aws_cryptosdk_session_process` en un bucle.
A la hora de cifrar, los campos de texto no cifrado son campos de entrada; los campos de texto no cifrado son campos de salida. Cuando se completa el procesamiento, el campo `ciphertext_output` contiene el [mensaje cifrado](concepts.md#message), incluido el texto no cifrado real, las claves de datos cifrados y el contexto de cifrado. Puede descifrar este mensaje cifrado mediante cualquier lenguaje AWS Encryption SDK de programación compatible.
```
/* 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;
}
```
Paso 6: limpiar la sesión.
El paso final destruye la sesión, incluidas las referencias al CMM y al conjunto de claves.
Si lo prefiere, en lugar de destruir la sesión, puede reutilizarla con el mismo conjunto de claves y CMM para descifrar la cadena o para cifrar o descifrar otros mensajes. Para utilizar la sesión para descifrado, utilice el método `aws_cryptosdk_session_reset` para cambiar el modo a `AWS_CRYPTOSDK_DECRYPT`.
### Descifrado de una cadena
La segunda parte de este ejemplo descifra un mensaje cifrado que contiene el texto cifrado de la cadena original.
Paso 1: cargar las 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();
```
Paso 2: crear el conjunto de claves.
Al descifrar los datos AWS KMS, se pasa el [mensaje cifrado](concepts.md#message) que ha devuelto la API de cifrado. La [API de descifrado](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) no toma ninguna entrada como AWS KMS key entrada. En su lugar, AWS KMS utiliza lo mismo AWS KMS key para descifrar el texto cifrado que utilizó para cifrarlo. Sin embargo, AWS Encryption SDK permite especificar un conjunto de AWS KMS claves sin cifrar ni descifrar. AWS KMS keys
Al descifrar, puede configurar un anillo de claves solo con el AWS KMS keys que desee utilizar para descifrar el mensaje cifrado. Por ejemplo, es posible que desee crear un conjunto de claves que contenga únicamente el AWS KMS key que utilice un rol concreto de su organización. Nunca AWS Encryption SDK utilizará un AWS KMS key a menos que aparezca en el anillo de claves de descifrado. Si el SDK no puede descifrar las claves de datos cifradas con las del AWS KMS keys anillo de claves que usted proporcione, ya sea porque ninguna de las claves del conjunto de AWS KMS keys claves se utilizó para cifrar ninguna de las claves de datos o porque la persona que llama no tiene permiso para usar las claves del anillo de claves para descifrar, la AWS KMS keys llamada de descifrado fallará.
Al especificar un anillo AWS KMS key de claves de descifrado, debe utilizar su clave [ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN). ARNsLos [alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) solo están permitidos en los anillos de claves de cifrado. Si necesita ayuda para identificarlos AWS KMS keys en un AWS KMS anillo de claves, consulte. [Identificarse AWS KMS keys en un AWS KMS llavero](use-kms-keyring.md#kms-keyring-id)
En este ejemplo, especificamos un conjunto de claves configurado con el mismo que AWS KMS key se utiliza para cifrar la cadena. Antes de ejecutar este código, reemplace el ARN de clave de ejemplo por uno 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);
```
Paso 3: crear una sesión.
Cree una sesión con el asignador y el conjunto de claves. Para configurar la sesión para descifrado, configure la sesión con el modo `AWS_CRYPTOSDK_DECRYPT`.
Después de crear una sesión con un conjunto de claves, puede liberar la referencia al conjunto de claves con el método que el SDK proporciona. La sesión conserva una referencia al objeto de conjunto de claves durante su ciclo de vida y tanto la sesión como el conjunto de claves se liberan cuando se destruye la sesión. Esta técnica de recuento de referencias ayuda a evitar fugas de memoria y que los objetos se liberen mientras están en 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);
```
Paso 4: descifrar la cadena.
Para descifrar la cadena, utilice el método `aws_cryptosdk_session_process_full` con la sesión que está configurada para descifrado. Este método introducido en las versiones 1.9.*x* y 2.2.*x* de AWS Encryption SDK está diseñado para el cifrado y el descifrado sin streaming. Para gestionar el streaming de datos, utilice el comando `aws_cryptosdk_session_process` en un bucle.
Al descifrar, los campos de texto cifrado son campos de entrada y los campos de texto no cifrado son campos de salida. El campo `ciphertext_input` mantiene el [mensaje cifrado](message-format.md) que devolvió el método de cifrado. Cuando el procesamiento está completo, el campo `plaintext_output` contiene la cadena de texto no cifrado (descifrado).
```
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;
}
```
Paso 5: verificar el contexto de cifrado.
Asegúrese de que el contexto de cifrado real (el que se utilizó para descifrar el mensaje) contenga el contexto de cifrado que proporcionó al cifrar el mensaje. El contexto de cifrado real podría incluir pares adicionales, ya que el [administrador de materiales criptográficos](concepts.md#crypt-materials-manager) (CMM) puede añadir pares al contexto de cifrado proporcionado antes de cifrar el mensaje.
En el SDK de cifrado de AWS para C, no es necesario proporcionar un contexto de cifrado al descifrar, ya que el contexto de cifrado está incluido en el mensaje cifrado que devuelve el SDK. Pero, antes de que devuelva el mensaje de texto no cifrado, la función de descifrado debería verificar que todas las parejas en el contexto de cifrado proporcionado aparezcan en el contexto de cifrado que se utilizó para descifrar el mensaje.
En primer lugar, obtenga un puntero de solo lectura a la tabla hash de la sesión. Esta tabla hash contiene el contexto de cifrado que se utilizó para descifrar el mensaje.
```
const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);
```
A continuación, ejecute un bucle en el contexto de cifrado en la tabla hash `my_enc_ctx` que copió al realizar el cifrado. Verifique que cada para de la tabla hash `my_enc_ctx` que se utilizó para cifrar aparece en la tabla hash `session_enc_ctx` que se utilizó para descifrar. Si falta alguna clave o dicha clave tiene un valor distinto, detenga el procesamiento y escriba un mensaje de error.
```
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();
}
}
```
Paso 6: limpiar la sesión.
Después de verificar el contexto de cifrado, puede destruir la sesión o reutilizarla. Si tiene que reconfigurar la sesión, utilice el método `aws_cryptosdk_session_reset`.
```
aws_cryptosdk_session_destroy(session);
```