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.
# AWS Encryption SDK lenguajes de programación
AWS Encryption SDK Está disponible para los siguientes lenguajes de programación. Todas las implementaciones de lenguaje son interoperables. Puede cifrar con una implementación de lenguaje y descifrar con otra. La interoperabilidad puede estar sujeta a restricciones de lenguaje. Si es así, estas restricciones se describen en el tema que trata de la implementación del lenguaje. Además, al cifrar y descifrar, debe usar conjuntos de claves compatibles o claves maestras y proveedores de claves maestras. Para obtener información, consulte [Compatibilidad de conjuntos de claves](choose-keyring.md#keyring-compatibility).
**Topics**
+ [C](c-language.md)
+ [.NET](dot-net.md)
+ [Go](go.md)
+ [Java](java.md)
+ [JavaScript](javascript.md)
+ [Python](python.md)
+ [Rust](rust.md)
+ [Interfaz de línea de comandos](crypto-cli.md)
# 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);
```
# AWS Encryption SDK para.NET
La AWS Encryption SDK para .NET es una biblioteca de cifrado del lado del cliente para desarrolladores que escriben aplicaciones en C\$1 y otros lenguajes de programación.NET. Es compatible con Windows, macOS y Linux.
**nota**
La versión 4.0.0 de para.NET se aparta AWS Encryption SDK de la especificación de mensajes. AWS Encryption SDK En consecuencia, los mensajes cifrados con la versión 4.0.0 solo se pueden descifrar con la versión 4.0.0 o posterior de la versión para .NET. AWS Encryption SDK No se pueden descifrar mediante ninguna otra implementación de lenguaje de programación.
La versión 4.0.1 de .NET escribe AWS Encryption SDK los mensajes de acuerdo con la AWS Encryption SDK especificación de mensajes y es interoperable con otras implementaciones de lenguajes de programación. De forma predeterminada, la versión 4.0.1 puede leer los mensajes cifrados por la versión 4.0.0. Sin embargo, si no desea descifrar los mensajes cifrados con la versión 4.0.0, puede especificar la propiedad de la [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs) para impedir que el cliente lea estos mensajes. Para obtener más información, consulte las [notas de la versión 4.0.1](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1) en el repositorio de. aws-encryption-sdk GitHub
La AWS Encryption SDK versión para .NET se diferencia de algunas de las implementaciones de otros lenguajes de programación AWS Encryption SDK en los siguientes aspectos:
+ No se admite el [almacenamiento en caché de claves de datos](data-key-caching.md)
**nota**
Versión 4. *x* de la versión AWS Encryption SDK para .NET es compatible con el [anillo de claves AWS KMS jerárquico](use-hierarchical-keyring.md), una solución alternativa de almacenamiento en caché de materiales criptográficos.
+ No es compatible con el streaming de datos
+ [Sin registros ni seguimientos de pilas](#dot-net-debugging) del AWS Encryption SDK para .NET
+ [Requiere el AWS SDK para .NET](#dot-net-install)
El AWS Encryption SDK para .NET incluye todas las funciones de seguridad introducidas en las versiones 2.0. *x* y versiones posteriores de las implementaciones en otros idiomas de AWS Encryption SDK. Sin embargo, si utiliza para.NET AWS Encryption SDK para descifrar datos cifrados con una versión anterior a la versión 2.0. *x* versión de la implementación en otro idioma de la AWS Encryption SDK, es posible que necesite ajustar su política de [compromisos](concepts.md#commitment-policy). Para obtener más información, consulte [¿Cómo establecer su política de compromiso?](migrate-commitment-policy.md#migrate-commitment-step1).
La AWS Encryption SDK versión para .NET es un producto de AWS Encryption SDK [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), un lenguaje de verificación formal en el que se escriben las especificaciones, el código para implementarlas y las pruebas para probarlas. El resultado es una biblioteca que implementa las características del AWS Encryption SDK en una trama que garantiza la corrección funcional.
**Más información**
+ Para ver ejemplos que muestran cómo configurar las opciones del AWS Encryption SDK, como especificar un conjunto de algoritmos alternativo, limitar las claves de datos cifrados y utilizar claves AWS KMS multirregionales, consulte. [Configuración del AWS Encryption SDK](configure.md)
+ Para obtener más información sobre la AWS Encryption SDK programación con para.NET, consulte el [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/)directorio del aws-encryption-sdk repositorio en GitHub.
**Topics**
+ [Instalar y compilar](#dot-net-install)
+ [Debugging](#dot-net-debugging)
+ [Ejemplos](dot-net-examples.md)
## Instalación del AWS Encryption SDK para .NET
El AWS Encryption SDK para .NET está disponible como [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)paquete en NuGet. Para obtener más información sobre la instalación y la creación de AWS Encryption SDK para .NET, consulte el archivo [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) del repositorio. `aws-encryption-sdk-net`
**Versión 3.x**
Versión 3. *x* de la AWS Encryption SDK para.NET solo es compatible con .NET Framework 4.5.2 — 4.8 en Windows. Es compatible con .NET Core 3.0\$1 y .NET 5.0 y versiones posteriores en todos los sistemas operativos compatibles.
**Versión 4.x**
Versión 4. *x* de la AWS Encryption SDK para.NET es compatible con .NET 6.0 y .NET Framework net48 y versiones posteriores. Versión 4. *x* requiere el AWS SDK para .NET v3.
**Versión 5.x**
Versión 5. *x* de la versión AWS Encryption SDK para .NET es compatible con .NET 6.0 y .NET Framework net48 y versiones posteriores. Versión 5. *x* requiere la versión 2. *x* de la biblioteca de proveedores de materiales (MPL) y el AWS SDK para .NET v4.
AWS Encryption SDK Para .NET se requieren las teclas « SDK para .NET par» si no se utilizan AWS Key Management Service (AWS KMS). Se instala con el NuGet paquete. Sin embargo, a menos que utilice AWS KMS claves, AWS Encryption SDK para .NET no se Cuenta de AWS requieren AWS credenciales ni interacción con ningún AWS servicio. Si necesita ayuda para configurar una AWS cuenta, consulte[Uso del AWS Encryption SDK con AWS KMS](getting-started.md).
## Depurar el AWS Encryption SDK para .NET
El AWS Encryption SDK para .NET no genera ningún registro. Las excepciones AWS Encryption SDK para .NET generan un mensaje de excepción, pero no hay rastros de pila.
Para ayudarle a depurar, asegúrese de activar el inicio de sesión en la SDK para .NET. Los registros y los mensajes de error del SDK para .NET pueden ayudarle a distinguir los errores que se producen en. NET SDK para .NET de los que se AWS Encryption SDK producen en él. Para obtener ayuda con el SDK para .NET registro, consulte [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)la *Guía para AWS SDK para .NET desarrolladores*. (Para ver el tema, amplíe la sección **Abrir para ver la sección de contenido de .NET Framework**).
# AWS Encryption SDK para ver ejemplos de.NET
Los ejemplos siguientes muestran los patrones de codificación básicos que se utilizan al programar con AWS Encryption SDK para.NET. En concreto, se crea una instancia de la biblioteca AWS Encryption SDK y de proveedores de materiales. A continuación, antes de llamar a cada método, se crea una instancia de un objeto que define la entrada del método. Es muy parecido al patrón de codificación que utiliza en la SDK para .NET.
Para ver ejemplos que muestran cómo configurar las opciones de la AWS Encryption SDK, como especificar un conjunto de algoritmos alternativo, limitar las claves de datos cifrados y utilizar claves AWS KMS multirregionales, consulte. [Configuración del AWS Encryption SDK](configure.md)
Para ver más ejemplos de programación con AWS Encryption SDK para.NET, consulte los [ejemplos](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples) en el `aws-encryption-sdk-net` directorio del `aws-encryption-sdk` repositorio en GitHub.
## Cifrar datos en el AWS Encryption SDK para .NET
En este ejemplo se muestra el patrón básico de cifrado de datos. Cifra un archivo pequeño con claves de datos que están protegidas por una clave de AWS KMS empaquetado.
Paso 1: Cree una instancia de la biblioteca AWS Encryption SDK y de los proveedores de materiales.
Comience por crear una instancia de la biblioteca AWS Encryption SDK y de los proveedores de materiales. Utilizará los métodos descritos en AWS Encryption SDK para cifrar y descifrar los datos. Utilizará los métodos de la biblioteca de proveedores de materiales para crear los conjuntos de claves que especifican qué claves protegen sus datos.
La forma de instanciar la biblioteca AWS Encryption SDK y la biblioteca de proveedores de materiales difiere entre las versiones 3. *x y 4*. *x* de AWS Encryption SDK para .NET. Todos los pasos siguientes son los mismos para ambas versiones 3. *x* y 4. *x* de AWS Encryption SDK para .NET.
```
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
```
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Paso 2: crear un objeto de entrada para el conjunto de claves.
Cada método que crea un conjunto de claves tiene una clase de objeto de entrada correspondiente. Por ejemplo, para crear el objeto de entrada para el método `CreateAwsKmsKeyring()`, cree una instancia de la clase `CreateAwsKmsKeyringInput`.
Aunque la entrada de este conjunto de claves no especifica una [clave generadora](use-kms-keyring.md#kms-keyring-encrypt), la única clave KMS especificada por el parámetro `KmsKeyId` es la clave generadora. Genera y cifra la clave de datos que cifra los datos.
Este objeto de entrada requiere un AWS KMS cliente para Región de AWS la clave KMS. Para crear un AWS KMS cliente, cree una instancia de la `AmazonKeyManagementServiceClient` clase en. SDK para .NET Llamar al constructor de `AmazonKeyManagementServiceClient()` sin parámetros crea un cliente con los valores predeterminados.
En un AWS KMS conjunto de claves utilizado para cifrar con .NET, puede [identificar las claves de KMS mediante el](use-kms-keyring.md#kms-keyring-id) ID de clave, el ARN de clave, el nombre de alias o el alias ARN. AWS Encryption SDK En un conjunto de AWS KMS claves utilizado para descifrar, debe usar un ARN de clave para identificar cada clave de KMS. Si piensa reutilizar su conjunto de claves de cifrado para descifrar, utilice un identificador ARN de clave para todas las claves de KMS.
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
Paso 3: crear el conjunto de claves.
Para crear el conjunto de claves, llame al método de conjunto de claves con el objeto de entrada del conjunto de claves. En este ejemplo, se utiliza el método `CreateAwsKmsKeyring()`, que solo necesita una clave de KMS.
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
Paso 4: definir un contexto de cifrado.
Un [contexto de cifrado](concepts.md#encryption-context) es un elemento opcional, pero muy recomendable, de las operaciones criptográficas del. AWS Encryption SDK Puede definir uno o varios pares clave-valor no secretos.
Con la versión 4. *x* AWS Encryption SDK para .NET, puede requerir un contexto de cifrado en todas las solicitudes de cifrado con el [contexto de cifrado requerido CMM](configure.md#config-required-encryption-context-cmm).
```
// Define the encryption context
var encryptionContext = new Dictionary()
{
{"purpose", "test"}
};
```
Paso 5: crear el objeto de entrada para cifrar.
Antes de llamar al método `Encrypt()`, cree una instancia de la clase `EncryptInput`.
```
string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
// Define the encrypt input
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
```
Paso 6: cifrar el texto no cifrado.
Utilice el `Encrypt()` método de AWS Encryption SDK para cifrar el texto sin formato mediante el conjunto de claves que haya definido.
La `EncryptOutput` que devuelve el método `Encrypt() ` contiene métodos para obtener el mensaje cifrado (`Ciphertext`), el contexto de cifrado y el conjunto de algoritmos.
```
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
```
Paso 7: obtener el mensaje cifrado.
El `Decrypt()` método AWS Encryption SDK para .NET toma el `Ciphertext` miembro de la instancia. `EncryptOutput`
El miembro `Ciphertext` del objeto `EncryptOutput` es el [mensaje cifrado](concepts.md#message), un objeto portátil que incluye los datos cifrados, las claves de datos cifrados y los metadatos, incluido el contexto de cifrado. Puede almacenar de forma segura el mensaje cifrado durante un período prolongado o enviarlo al método de `Decrypt()` para recuperar el texto no cifrado.
```
var encryptedMessage = encryptOutput.Ciphertext;
```
## Descifrar en modo estricto en AWS Encryption SDK para.NET
Las prácticas recomendadas recomiendan especificar las claves que se utilizan para descifrar los datos, una opción conocida como *modo estricto*. AWS Encryption SDK Utiliza únicamente las claves KMS que especifique en su conjunto de claves para descifrar el texto cifrado. Las claves del conjunto de claves de descifrado deben incluir al menos una de las claves que cifraron los datos.
En este ejemplo se muestra el patrón básico de descifrado en modo estricto con la AWS Encryption SDK para .NET.
Paso 1: Cree una instancia de la biblioteca y de los proveedores de materiales. AWS Encryption SDK
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Paso 2: crear un objeto de entrada para el conjunto de claves.
Para especificar los parámetros del método de conjunto de claves, cree un objeto de entrada. Cada método de conjunto de claves de .NET tiene un objeto de entrada correspondiente. AWS Encryption SDK Como en este ejemplo se utiliza el método `CreateAwsKmsKeyring()` para crear el conjunto de claves, se crea una instancia de la clase `CreateAwsKmsKeyringInput` para la entrada.
En un conjunto de claves de descifrado, debe usar el ARN de una clave para identificar claves KMS.
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
Paso 3: crear el conjunto de claves.
Para crear el conjunto de claves de descifrado, en este ejemplo se utiliza el método `CreateAwsKmsKeyring()` y el objeto de entrada del conjunto de claves.
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
Paso 4: crear el objeto de entrada para descifrar.
Para crear el objeto de entrada para el método `Decrypt()`, cree una instancia de la clase `DecryptInput`.
El parámetro `Ciphertext` del constructor `DecryptInput()` toma el miembro `Ciphertext` del objeto `EncryptOutput` que devolvió el método `Encrypt()`. La propiedad `Ciphertext` representa el [mensaje cifrado](concepts.md#message), que incluye los datos cifrados, las claves de datos cifrados y los metadatos que la AWS Encryption SDK necesita para descifrar el mensaje.
Con la versión 4. *x* del AWS Encryption SDK para.NET, puede utilizar el `EncryptionContext` parámetro opcional para especificar el contexto de cifrado en el `Decrypt()` método.
Utilice el parámetro `EncryptionContext` para comprobar que el contexto de cifrado utilizado para cifrar *está incluido* en el contexto de cifrado utilizado para descifrar el texto cifrado. AWS Encryption SDK Añade pares al contexto de cifrado, incluida la firma digital si utilizas un conjunto de algoritmos con firma, como el conjunto de algoritmos predeterminado.
```
var encryptedMessage = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = encryptedMessage,
Keyring = keyring,
EncryptionContext = encryptionContext // OPTIONAL
};
```
Paso 5: descifrar el texto cifrado.
```
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
Paso 6: verificar el contexto de cifrado; versión 3.*x*
El `Decrypt()` método de la versión 3. *x* del AWS Encryption SDK para .NET no utiliza un contexto de cifrado. Obtiene los valores del contexto de cifrado de los metadatos en el mensaje cifrado. Sin embargo, antes de devolver o utilizar el texto no cifrado, se recomienda comprobar que el contexto de cifrado que se utilizó para descifrar el texto cifrado incluye el contexto de cifrado que proporcionó al cifrar.
Compruebe que el contexto de cifrado utilizado para cifrar *esté incluido* en el contexto de cifrado que se utilizó para descifrar el texto cifrado. AWS Encryption SDK Agrega pares al contexto de cifrado, incluida la firma digital si se utiliza un conjunto de algoritmos con firma, como el conjunto de algoritmos predeterminado.
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
## Descifrar con un anillo de claves de detección en el para.NET AWS Encryption SDK
En lugar de especificar las claves de KMS para el descifrado, puede proporcionar un *conjunto de claves de detección* de AWS KMS , que es un conjunto de claves que no especifica ninguna clave de KMS. Un anillo de claves de detección permite AWS Encryption SDK descifrar los datos utilizando la clave KMS que los haya cifrado, siempre que la persona que llama tenga permiso para descifrar la clave. Como práctica recomendada, añada un filtro de detección que limite las claves de KMS que se pueden usar a las Cuentas de AWS de una partición específica, en particular.
AWS Encryption SDK Para .NET, se proporciona un conjunto de claves de detección básico que requiere un AWS KMS cliente y un conjunto de claves de detección múltiple que requiere la especificación de uno o más. Regiones de AWS Tanto el cliente como las regiones limitan las claves KMS que se pueden usar para descifrar el mensaje cifrado. Los objetos de entrada de ambos conjuntos de claves utilizan el filtro de detección recomendado.
El siguiente ejemplo muestra el patrón de descifrado de datos con un conjunto de claves de detección de AWS KMS y un filtro de detección.
Paso 1: crear una instancia de la biblioteca AWS Encryption SDK y de la biblioteca de proveedores de materiales.
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
Paso 2: crear el objeto de entrada para el conjunto de claves.
Para especificar los parámetros del método de conjunto de claves, cree un objeto de entrada. Cada método de conjunto de claves de .NET tiene un objeto de entrada correspondiente. AWS Encryption SDK Como en este ejemplo se utiliza el método `CreateAwsKmsDiscoveryKeyring()` para crear el conjunto de claves, se crea una instancia de la clase `CreateAwsKmsDiscoveryKeyringInput` para la entrada.
```
List accounts = new List { "111122223333" };
var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = accounts,
Partition = "aws"
}
};
```
Paso 3: crear el conjunto de claves.
Para crear el conjunto de claves de descifrado, en este ejemplo se utiliza el método `CreateAwsKmsDiscoveryKeyring()` y el objeto de entrada del conjunto de claves.
```
var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);
```
Paso 4: crear el objeto de entrada para descifrar.
Para crear el objeto de entrada para el método `Decrypt()`, cree una instancia de la clase `DecryptInput`. El valor del parámetro `Ciphertext` es el miembro `Ciphertext` del objeto `EncryptOutput` que devuelve el método `Encrypt()`.
Con la versión 4. *x* del AWS Encryption SDK para.NET, puede utilizar el `EncryptionContext` parámetro opcional para especificar el contexto de cifrado en el `Decrypt()` método.
Utilice el parámetro `EncryptionContext` para comprobar que el contexto de cifrado utilizado para cifrar *está incluido* en el contexto de cifrado utilizado para descifrar el texto cifrado. AWS Encryption SDK Añade pares al contexto de cifrado, incluida la firma digital si utilizas un conjunto de algoritmos con firma, como el conjunto de algoritmos predeterminado.
```
var ciphertext = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = discoveryKeyring,
EncryptionContext = encryptionContext // OPTIONAL
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
Paso 5: verificar el contexto de cifrado; versión 3.*x*
El `Decrypt()` método de la versión 3. *x* del AWS Encryption SDK para .NET no incluye un contexto de cifrado`Decrypt()`. Obtiene los valores del contexto de cifrado de los metadatos en el mensaje cifrado. Sin embargo, antes de devolver o utilizar el texto no cifrado, se recomienda comprobar que el contexto de cifrado que se utilizó para descifrar el texto cifrado incluye el contexto de cifrado que proporcionó al cifrar.
Compruebe que el contexto de cifrado utilizado para cifrar *esté incluido* en el contexto de cifrado que se utilizó para descifrar el texto cifrado. AWS Encryption SDK Añade pares al contexto de cifrado, incluida la firma digital si se utiliza un conjunto de algoritmos con firma, como el conjunto de algoritmos predeterminado.
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
# AWS Encryption SDK para Go
En este tema se explica cómo instalar y usar AWS Encryption SDK for Go. Para obtener más información sobre la programación con AWS Encryption SDK for Go, consulte el directorio [go](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/) del aws-encryption-sdk repositorio en GitHub.
AWS Encryption SDK for Go se diferencia de algunas de las implementaciones de otros lenguajes de programación AWS Encryption SDK en los siguientes aspectos:
+ No hay soporte para el almacenamiento en [caché de claves de datos](data-key-caching.md). Sin embargo, AWS Encryption SDK for Go es compatible con el [llavero AWS KMS jerárquico](use-hierarchical-keyring.md), una solución alternativa de almacenamiento en caché de materiales criptográficos.
+ No es compatible con el streaming de datos
El AWS Encryption SDK for Go incluye todas las funciones de seguridad introducidas en las versiones 2.0. *x* y versiones posteriores de las implementaciones en otros idiomas del AWS Encryption SDK. Sin embargo, si utiliza AWS Encryption SDK for Go para descifrar datos cifrados con una versión anterior a la versión 2.0. *x* versión de la implementación en otro idioma de la AWS Encryption SDK, es posible que necesite ajustar su política de [compromisos](concepts.md#commitment-policy). Para obtener más información, consulte [¿Cómo establecer su política de compromiso?](migrate-commitment-policy.md#migrate-commitment-step1).
El AWS Encryption SDK for Go es un producto de [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), un lenguaje de verificación formal en el que se escriben las especificaciones, el código para implementarlas y las pruebas para probarlas. AWS Encryption SDK El resultado es una biblioteca que implementa las características del AWS Encryption SDK en una trama que garantiza la corrección funcional.
**Más información**
+ Para ver ejemplos que muestran cómo configurar las opciones del AWS Encryption SDK, como especificar un conjunto de algoritmos alternativo, limitar las claves de datos cifrados y utilizar claves AWS KMS multirregionales, consulte. [Configuración del AWS Encryption SDK](configure.md)
+ Para ver ejemplos que muestran cómo configurar y usar AWS Encryption SDK for Go, consulta los [ejemplos de Go](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/examples) en el aws-encryption-sdk repositorio correspondiente. GitHub
**Topics**
+ [
## Requisitos previos
](#prerequisites-go)
+ [
## Instalación
](#go-installation)
## Requisitos previos
Antes de instalar AWS Encryption SDK for Go, asegúrese de cumplir los siguientes requisitos previos.
**Una versión compatible de Go**
AWS Encryption SDK Para Go es necesaria la versión 1.23 o posterior.
Para obtener más información sobre la descarga e instalación de Go, consulta [Instalación de Go](https://go.dev/doc/install).
## Instalación
Instala la última versión de AWS Encryption SDK for Go. Para obtener más información sobre la instalación y creación de AWS Encryption SDK for Go, consulta el [archivo README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/README.md) en el directorio go del aws-encryption-sdk repositorio en cuestión. GitHub
**Para instalar la versión más reciente**
+ Instala el for Go AWS Encryption SDK
```
go get github.com/aws/aws-encryption-sdk/releases/go/encryption-sdk@latest
```
+ Instale la [biblioteca de proveedores de material criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL)
```
go get github.com/aws/aws-cryptographic-material-providers-library/releases/go/mpl
```
# SDK de cifrado de AWS para Java
En este tema se explica cómo instalar y utilizar el SDK de cifrado de AWS para Java. Para obtener detalles sobre la programación con SDK de cifrado de AWS para Java, consulte el [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/)repositorio en GitHub. Para obtener documentación de la API, consulte la documentación de [Javadoc](https://aws.github.io/aws-encryption-sdk-java/) para SDK de cifrado de AWS para Java.
**Topics**
+ [
## Requisitos previos
](#java-prerequisites)
+ [
## Instalación
](#java-installation)
+ [Ejemplos](java-example-code.md)
## Requisitos previos
Antes de instalarlo SDK de cifrado de AWS para Java, asegúrese de cumplir los siguientes requisitos previos.
**Un entorno de desarrollo de Java**
Necesitará Java 8 o una versión posterior. En el sitio web de Oracle, vaya a la página de [descargas de Java SE](https://www.oracle.com/java/technologies/downloads/) y, a continuación, descargue e instale el Java SE Development Kit (JDK).
Si utiliza el JDK de Oracle, también debe descargar e instalar los [archivos de políticas de jurisdicción de seguridad ilimitada de la extensión de criptografía de Java (JCE)](http://www.oracle.com/java/technologies/javase-jce8-downloads.html).
**Bouncy Castle**
SDK de cifrado de AWS para Java Requiere [Bouncy Castle.](https://www.bouncycastle.org/download/bouncy-castle-java/)
+ SDK de cifrado de AWS para Java las versiones 1.6.1 y posteriores utilizan Bouncy Castle para serializar y deserializar objetos criptográficos. Puede utilizar Bouncy Castle o [Bouncy Castle FIPS](https://www.bouncycastle.org/about/bouncy-castle-fips-faq/) para cumplir este requisito. ****Si necesita ayuda para instalar y configurar el FIPS de Bouncy Castle, consulte la [documentación del FIPS de BC](https://www.bouncycastle.org/documentation/), especialmente las guías de usuario y la política de seguridad.**** PDFs
+ Las versiones anteriores SDK de cifrado de AWS para Java utilizan la API de criptografía de Bouncy Castle para Java. Este requisito solo se cumple con el Bouncy Castle que no es de FIPS.
Si no tienes Bouncy Castle, ve a [Descargar Bouncy Castle para Java para](https://bouncycastle.org/download/bouncy-castle-java/) descargar el archivo del proveedor correspondiente a tu JDK. [También puedes usar [Apache Maven](https://maven.apache.org/) para obtener el artefacto para el proveedor estándar de Bouncy Castle ([bcprov-ext-jdk15on](https://mvnrepository.com/artifact/org.bouncycastle/bcprov-ext-jdk15on)) o el artefacto para Bouncy Castle FIPS (bc-fips).](https://mvnrepository.com/artifact/org.bouncycastle/bc-fips)
**AWS SDK para Java**
Versión 3. *x* de los SDK de cifrado de AWS para Java requiere el AWS SDK for Java 2.x, incluso si no usas AWS KMS llaveros.
Versión 2. *x* o una versión anterior de SDK de cifrado de AWS para Java no requiere la AWS SDK para Java. Sin embargo, AWS SDK para Java es necesario para usar [AWS Key Management Service](https://aws.amazon.com/kms/)(AWS KMS) como proveedor de claves maestras. A partir de la SDK de cifrado de AWS para Java versión 2.4.0, SDK de cifrado de AWS para Java es compatible con las versiones 1.x y 2.x de. AWS SDK para Java AWS Encryption SDK el código de la AWS SDK para Java 1.x y la 2.x es interoperable. Por ejemplo, puede cifrar los datos con un AWS Encryption SDK código compatible con la versión AWS SDK para Java 1.x y descifrarlos con un código compatible AWS SDK for Java 2.x (o viceversa). Las versiones anteriores a la 2.4.0 SDK de cifrado de AWS para Java solo admiten la versión 1.x. AWS SDK para Java Para obtener información sobre cómo actualizar su versión de AWS Encryption SDK, consulte. [Migración de su AWS Encryption SDK](migration.md)
Al actualizar el SDK de cifrado de AWS para Java código de la versión AWS SDK para Java 1.x a AWS SDK for Java 2.x, sustituya las referencias a la [`AWSKMS`interfaz](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/kms/package-summary.html) de la versión AWS SDK para Java 1.x por las referencias a la [`KmsClient`interfaz](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/package-summary.html) de. AWS SDK for Java 2.x[No SDK de cifrado de AWS para Java es compatible con la `KmsAsyncClient` interfaz.](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/KmsAsyncClient.html) Además, actualice el código para usar los objetos relacionados al AWS KMS en el espacio de nombres de `kmssdkv2`, en lugar del espacio de nombres de `kms`.
Para instalar AWS SDK para Java, utilice Apache Maven.
+ Para [importar todo el AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#build-the-entire-sdk-into-your-project) como una dependencia declárelo en el archivo `pom.xml`.
+ Para crear una dependencia solo para el AWS KMS módulo de la AWS SDK para Java versión 1.x, siga las instrucciones para [especificar determinados módulos](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-project-maven.html#modules-dependencies) y establezca el `artifactId` valor. `aws-java-sdk-kms`
+ Para crear una dependencia solo para el AWS KMS módulo de la versión AWS SDK para Java 2.x, siga las instrucciones para [especificar módulos concretos](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#modules-dependencies). Establece el `groupId` en `software.amazon.awssdk` y el `artifactId` en `kms`.
Para ver más cambios, consulta las [diferencias entre la versión AWS SDK para Java 1.x y la 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-whats-different.html) en la AWS SDK for Java 2.x Guía para desarrolladores.
Los ejemplos de Java de la Guía AWS Encryption SDK para desarrolladores utilizan el. AWS SDK for Java 2.x
## Instalación
Instale la versión más reciente de SDK de cifrado de AWS para Java.
**nota**
Todas las versiones SDK de cifrado de AWS para Java anteriores a la 2.0.0 se encuentran en esta [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 Java 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 AWS Encryption SDK. Para obtener más información, consulte [Migrando su AWS Encryption SDK](migration.md).
Puede instalarlo de SDK de cifrado de AWS para Java las siguientes maneras.
**Manualmente**
Para instalarlo SDK de cifrado de AWS para Java, clone o descargue el [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) GitHubrepositorio.
**Con Apache Maven**
SDK de cifrado de AWS para Java Está disponible a través de [Apache Maven](https://maven.apache.org/) con la siguiente definición de dependencia.
```
com.amazonawsaws-encryption-sdk-java3.0.0
```
Después de instalar el SDK, comience consultando el [ejemplo de código Java](java-example-code.md) de esta guía y el [Javadoc](https://aws.github.io/aws-encryption-sdk-java/) que aparece en él. GitHub
# SDK de cifrado de AWS para Java ejemplos
Los siguientes ejemplos muestran cómo utilizarlos SDK de cifrado de AWS para Java para cifrar y descifrar datos. Estos ejemplos muestran cómo utilizar la versión 3. *x* y versiones posteriores de SDK de cifrado de AWS para Java. Versión 3. *x* de los SDK de cifrado de AWS para Java requiere el AWS SDK for Java 2.x. Versión 3. *x* de SDK de cifrado de AWS para Java reemplaza a los [proveedores de llaves maestras](concepts.md#master-key-provider) por [llaveros](concepts.md#keyring). Para ver ejemplos que utilizan versiones anteriores, busca tu versión en la lista de [versiones](https://github.com/aws/aws-encryption-sdk-java/releases) del [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/)repositorio de GitHub.
**Topics**
+ [Cadenas](#java-example-strings)
+ [Secuencias de bytes](#java-example-streams)
+ [Secuencias de bytes con varios proveedores de claves maestras](#java-example-multiple-providers)
## Cifrado y descifrado de cadenas
En el siguiente ejemplo, se muestra cómo utilizar la versión 3. *x* de SDK de cifrado de AWS para Java para cifrar y descifrar cadenas. Antes de usar la cadena, conviértala en una matriz de bytes.
[En este ejemplo se utiliza un AWS KMS anillo de claves.](use-kms-keyring.md) Al cifrar con un AWS KMS anillo de claves, puede usar un ID de clave, un ARN de clave, un nombre de alias o un ARN de alias para identificar las claves de KMS. Al descifrar, debe utilizar una clave ARN para identificar las claves de KMS.
Cuando se llama al método `encryptData()`, este devuelve un [mensaje cifrado](concepts.md#message) (`CryptoResult`) que incluye el texto cifrado, las claves de datos cifradas y el contexto de cifrado. Cuando llama a `getResult` en el objeto `CryptoResult`, se devuelve una versión de cadena codificada en base 64 del [mensaje cifrado](message-format.md) que puede pasar al método `decryptData()`.
Del mismo modo, cuando llamas`decryptData()`, el `CryptoResult` objeto que devuelve contiene el mensaje de texto sin formato y un identificador. AWS KMS key Antes de que la aplicación devuelva el texto sin formato, compruebe que el AWS KMS key identificador y el contexto de cifrado del mensaje cifrado son los esperados.
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoResult;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Collections;
import java.util.Map;
/**
* Encrypts and then decrypts data using an AWS KMS Keyring.
*
*
Arguments:
*
*
*
Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS customer master
* key (CMK), see 'Viewing Keys' at
* http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
*
*/
public class BasicEncryptionKeyringExample {
private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8);
public static void main(final String[] args) {
final String keyArn = args[0];
encryptAndDecryptWithKeyring(keyArn);
}
public static void encryptAndDecryptWithKeyring(final String keyArn) {
// 1. Instantiate the SDK
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto =
AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput =
CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build();
final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create an encryption context
// We recommend using an encryption context whenever possible
// to protect integrity. This sample uses placeholder values.
// For more information see:
// blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management
final Map encryptionContext =
Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
// 4. Encrypt the data
final CryptoResult encryptResult =
crypto.encryptData(kmsKeyring, EXAMPLE_DATA, encryptionContext);
final byte[] ciphertext = encryptResult.getResult();
// 5. Decrypt the data
final CryptoResult decryptResult =
crypto.decryptData(
kmsKeyring,
ciphertext,
// Verify that the encryption context in the result contains the
// encryption context supplied to the encryptData method
encryptionContext);
// 6. Verify that the decrypted plaintext matches the original plaintext
assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
}
}
```
## Cifrado y descifrado de secuencias de bytes
En el siguiente ejemplo, se muestra cómo utilizarlos AWS Encryption SDK para cifrar y descifrar secuencias de bytes.
En este ejemplo se utiliza un anillo de claves [AES sin procesar.](use-raw-aes-keyring.md)
Al cifrar, en este ejemplo se utiliza el método `AwsCrypto.builder() .withEncryptionAlgorithm()` para especificar un conjunto de algoritmos sin [firmas digitales.](concepts.md#digital-sigs) Al descifrar, para garantizar que el texto cifrado no esté firmado, en este ejemplo se utiliza el método `createUnsignedMessageDecryptingStream()`. El `createUnsignedMessageDecryptingStream()` método falla si encuentra un texto cifrado con una firma digital.
Si está cifrando con el conjunto de algoritmos predeterminado, que incluye firmas digitales, utilice el método `createDecryptingStream()` en su lugar, como se muestra en el siguiente ejemplo.
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoAlgorithm;
import com.amazonaws.encryptionsdk.CryptoInputStream;
import com.amazonaws.encryptionsdk.jce.JceMasterKey;
import com.amazonaws.util.IOUtils;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.AesWrappingAlg;
import software.amazon.cryptography.materialproviders.model.CreateRawAesKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.security.SecureRandom;
import java.util.Collections;
import java.util.Map;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
/**
*
* Encrypts and then decrypts a file under a random key.
*
*
* Arguments:
*
*
Name of file containing plaintext data to encrypt
*
*
*
* This program demonstrates using a standard Java {@link SecretKey} object as a {@link IKeyring} to
* encrypt and decrypt streaming data.
*/
public class FileStreamingKeyringExample {
private static String srcFile;
public static void main(String[] args) throws IOException {
srcFile = args[0];
// In this example, we generate a random key. In practice,
// you would get a key from an existing store
SecretKey cryptoKey = retrieveEncryptionKey();
// Create a Raw Aes Keyring using the random key and an AES-GCM encryption algorithm
final MaterialProviders materialProviders = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
.wrappingKey(ByteBuffer.wrap(cryptoKey.getEncoded()))
.keyNamespace("Example")
.keyName("RandomKey")
.wrappingAlg(AesWrappingAlg.ALG_AES128_GCM_IV12_TAG16)
.build();
IKeyring keyring = materialProviders.CreateRawAesKeyring(keyringInput);
// Instantiate the SDK.
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
// This example encrypts with an algorithm suite that doesn't include signing for faster decryption,
// since this use case assumes that the contexts that encrypt and decrypt are equally trusted.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
.build();
// Create an encryption context to identify the ciphertext
Map context = Collections.singletonMap("Example", "FileStreaming");
// Because the file might be too large to load into memory, we stream the data, instead of
//loading it all at once.
FileInputStream in = new FileInputStream(srcFile);
CryptoInputStream encryptingStream = crypto.createEncryptingStream(keyring, in, context);
FileOutputStream out = new FileOutputStream(srcFile + ".encrypted");
IOUtils.copy(encryptingStream, out);
encryptingStream.close();
out.close();
// Decrypt the file. Verify the encryption context before returning the plaintext.
// Since the data was encrypted using an unsigned algorithm suite, use the recommended
// createUnsignedMessageDecryptingStream method, which only accepts unsigned messages.
in = new FileInputStream(srcFile + ".encrypted");
CryptoInputStream decryptingStream = crypto.createUnsignedMessageDecryptingStream(keyring, in);
// Does it contain the expected encryption context?
if (!"FileStreaming".equals(decryptingStream.getCryptoResult().getEncryptionContext().get("Example"))) {
throw new IllegalStateException("Bad encryption context");
}
// Write the plaintext data to disk.
out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
out.close();
}
/**
* In practice, this key would be saved in a secure location.
* For this demo, we generate a new random key for each operation.
*/
private static SecretKey retrieveEncryptionKey() {
SecureRandom rnd = new SecureRandom();
byte[] rawKey = new byte[16]; // 128 bits
rnd.nextBytes(rawKey);
return new SecretKeySpec(rawKey, "AES");
}
}
```
## Cifrar y descifrar secuencias de bytes con un conjunto de claves múltiples
[En el siguiente ejemplo, se muestra cómo utilizarla con un conjunto de claves múltiples. AWS Encryption SDK](use-multi-keyring.md) Cuando se utiliza un conjunto de claves múltiple para cifrar datos, cualquiera de las claves de encapsulamiento en cualquiera de los conjuntos de claves puede descifrar dichos datos. En este ejemplo, se utiliza un [AWS KMS llavero](use-kms-keyring.md) y un llavero [RSA sin procesar como llaveros secundarios.](use-raw-rsa-keyring.md)
En este ejemplo, se cifra con el [conjunto de algoritmos predeterminado](supported-algorithms.md), que incluye una [firma digital](concepts.md#digital-sigs). Al transmitir, AWS Encryption SDK publica el texto sin formato después de las comprobaciones de integridad, pero antes de comprobar la firma digital. Para evitar utilizar el texto no cifrado hasta que se compruebe la firma, en este ejemplo se almacena el texto no cifrado en búfer y se graba en el disco únicamente cuando se han completado el descifrado y la verificación.
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoOutputStream;
import com.amazonaws.util.IOUtils;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.CreateMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.CreateRawRsaKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import software.amazon.cryptography.materialproviders.model.PaddingScheme;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
import java.security.GeneralSecurityException;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.util.Collections;
/**
*
* Encrypts a file using both AWS KMS Key and an asymmetric key pair.
*
*
* Arguments:
*
*
Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS key,
* see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
*
*
Name of file containing plaintext data to encrypt
*
*
* You might use AWS Key Management Service (AWS KMS) for most encryption and decryption operations, but
* still want the option of decrypting your data offline independently of AWS KMS. This sample
* demonstrates one way to do this.
*
* The sample encrypts data under both an AWS KMS key and an "escrowed" RSA key pair
* so that either key alone can decrypt it. You might commonly use the AWS KMS key for decryption. However,
* at any time, you can use the private RSA key to decrypt the ciphertext independent of AWS KMS.
*
* This sample uses the RawRsaKeyring to generate a RSA public-private key pair
* and saves the key pair in memory. In practice, you would store the private key in a secure offline
* location, such as an offline HSM, and distribute the public key to your development team.
*/
public class EscrowedEncryptKeyringExample {
private static ByteBuffer publicEscrowKey;
private static ByteBuffer privateEscrowKey;
public static void main(final String[] args) throws Exception {
// This sample generates a new random key for each operation.
// In practice, you would distribute the public key and save the private key in secure
// storage.
generateEscrowKeyPair();
final String kmsArn = args[0];
final String fileName = args[1];
standardEncrypt(kmsArn, fileName);
standardDecrypt(kmsArn, fileName);
escrowDecrypt(fileName);
}
private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception {
// Encrypt with the KMS key and the escrowed public key
// 1. Instantiate the SDK
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(kmsArn)
.build();
IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create the Raw Rsa Keyring with Public Key.
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.build();
IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 4. Create the multi-keyring.
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(kmsKeyring)
.childKeyrings(Collections.singletonList(rsaPublicKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
// 5. Encrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName);
final FileOutputStream out = new FileOutputStream(fileName + ".encrypted");
final CryptoOutputStream encryptingStream = crypto.createEncryptingStream(multiKeyring, out);
IOUtils.copy(in, encryptingStream);
in.close();
encryptingStream.close();
}
private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception {
// Decrypt with the AWS KMS key and the escrow public key.
// 1. Instantiate the SDK.
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(kmsArn)
.build();
IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create the Raw Rsa Keyring with Public Key.
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.build();
IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 4. Create the multi-keyring.
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(kmsKeyring)
.childKeyrings(Collections.singletonList(rsaPublicKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
// 5. Decrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName + ".encrypted");
final FileOutputStream out = new FileOutputStream(fileName + ".decrypted");
// Since we are using a signing algorithm suite, we avoid streaming decryption directly to the output file,
// to ensure that the trailing signature is verified before writing any untrusted plaintext to disk.
final ByteArrayOutputStream plaintextBuffer = new ByteArrayOutputStream();
final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(multiKeyring, plaintextBuffer);
IOUtils.copy(in, decryptingStream);
in.close();
decryptingStream.close();
final ByteArrayInputStream plaintextReader = new ByteArrayInputStream(plaintextBuffer.toByteArray());
IOUtils.copy(plaintextReader, out);
out.close();
}
private static void escrowDecrypt(final String fileName) throws Exception {
// You can decrypt the stream using only the private key.
// This method does not call AWS KMS.
// 1. Instantiate the SDK
final AwsCrypto crypto = AwsCrypto.standard();
// 2. Create the Raw Rsa Keyring with Private Key.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.privateKey(privateEscrowKey)
.build();
IKeyring escrowPrivateKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 3. Decrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName + ".encrypted");
final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed");
final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(escrowPrivateKeyring, out);
IOUtils.copy(in, decryptingStream);
in.close();
decryptingStream.close();
}
private static void generateEscrowKeyPair() throws GeneralSecurityException {
final KeyPairGenerator kg = KeyPairGenerator.getInstance("RSA");
kg.initialize(4096); // Escrow keys should be very strong
final KeyPair keyPair = kg.generateKeyPair();
publicEscrowKey = RawRsaKeyringExample.getPEMPublicKey(keyPair.getPublic());
privateEscrowKey = RawRsaKeyringExample.getPEMPrivateKey(keyPair.getPrivate());
}
}
```
# SDK de cifrado de AWS para JavaScript
SDK de cifrado de AWS para JavaScript Está diseñado para proporcionar una biblioteca de cifrado del lado del cliente para los desarrolladores que escriben aplicaciones de navegador web JavaScript o aplicaciones de servidor web en Node.js.
Como todas las implementaciones del AWS Encryption SDK, SDK de cifrado de AWS para JavaScript ofrece funciones avanzadas de 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 AWS Encryption SDK están diseñadas para ser interoperables, sujetas a las limitaciones del idioma. Para obtener más información sobre las restricciones lingüísticas, consulte. JavaScript [Compatibilidad del SDK de cifrado de AWS para JavaScript](javascript-compatibility.md)
**Más información**
+ Para obtener más información sobre la programación con SDK de cifrado de AWS para JavaScript, consulte el [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)repositorio en GitHub.
+ Para ver ejemplos de programación, consulte [SDK de cifrado de AWS para JavaScript ejemplos](js-examples.md) los módulos [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) y [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) del repositorio. [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)
+ Para ver un ejemplo práctico del uso del código SDK de cifrado de AWS para JavaScript para cifrar datos en una aplicación web, consulte [Cómo habilitar el cifrado en un navegador con el archivo Node.js en el SDK de cifrado de AWS para JavaScript blog](https://aws.amazon.com/blogs/security/how-to-enable-encryption-browser-aws-encryption-sdk-javascript-node-js/) de seguridad. AWS
**Topics**
+ [Compatibilidad](javascript-compatibility.md)
+ [Instalación](javascript-installation.md)
+ [Módulos](javascript-modules.md)
+ [Ejemplos](js-examples.md)
# Compatibilidad del SDK de cifrado de AWS para JavaScript
SDK de cifrado de AWS para JavaScript Está diseñado para ser interoperable con las implementaciones de otros idiomas del. AWS Encryption SDK[En la mayoría de los casos, puede cifrar los datos SDK de cifrado de AWS para JavaScript y descifrarlos con cualquier implementación en otro idioma, incluida la AWS Encryption SDK interfaz de línea de comandos.](crypto-cli.md) Y puede utilizarla SDK de cifrado de AWS para JavaScript para descifrar los [mensajes cifrados](concepts.md#message) producidos por las implementaciones del en otros idiomas. AWS Encryption SDK
Sin embargo, cuando utilice el SDK de cifrado de AWS para JavaScript, debe tener en cuenta algunos problemas de compatibilidad en la implementación del JavaScript idioma y en los navegadores web.
Además, cuando utilice implementaciones de lenguaje diferentes, asegúrese de configurar proveedores de claves maestras, claves maestras y conjuntos de claves compatibles. Para obtener más información, consulte [Compatibilidad de conjuntos de claves](choose-keyring.md#keyring-compatibility).
## SDK de cifrado de AWS para JavaScript compatibilidad
La JavaScript implementación de la AWS Encryption SDK se diferencia de las implementaciones de otros lenguajes en los siguientes aspectos:
+ La operación de cifrado del SDK de cifrado de AWS para JavaScript no devuelve texto cifrado no enmarcado. Sin embargo, SDK de cifrado de AWS para JavaScript descifrará el texto cifrado enmarcado y no enmarcado devuelto por las implementaciones del. AWS Encryption SDK
+ A partir de Node.js versión 12.9.0, Node.js admite las siguientes opciones de encapsulamiento de claves de RSA:
+ OAEP con,, o SHA1 SHA256 SHA384 SHA512
+ OAEP con y con SHA1 MGF1 SHA1
+ PKCS1v15
+ Antes de la versión 12.9.0, Node.js admitía las siguientes opciones de encapsulamiento de claves de RSA:
+ OAEP con y con SHA1 MGF1 SHA1
+ PKCS1v15
## Compatibilidad del navegador
Algunos navegadores web no admiten operaciones criptográficas básicas que el SDK de cifrado de AWS para JavaScript requiere. Puede compensar algunas de las operaciones faltantes configurando una alternativa para la WebCrypto API que implementa el navegador.
**Limitaciones del explorador web**
Las siguientes limitaciones son comunes a todos los navegadores web:
+ La WebCrypto API no admite el empaquetado de PKCS1v15 claves.
+ Los navegadores no admiten claves de 192 bits.
**Operaciones criptográficas requeridas**
SDK de cifrado de AWS para JavaScript Requiere las siguientes operaciones en los navegadores web. Si un navegador no las admite, es incompatible con el SDK de cifrado de AWS para JavaScript.
+ El navegador debe incluir `crypto.getRandomValues()`, que es un método para generar valores criptográficamente aleatorios. Para obtener información sobre las versiones de navegadores web compatibles`crypto.getRandomValues()`, consulte [¿Puedo usar criptomonedas? getRandomValues()?](https://caniuse.com/#feat=getrandomvalues) .
**Reserva obligatoria**
SDK de cifrado de AWS para JavaScript Requiere las siguientes bibliotecas y operaciones en los navegadores web. Si admite un navegador web que no cumple estos requisitos, debe configurar una reserva. De lo contrario, los intentos de SDK de cifrado de AWS para JavaScript utilizarla con el navegador fallarán.
+ La WebCrypto API, que realiza operaciones criptográficas básicas en aplicaciones web, no está disponible para todos los navegadores. Para obtener información acerca de las versiones del explorador web que admiten la criptografía web, vea [¿Puedo utilizar criptografía web?](https://caniuse.com/#feat=cryptography).
+ Las versiones modernas del navegador web Safari no admiten el cifrado AES-GCM de cero bytes, que sí es obligatorio. AWS Encryption SDK Si el navegador implementa la WebCrypto API, pero no puede usar AES-GCM para cifrar cero bytes, SDK de cifrado de AWS para JavaScript utiliza la biblioteca alternativa solo para el cifrado de cero bytes. Utiliza la API para todas las demás operaciones. WebCrypto
Para configurar una reserva para cualquiera de las limitaciones, agregue las instrucciones siguientes al código. En la función [configureFallback](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/web-crypto-backend/src/backend-factory.ts#L78), especifique una biblioteca que admita las características que faltan. En el siguiente ejemplo, se utiliza la biblioteca de JavaScript criptografía de Microsoft Research (`msrcrypto`), pero puede sustituirla por una biblioteca compatible. Para ver un ejemplo completo, consulte [fallback.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/fallback.ts).
```
import { configureFallback } from '@aws-crypto/client-browser'
configureFallback(msrCrypto)
```
# Instalación del SDK de cifrado de AWS para JavaScript
SDK de cifrado de AWS para JavaScript Consiste en una colección de módulos interdependientes. Varios de los módulos son solo colecciones de módulos diseñados para trabajar juntos. Algunos módulos están diseñados para funcionar de forma independiente. Unos cuantos módulos son de uso obligatorio en todas las implementaciones; mientras que otros solo se usan en casos especiales. Para obtener información sobre los módulos del AWS Encryption SDK formulario JavaScript, consulte [Módulos del SDK de cifrado de AWS para JavaScript](javascript-modules.md) y el `README.md` archivo de cada uno de los módulos del [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules)repositorio en GitHub.
**nota**
Todas las versiones SDK de cifrado de AWS para JavaScript 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 JavaScript 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 JavaScript. Para obtener más información, consulte [Migrando su AWS Encryption SDK](migration.md).
Para instalar los módulos, utilice el [administrador de paquetes npm](https://www.npmjs.com/get-npm).
Por ejemplo, para instalar el `client-node` módulo, que incluye todos los módulos que necesita programar con el SDK de cifrado de AWS para JavaScript archivo Node.js, utilice el siguiente comando.
```
npm install @aws-crypto/client-node
```
Para instalar el `client-browser` módulo, que incluye todos los módulos que necesite programar SDK de cifrado de AWS para JavaScript en el navegador, utilice el siguiente comando.
```
npm install @aws-crypto/client-browser
```
Para ver ejemplos prácticos de cómo utilizar el SDK de cifrado de AWS para JavaScript, consulte los ejemplos de los `example-browser` módulos `example-node` y del [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)repositorio correspondiente GitHub.
# Módulos del SDK de cifrado de AWS para JavaScript
Los módulos del SDK de cifrado de AWS para JavaScript facilitan la instalación del código que necesita para sus proyectos.
## Módulos para JavaScript Node.js
[client-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-node)
Incluye todos los módulos que necesita para programar con Node.js. SDK de cifrado de AWS para JavaScript
[caching-materials-manager-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-node)
Exporta las funciones que admiten la función de almacenamiento en [caché de claves de datos](data-key-caching.md) de SDK de cifrado de AWS para JavaScript Node.js.
[decrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-node)
Exporta funciones que descifran y verifican mensajes cifrados que representan datos y flujo de datos. Incluido en el módulo `client-node`.
[encrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-node)
Exporta funciones que cifran y firman diferentes tipos de datos. Incluido en el módulo `client-node`.
[example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node)
Exporta ejemplos prácticos de programación con Node.js. SDK de cifrado de AWS para JavaScript Incluye ejemplos de diferentes tipos de conjuntos de claves y diferentes tipos de datos.
[hkdf-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/hkdf-node)
Exporta una [función de derivación de claves (HKDF) basada en HMAC](https://en.wikipedia.org/wiki/HKDF) que se utiliza SDK de cifrado de AWS para JavaScript en Node.js en determinados conjuntos de algoritmos. SDK de cifrado de AWS para JavaScript En el navegador, utiliza la función HKDF nativa de la API. WebCrypto
[integration-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-node)
Define las pruebas que comprueban que SDK de cifrado de AWS para JavaScript el archivo Node.js es compatible con las implementaciones en otros idiomas del. AWS Encryption SDK
[kms-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-node)
Exporta las funciones que admiten los AWS KMS llaveros en Node.js.
[raw-aes-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-node)
Exporta funciones que admiten [conjuntos de claves de AES sin formato](use-raw-aes-keyring.md) en Node.js.
[raw-rsa-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-node)
Exporta funciones que admiten [conjuntos de claves de RSA sin formato](use-raw-rsa-keyring.md) en Node.js.
## Módulos para navegador JavaScript
[client-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-browser)
Incluye todos los módulos que necesitas para programar con ellos SDK de cifrado de AWS para JavaScript en el navegador.
[caching-materials-manager-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-browser)
Exporta las funciones que admiten la función de almacenamiento JavaScript en [caché de claves de datos](data-key-caching.md) del navegador.
[decrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-browser)
Exporta funciones que descifran y verifican mensajes cifrados que representan datos y flujo de datos.
[encrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-browser)
Exporta funciones que cifran y firman diferentes tipos de datos.
[example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser)
Ejemplos prácticos de programación con SDK de cifrado de AWS para JavaScript el navegador. Incluye ejemplos de diferentes tipos de conjuntos de claves y diferentes tipos de datos.
[integration-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-browser)
Define las pruebas que verifican que el SDK de cifrado de AWS para Java script del navegador es compatible con las implementaciones en otros lenguajes del AWS Encryption SDK.
[kms-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-browser)
Exporta funciones que admiten [conjuntos de claves de AWS KMS](use-kms-keyring.md) en el navegador.
[raw-aes-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-browser)
Exporta funciones que admiten [conjuntos de claves de AES sin formato](use-raw-aes-keyring.md) en el navegador.
[raw-rsa-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-browser)
Exporta funciones que admiten [conjuntos de claves de RSA sin formato](use-raw-rsa-keyring.md) en el navegador.
## Módulos para todas las implementaciones
[cache-material](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/cache-material)
Admite la característica de [almacenamiento en caché de claves de datos](data-key-caching.md). Proporciona código para ensamblar los materiales criptográficos que se almacenan en caché con cada clave de datos.
[kms-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring)
Exporta funciones que admiten [conjuntos de claves KMS](use-kms-keyring.md).
[material-management](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/material-management)
Implementa el [administrador de materiales criptográficos](concepts.md#crypt-materials-manager) (CMM).
[raw-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-keyring)
Exporta funciones necesarias para los conjuntos de claves de AES y RSA sin formato.
[serialize](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/serialize)
Exporta funciones que el SDK utiliza para serializar su salida.
[web-crypto-backend](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/web-crypto-backend)
Exporta las funciones que utilizan la WebCrypto API SDK de cifrado de AWS para JavaScript del navegador.
# SDK de cifrado de AWS para JavaScript ejemplos
En los siguientes ejemplos se muestra cómo utilizar el SDK de cifrado de AWS para JavaScript para cifrar y descifrar datos.
Puedes encontrar más ejemplos de su uso SDK de cifrado de AWS para JavaScript en los módulos [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) y [example-browser del repositorio](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) de. [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) GitHub Estos módulos de ejemplo no se instalan al instalar los módulos `client-browser` o `client-node`.
**Consulte los ejemplos de código completos**: Nodo: [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts), Navegador: [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts)
**Topics**
+ [
## Cifrar datos con un anillo de claves AWS KMS
](#javascript-example-encrypt)
+ [
## Descifrar datos con un anillo de claves AWS KMS
](#javascript-example-decrypt)
## Cifrar datos con un anillo de claves AWS KMS
En el siguiente ejemplo, se muestra cómo utilizar el SDK de cifrado de AWS para JavaScript para cifrar y descifrar una cadena corta o una matriz de bytes.
Este ejemplo incluye un [AWS KMS anillo de claves](use-kms-keyring.md), un tipo de anillo de claves que utiliza un AWS KMS key para generar y cifrar claves de datos. *Si necesitas ayuda para crear una AWS KMS key, consulta la sección [Creación de claves](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) en la AWS Key Management Service Guía para desarrolladores.* Para obtener ayuda para identificarlas AWS KMS keys en un AWS KMS llavero, consulte [Identificarse AWS KMS keys en un AWS KMS llavero](use-kms-keyring.md#kms-keyring-id)
Paso 1: Establece la política de compromiso.
A partir de la versión 1.7. *x* del SDK de cifrado de AWS para JavaScript, puede establecer la política de compromiso al llamar a la nueva `buildClient` función que crea una instancia de un AWS Encryption SDK cliente. La función `buildClient` toma un valor enumerado que representa su política de compromiso. Devuelve funciones actualizadas `encrypt` y `decrypt` que hacen cumplir su política de compromiso al cifrar y descifrar.
En los siguientes ejemplos, se utiliza la `buildClient` función para especificar la [política de compromiso predeterminada](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` También puede utilizarla `buildClient` para limitar el número de claves de datos cifradas en un mensaje cifrado. Para obtener más información, consulte [Limitar las claves de datos cifrados](configure.md#config-limit-keys).
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
Paso 2: crear el conjunto de claves.
Cree un conjunto de AWS KMS claves para el cifrado.
Al cifrar con un AWS KMS anillo de claves, debe especificar una *clave generadora*, es decir, una AWS KMS key que se utilice para generar la clave de datos en texto plano y cifrarla. También puede especificar cero o más *claves adicionales* que cifren la misma clave de datos en texto no cifrado. El anillo de claves devuelve la clave de datos en texto plano y una copia cifrada de esa clave de datos para cada AWS KMS key uno de los componentes del conjunto de claves, incluida la clave generadora. Para descifrar los datos, debe descifrar cualquiera de las claves de datos cifradas.
Para especificar el AWS KMS keys anillo de claves de cifrado en SDK de cifrado de AWS para JavaScript, puede utilizar [cualquier](use-kms-keyring.md#kms-keyring-id) identificador de clave compatible. AWS KMS En este ejemplo se utiliza una clave generadora, que se identifica mediante su [ARN de alias](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN) y una clave adicional, que se identifica mediante un [ARN de clave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).
Si piensa reutilizar el AWS KMS anillo de claves para descifrar, debe utilizar la clave para ARNs identificarlo AWS KMS keys en el anillo de claves.
Antes de ejecutar este código, sustituya los identificadores de ejemplo por AWS KMS key identificadores válidos. Debe tener los [permisos necesarios para usar el AWS KMS keys](use-kms-keyring.md#kms-keyring-permissions) en el conjunto de claves.
Comience por proporcionar sus credenciales al navegador. [Los SDK de cifrado de AWS para JavaScript ejemplos utilizan el paquete web. DefinePlugin](https://webpack.js.org/plugins/define-plugin/), que reemplaza las constantes de las credenciales por las credenciales reales. También puede usar cualquier otro método para proporcionar sus credenciales. A continuación, utilice las credenciales para crear un AWS KMS cliente.
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
A continuación, especifique AWS KMS keys la clave del generador y la clave adicional. A continuación, cree un AWS KMS conjunto de claves con el AWS KMS cliente y el AWS KMS keys.
```
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })
```
```
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
```
Paso 3: Defina 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.
Cree un objeto simple que incluya los pares de contexto de cifrado. La clave y el valor de cada par deben ser una cadena.
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
Paso 4: Cifra los datos.
Para cifrar los datos en texto no cifrado, llame a la función `encrypt`. Introduzca el conjunto de AWS KMS claves, los datos en texto plano y el contexto de cifrado.
La función `encrypt` devuelve un [mensaje cifrado](concepts.md#message) (`result`) que contiene los datos cifrados, las claves de datos cifradas y los metadatos importantes, como el contexto de cifrado y la firma.
Puede [descifrar este mensaje cifrado](#javascript-example-decrypt) utilizando cualquier lenguaje AWS Encryption SDK de programación compatible.
```
const plaintext = new Uint8Array([1, 2, 3, 4, 5])
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
```
const plaintext = 'asdf'
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
## Descifrar datos con un anillo de claves AWS KMS
Puede usarlo SDK de cifrado de AWS para JavaScript para descifrar el mensaje cifrado y recuperar los datos originales.
En este ejemplo, desciframos los datos que hemos cifrado en el ejemplo [Cifrar datos con un anillo de claves AWS KMS](#javascript-example-encrypt).
Paso 1: Establece la política de compromiso.
A partir de la versión 1.7. *x* del SDK de cifrado de AWS para JavaScript, puede establecer la política de compromiso al llamar a la nueva `buildClient` función que crea una instancia de un AWS Encryption SDK cliente. La función `buildClient` toma un valor enumerado que representa su política de compromiso. Devuelve funciones actualizadas `encrypt` y `decrypt` que hacen cumplir su política de compromiso al cifrar y descifrar.
En los siguientes ejemplos, se utiliza la `buildClient` función para especificar la [política de compromiso predeterminada](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` También puede utilizarla `buildClient` para limitar el número de claves de datos cifradas en un mensaje cifrado. Para obtener más información, consulte [Limitar las claves de datos cifrados](configure.md#config-limit-keys).
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
Paso 2: crear el conjunto de claves.
Para descifrar los datos, pase el [mensaje cifrado](concepts.md#message) (`result`) que la función `encrypt` ha devuelto. El mensaje cifrado contiene los datos cifrados, las claves de datos cifradas y metadatos importantes, como el contexto de cifrado y la firma.
También debe especificar un [conjunto de claves de AWS KMS](use-kms-keyring.md) al descifrar. Puede utilizar el mismo conjunto de claves que se utilizó para cifrar los datos u otro conjunto de claves. Para tener éxito, al menos una AWS KMS key de las claves de descifrado debe poder descifrar una de las claves de datos cifradas del mensaje cifrado. Dado que no se generan claves de datos, no es necesario especificar una clave generadora en un conjunto de claves de descifrado. Si lo hace, la clave generadora y las claves adicionales se tratarán de la misma manera.
Para especificar un AWS KMS key anillo de claves de descifrado en SDK de cifrado de AWS para JavaScript, debe utilizar la clave [ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN). De lo contrario, no AWS KMS key se reconoce. Si necesita ayuda para identificarlo AWS KMS keys en un AWS KMS llavero, consulte [Identificarse AWS KMS keys en un AWS KMS llavero](use-kms-keyring.md#kms-keyring-id)
Si utiliza el mismo anillo de claves para cifrar y descifrar, utilice la clave ARNs para identificar el AWS KMS keys conjunto de claves.
En este ejemplo, creamos un anillo de claves que incluye solo uno de los del anillo de claves de AWS KMS keys cifrado. Antes de ejecutar este código, reemplace el ARN de clave de ejemplo por uno válido. Debe tener permiso de `kms:Decrypt` sobre la AWS KMS key.
Comience por proporcionar sus credenciales al navegador. [Los SDK de cifrado de AWS para JavaScript ejemplos utilizan el paquete web. DefinePlugin](https://webpack.js.org/plugins/define-plugin/), que reemplaza las constantes de las credenciales por las credenciales reales. También puede usar cualquier otro método para proporcionar sus credenciales. A continuación, utilice las credenciales para crear un AWS KMS cliente.
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
A continuación, cree un conjunto de AWS KMS claves con el AWS KMS cliente. En este ejemplo, se utiliza solo una de las del AWS KMS keys anillo de claves de cifrado.
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
```
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ keyIds })
```
Paso 3: Descifrar los datos.
A continuación, llame a la función `decrypt`. Pase el conjunto de claves de descifrado que acaba de crear (`keyring`) y el [mensaje cifrado](concepts.md#message) que la función `encrypt` ha devuelto (`result`). AWS Encryption SDK Utiliza el anillo de claves para descifrar una de las claves de datos cifradas. Luego, usa la clave de datos en texto no cifrado para descifrar los datos.
Si la llamada se realiza correctamente, el campo `plaintext` contiene los datos en texto no cifrado (descifrado). El campo `messageHeader` contiene metadatos sobre el proceso de descifrado, como el contexto de cifrado que se ha utilizado para descifrar los datos.
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
Paso 4: Verificar el contexto de cifrado.
El [contexto de cifrado](concepts.md#encryption-context) utilizado para descifrar los datos se incluye en el encabezado del mensaje (`messageHeader`) que la función `decrypt` devuelve. Antes de que la aplicación devuelva los datos en texto no cifrado, compruebe que el contexto de cifrado que proporcionó durante el cifrado esté incluido en el contexto de cifrado que se utilizó al descifrar. Una discrepancia podría indicar que se han manipulado los datos o que no ha descifrado el texto cifrado correcto.
Al verificar el contexto de cifrado, no requiere una coincidencia exacta. Cuando se utiliza un algoritmo de cifrado con la firma, el [administrador de materiales criptográficos](concepts.md#crypt-materials-manager) (CMM) agrega la clave de firma pública al contexto de cifrado antes de cifrar el mensaje. Pero todos los pares de contexto de cifrado que ha enviado tienen que estar incluidos en el contexto de cifrado devuelto.
Primero, obtenga el contexto de cifrado del encabezado del mensaje. Luego compruebe que cada par clave-valor del contexto de cifrado original (`context`) coincida con un par clave-valor en el contexto de cifrado devuelto (`encryptionContext`).
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
Si la comprobación del contexto de cifrado se realiza correctamente, puede devolver los datos en texto no cifrado.
# SDK de cifrado de AWS para Python
En este tema se explica cómo instalar y utilizar el SDK de cifrado de AWS para Python. Para obtener detalles sobre la programación con SDK de cifrado de AWS para Python, consulte el [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositorio en GitHub. Para obtener documentación de la API, consulte [Leer los documentos](https://aws-encryption-sdk-python.readthedocs.io/en/latest/).
**Topics**
+ [
## Requisitos previos
](#python-prerequisites)
+ [
## Instalación
](#python-installation)
+ [Ejemplos](python-example-code.md)
## Requisitos previos
Antes de instalarlo SDK de cifrado de AWS para Python, asegúrese de cumplir los siguientes requisitos previos.
**Una versión compatible de Python**
SDK de cifrado de AWS para Python Las versiones 3.2.0 y posteriores requieren Python 3.8 o posterior.
La [biblioteca de proveedores de material AWS criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) es una dependencia opcional de la versión SDK de cifrado de AWS para Python 4. *x.* Si piensa instalar el MPL, debe usar Python 3.11 o posterior.
Las versiones anteriores son AWS Encryption SDK compatibles con Python 2.7 y Python 3.4 y versiones posteriores, pero le recomendamos que utilice la versión más reciente de AWS Encryption SDK.
Para descargar Python, visite el sitio de [descargas de Python](https://www.python.org/downloads/).
**La herramienta de instalación pip para Python**
`pip` está incluido en Python 3.6 y versiones posteriores, aunque es posible que desee actualizarlo. Para obtener más información acerca de la actualización o la instalación de `pip`, consulte la sección sobre la [instalación](https://pip.pypa.io/en/latest/installation/) en la documentación de `pip`.
## Instalación
Instale la versión más reciente de SDK de cifrado de AWS para Python.
**nota**
Todas las versiones SDK de cifrado de AWS para Python anteriores a la 3.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 AWS Encryption SDK 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 AWS Encryption SDK. Para obtener más información, consulte [Migrando su AWS Encryption SDK](migration.md).
Se utiliza `pip` para instalar el SDK de cifrado de AWS para Python, como se muestra en los siguientes ejemplos.
**Para instalar la versión más reciente**
```
pip install "aws-encryption-sdk[MPL]"
```
El `[MPL]` sufijo instala la [biblioteca de proveedores de material AWS criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL). La MPL contiene estructuras para cifrar y descifrar los datos. La MPL es una dependencia opcional de la introducida en la SDK de cifrado de AWS para Python versión 4. *x*. Recomendamos encarecidamente instalar el MPL. Sin embargo, si no tiene intención de utilizar el MPL, puede omitir el sufijo. `[MPL]`
Para obtener más información acerca de cómo utilizar pip para instalar y actualizar paquetes, consulte [Instalación de paquetes](https://packaging.python.org/tutorials/installing-packages/).
SDK de cifrado de AWS para Python Requiere la [biblioteca de criptografía (pyca/cryptography](https://cryptography.io/en/latest/)) en todas las plataformas. Todas las versiones de `pip` instalan y compilan automáticamente la biblioteca de `cryptography` en Windows. La versión 8.1 de `pip` y las versiones posteriores se instalan y compilan automáticamente `cryptography` en Linux. Si utiliza una versión anterior de `pip` y su entorno Linux no dispone de las herramientas necesarias para crear la biblioteca `cryptography`, tiene que instalarlas. Para obtener más información, consulte [Building cryptography on Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux).
[Las versiones 1.10.0 y 2.5.0 sitúan la dependencia criptográfica entre las versiones 2.5.0 y SDK de cifrado de AWS para Python 3.3.2.](https://cryptography.io/en/latest/) Otras versiones SDK de cifrado de AWS para Python instalan la última versión de la criptografía. Si necesita una versión de criptografía posterior a la 3.3.2, le recomendamos que utilice la última versión principal del SDK de cifrado de AWS para Python.
Para obtener la última versión de desarrollo de SDK de cifrado de AWS para Python, vaya al [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositorio de GitHub.
Después de instalar el SDK de cifrado de AWS para Python, comience consultando el [código de ejemplo de Python](python-example-code.md) en esta guía.
# SDK de cifrado de AWS para Python código de ejemplo
Los siguientes ejemplos muestran cómo utilizar el SDK de cifrado de AWS para Python para cifrar y descifrar datos.
Los ejemplos de esta sección muestran cómo utilizar la versión 4. *x* de SDK de cifrado de AWS para Python con la dependencia opcional de la [biblioteca de proveedores de material criptográfico](https://github.com/aws/aws-cryptographic-material-providers-library) (`aws-cryptographic-material-providers`). Para ver ejemplos que utilizan versiones anteriores o instalaciones sin la biblioteca de proveedores de materiales (MPL), busca tu versión en la lista de [versiones](https://github.com/aws/aws-encryption-sdk-python/releases) del [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/)repositorio de. GitHub
Cuando usas la versión 4. *x* SDK de cifrado de AWS para Python con la MPL, utiliza [anillos de claves](choose-keyring.md) para realizar el cifrado de [sobres.](concepts.md#envelope-encryption) AWS Encryption SDK Proporciona anillos de claves que son compatibles con los proveedores de claves maestras que utilizaba en versiones anteriores. Para obtener más información, consulte [Compatibilidad de conjuntos de claves](choose-keyring.md#keyring-compatibility). Para ver ejemplos sobre la migración de proveedores de claves maestras a conjuntos de claves, consulte los [ejemplos de migración](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/migration) en el repositorio de; `aws-encryption-sdk-python` GitHub
**Topics**
+ [Cadenas](#python-example-strings)
+ [Secuencias de bytes](#python-example-streams)
## Cifrado y descifrado de cadenas
El siguiente ejemplo muestra cómo utilizarlos AWS Encryption SDK para cifrar y descifrar cadenas. En este ejemplo, se utiliza un [AWS KMS anillo de claves](use-kms-keyring.md) con una clave KMS de cifrado simétrico.
En este ejemplo, se crea una instancia del AWS Encryption SDK cliente con la política de compromiso [predeterminada](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Para obtener más información, consulte [Establecer su política de compromiso](migrate-commitment-policy.md).
```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example sets up the KMS Keyring
The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and
decrypt data keys. This example creates a KMS Keyring and then encrypts a custom input EXAMPLE_DATA
with an encryption context. This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.
AWS KMS keyrings can be used independently or in a multi-keyring with other keyrings
of the same or a different type.
"""
import boto3
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import CreateAwsKmsKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict # noqa pylint: disable=wrong-import-order
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
EXAMPLE_DATA: bytes = b"Hello World"
def encrypt_and_decrypt_with_keyring(
kms_key_id: str
):
"""Demonstrate an encrypt/decrypt cycle using an AWS KMS keyring.
Usage: encrypt_and_decrypt_with_keyring(kms_key_id)
:param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and
decryption of your data keys.
:type kms_key_id: string
"""
# 1. Instantiate the encryption SDK client.
# This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
# which enforces that this client only encrypts using committing algorithm suites and enforces
# that this client will only decrypt encrypted messages that were created with a committing
# algorithm suite.
# This is the default commitment policy if you were to build the client as
# `client = aws_encryption_sdk.EncryptionSDKClient()`.
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# 2. Create a boto3 client for KMS.
kms_client = boto3.client('kms', region_name="us-west-2")
# 3. Optional: create encryption context.
# Remember that your encryption context is NOT SECRET.
encryption_context: Dict[str, str] = {
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
# 4. Create your keyring
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
kms_key_id=kms_key_id,
kms_client=kms_client
)
kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring(
input=keyring_input
)
# 5. Encrypt the data with the encryptionContext.
ciphertext, _ = client.encrypt(
source=EXAMPLE_DATA,
keyring=kms_keyring,
encryption_context=encryption_context
)
# 6. Demonstrate that the ciphertext and plaintext are different.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert ciphertext != EXAMPLE_DATA, \
"Ciphertext and plaintext data are the same. Invalid encryption"
# 7. Decrypt your encrypted data using the same keyring you used on encrypt.
plaintext_bytes, _ = client.decrypt(
source=ciphertext,
keyring=kms_keyring,
# Provide the encryption context that was supplied to the encrypt method
encryption_context=encryption_context,
)
# 8. Demonstrate that the decrypted plaintext is identical to the original plaintext.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert plaintext_bytes == EXAMPLE_DATA, \
"Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```
## Cifrado y descifrado de secuencias de bytes
El siguiente ejemplo muestra cómo utilizarla AWS Encryption SDK para cifrar y descifrar secuencias de bytes. En este ejemplo se utiliza un anillo de claves [AES sin procesar.](use-raw-aes-keyring.md)
En este ejemplo, se crea una instancia del AWS Encryption SDK cliente con la política de [compromiso predeterminada](migrate-commitment-policy.md),. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` Para obtener más información, consulte [Establecer su política de compromiso](migrate-commitment-policy.md).
```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example demonstrates file streaming for encryption and decryption.
File streaming is useful when the plaintext or ciphertext file/data is too large to load into
memory. Therefore, the AWS Encryption SDK allows users to stream the data, instead of loading it
all at once in memory. In this example, we demonstrate file streaming for encryption and decryption
using a Raw AES keyring. However, you can use any keyring with streaming.
This example creates a Raw AES Keyring and then encrypts an input stream from the file
`plaintext_filename` with an encryption context to an output (encrypted) file `ciphertext_filename`.
It then decrypts the ciphertext from `ciphertext_filename` to a new file `decrypted_filename`.
This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.
See raw_aes_keyring_example.py in the same directory for another raw AES keyring example
in the AWS Encryption SDK for Python.
"""
import filecmp
import secrets
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict # noqa pylint: disable=wrong-import-order
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
def encrypt_and_decrypt_with_keyring(
plaintext_filename: str,
ciphertext_filename: str,
decrypted_filename: str
):
"""Demonstrate a streaming encrypt/decrypt cycle.
Usage: encrypt_and_decrypt_with_keyring(plaintext_filename
ciphertext_filename
decrypted_filename)
:param plaintext_filename: filename of the plaintext data
:type plaintext_filename: string
:param ciphertext_filename: filename of the ciphertext data
:type ciphertext_filename: string
:param decrypted_filename: filename of the decrypted data
:type decrypted_filename: string
"""
# 1. Instantiate the encryption SDK client.
# This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
# which enforces that this client only encrypts using committing algorithm suites and enforces
# that this client will only decrypt encrypted messages that were created with a committing
# algorithm suite.
# This is the default commitment policy if you were to build the client as
# `client = aws_encryption_sdk.EncryptionSDKClient()`.
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# 2. The key namespace and key name are defined by you.
# and are used by the Raw AES keyring to determine
# whether it should attempt to decrypt an encrypted data key.
key_name_space = "Some managed raw keys"
key_name = "My 256-bit AES wrapping key"
# 3. Optional: create encryption context.
# Remember that your encryption context is NOT SECRET.
encryption_context: Dict[str, str] = {
"encryption": "context",
"is not": "secret",
"but adds": "useful metadata",
"that can help you": "be confident that",
"the data you are handling": "is what you think it is",
}
# 4. Generate a 256-bit AES key to use with your keyring.
# In practice, you should get this key from a secure key management system such as an HSM.
# Here, the input to secrets.token_bytes() = 32 bytes = 256 bits
static_key = secrets.token_bytes(32)
# 5. Create a Raw AES keyring
# We choose to use a raw AES keyring, but any keyring can be used with streaming.
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
key_namespace=key_name_space,
key_name=key_name,
wrapping_key=static_key,
wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
)
raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
input=keyring_input
)
# 6. Encrypt the data stream with the encryptionContext
with open(plaintext_filename, 'rb') as pt_file, open(ciphertext_filename, 'wb') as ct_file:
with client.stream(
mode='e',
source=pt_file,
keyring=raw_aes_keyring,
encryption_context=encryption_context
) as encryptor:
for chunk in encryptor:
ct_file.write(chunk)
# 7. Demonstrate that the ciphertext and plaintext are different.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert not filecmp.cmp(plaintext_filename, ciphertext_filename), \
"Ciphertext and plaintext data are the same. Invalid encryption"
# 8. Decrypt your encrypted data stream using the same keyring you used on encrypt.
with open(ciphertext_filename, 'rb') as ct_file, open(decrypted_filename, 'wb') as pt_file:
with client.stream(
mode='d',
source=ct_file,
keyring=raw_aes_keyring,
encryption_context=encryption_context
) as decryptor:
for chunk in decryptor:
pt_file.write(chunk)
# 10. Demonstrate that the decrypted plaintext is identical to the original plaintext.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert filecmp.cmp(plaintext_filename, decrypted_filename), \
"Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```
# AWS Encryption SDK para Rust
En este tema se explica cómo instalar y usar AWS Encryption SDK for Rust. Para obtener más información sobre la programación AWS Encryption SDK para Rust, consulte el directorio [Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/) del aws-encryption-sdk repositorio en GitHub.
La AWS Encryption SDK versión para Rust se diferencia de algunas de las implementaciones de otros lenguajes de programación AWS Encryption SDK en los siguientes aspectos:
+ No hay soporte para el almacenamiento en [caché de claves de datos](data-key-caching.md). Sin embargo, AWS Encryption SDK para Rust es compatible con el [anillo de claves AWS KMS jerárquico](use-hierarchical-keyring.md), una solución alternativa de almacenamiento en caché de materiales criptográficos.
+ No es compatible con el streaming de datos
La versión AWS Encryption SDK para Rust incluye todas las funciones de seguridad introducidas en las versiones 2.0. *x* y versiones posteriores de las implementaciones en otros idiomas del AWS Encryption SDK. Sin embargo, si está utilizando Rust AWS Encryption SDK para descifrar datos cifrados con una versión anterior a la 2.0. *x* versión de la implementación en otro idioma de la AWS Encryption SDK, es posible que deba ajustar su política de [compromisos](concepts.md#commitment-policy). Para obtener más información, consulte [¿Cómo establecer su política de compromiso?](migrate-commitment-policy.md#migrate-commitment-step1).
El AWS Encryption SDK de Rust es un producto de [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), un lenguaje de verificación formal en el que se escriben las especificaciones, el código para implementarlas y las pruebas para probarlas. AWS Encryption SDK El resultado es una biblioteca que implementa las características del AWS Encryption SDK en una trama que garantiza la corrección funcional.
**Más información**
+ Para ver ejemplos que muestran cómo configurar las opciones del AWS Encryption SDK, como especificar un conjunto de algoritmos alternativo, limitar las claves de datos cifrados y utilizar claves AWS KMS multirregionales, consulte. [Configuración del AWS Encryption SDK](configure.md)
+ Para ver ejemplos que muestran cómo configurar y usar AWS Encryption SDK para Rust, consulta los [ejemplos de Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples) en el aws-encryption-sdk repositorio de Rust. GitHub
**Topics**
+ [
## Requisitos previos
](#prerequisites-rust)
+ [
## Instalación
](#rust-installation)
+ [Ejemplos](rust-examples.md)
## Requisitos previos
Antes de instalar el AWS Encryption SDK para Rust, asegúrate de cumplir los siguientes requisitos previos.
**Instale Rust y Cargo**
Instala la versión estable actual de [Rust](https://www.rust-lang.org/) usando [rustup.](https://rustup.rs/)
Para obtener más información sobre la descarga e instalación de rustup, consulta los [procedimientos de instalación](https://doc.rust-lang.org/cargo/getting-started/installation.html) en The Cargo Book.
## Instalación
El AWS Encryption SDK de Rust está disponible en forma de [https://crates.io/crates/aws-esdk](https://crates.io/crates/aws-esdk)caja en Crates.io. Para obtener más información sobre cómo instalar y compilar AWS Encryption SDK para Rust, consulta el [archivo README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline) en el repositorio de Rust. aws-encryption-sdk GitHub
Puedes instalar el AWS Encryption SDK para Rust de las siguientes maneras.
**Manualmente**
Para instalar el repositorio AWS Encryption SDK para Rust, clona o descarga el [aws-encryption-sdk](https://github.com/aws/aws-encryption-sdk/tree/mainline) GitHub repositorio.
**Usando Crates.io**
Ejecute el siguiente comando Cargo en el directorio de su proyecto:
```
cargo add aws-esdk
```
O añade la siguiente línea a tu Cargo.toml:
```
aws-esdk = ""
```
# AWS Encryption SDK para el código de ejemplo de Rust
Los siguientes ejemplos muestran los patrones de codificación básicos que se utilizan al programar con Rust. AWS Encryption SDK En concreto, se crea una instancia de la biblioteca AWS Encryption SDK y de proveedores de materiales. A continuación, antes de llamar a cada método, se crea una instancia del objeto que define la entrada del método.
Para ver ejemplos que muestran cómo configurar las opciones del AWS Encryption SDK, como especificar un conjunto de algoritmos alternativo y limitar las claves de datos cifrados, consulta los [ejemplos de Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples/) en el aws-encryption-sdk repositorio de. GitHub
## Cifrar y descifrar datos en el caso de Rust AWS Encryption SDK
Este ejemplo muestra el patrón básico para cifrar y descifrar datos. Cifra un archivo pequeño con claves de datos que están protegidas por una AWS KMS clave de empaquetado.
**Paso 1: Instanciar el. AWS Encryption SDK**
Utilizará los métodos descritos en AWS Encryption SDK para cifrar y descifrar los datos.
```
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
```
**Paso 2: Crea un AWS KMS cliente.**
```
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
```
**Opcional: cree su contexto de cifrado.**
```
let encryption_context = HashMap::from([
("encryption".to_string(), "context".to_string()),
("is not".to_string(), "secret".to_string()),
("but adds".to_string(), "useful metadata".to_string()),
("that can help you".to_string(), "be confident that".to_string()),
("the data you are handling".to_string(), "is what you think it is".to_string()),
]);
```
**Paso 3: Cree una instancia de la biblioteca de proveedores de materiales.**
Utilizará los métodos de la biblioteca de proveedores de materiales para crear los conjuntos de claves que especifican qué claves protegen sus datos.
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
```
**Paso 4: Crea un AWS KMS llavero.**
Para crear el conjunto de claves, llame al método de conjunto de claves con el objeto de entrada del conjunto de claves. En este ejemplo, se utiliza el `create_aws_kms_keyring()` método y se especifica una clave KMS.
```
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
```
**Paso 5: Cifra el texto sin formato.**
```
let plaintext = example_data.as_bytes();
let encryption_response = esdk_client.encrypt()
.plaintext(plaintext)
.keyring(kms_keyring.clone())
.encryption_context(encryption_context.clone())
.send()
.await?;
let ciphertext = encryption_response
.ciphertext
.expect("Unable to unwrap ciphertext from encryption response");
```
**Paso 6: Descifra tus datos cifrados con el mismo conjunto de claves que utilizaste para cifrar.**
```
let decryption_response = esdk_client.decrypt()
.ciphertext(ciphertext)
.keyring(kms_keyring)
// Provide the encryption context that was supplied to the encrypt method
.encryption_context(encryption_context)
.send()
.await?;
let decrypted_plaintext = decryption_response
.plaintext
.expect("Unable to unwrap plaintext from decryption response");
```
# AWS Encryption SDK interfaz de línea de comandos
La interfaz de línea de AWS Encryption SDK comandos (CLI de AWS cifrado) le permite utilizarla AWS Encryption SDK para cifrar y descifrar datos de forma interactiva en la línea de comandos y en los scripts. No se requieren conocimientos de criptografía o programación.
**nota**
Las versiones de la CLI de AWS cifrado anteriores a la 4.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.1.*x* y versiones posteriores a la última versión de la CLI de cifrado de AWS sin cambios en el código ni en los datos. Sin embargo, se introdujeron [nuevas características de seguridad](about-versions.md#version-2) en la versión 2.1.*x* que no son compatibles con versiones anteriores. Para actualizar desde la versión 1.7. *x* o anterior, primero debe actualizar a la última versión 1. versión *x* de la CLI AWS de cifrado. Para obtener más información, consulte [Migrando su AWS Encryption SDK](migration.md).
Las nuevas funciones de seguridad se publicaron originalmente en las versiones 1.7 de AWS Encryption CLI. *x* y 2.0. *x*. Sin embargo, AWS Encryption CLI versión 1.8. *x* reemplaza a la versión 1.7. *x* y CLI de AWS cifrado 2.1. *x* reemplaza a 2.0. *x*. Para obtener más información, consulte el [aviso de seguridad](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) correspondiente en el [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositorio de GitHub.
Como todas las implementaciones de AWS Encryption SDK, la CLI de AWS cifrado ofrece funciones avanzadas de protección de datos. Esto incluye el [cifrado de sobre](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/how-it-works.html#envelope-encryption), los datos autenticados adicionales (AAD) y los [conjuntos de algoritmos](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/supported-algorithms.html) de clave simétrica autenticados y seguros, tales como AES-GCM de 256 bits con derivación de clave [compromiso clave](concepts.md#key-commitment) y firma.
La CLI de AWS cifrado se basa en Linux, macOS [SDK de cifrado de AWS para Python](python.md)y Windows y es compatible con ellos. Puede ejecutar comandos y scripts para cifrar y descifrar los datos en el shell que prefiera en Linux o macOS, en una ventana de línea de comandos (cmd.exe) en Windows y en una PowerShell consola de cualquier sistema.
Todas las implementaciones específicas del idioma AWS Encryption SDK, incluida la AWS CLI de cifrado, son interoperables. Por ejemplo, puede cifrar datos con la [SDK de cifrado de AWS para Java](java.md)y descifrarlos con la AWS CLI de cifrado.
En este tema se presenta la CLI de AWS cifrado, se explica cómo instalarla y utilizarla y se proporcionan varios ejemplos que le ayudarán a empezar. Para comenzar rápidamente, consulte [Cómo cifrar y descifrar sus datos con la AWS CLI de cifrado en el](https://aws.amazon.com/blogs/security/how-to-encrypt-and-decrypt-your-data-with-the-aws-encryption-cli/) blog de AWS seguridad. Para obtener información más detallada, consulte [Read The Docs](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/) y únase a nosotros en el desarrollo de la CLI de AWS cifrado en el [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositorio de GitHub.
**Desempeño**
La CLI de AWS cifrado se basa en SDK de cifrado de AWS para Python. Cada vez que ejecuta la CLI, se inicia una nueva instancia del tiempo de ejecución de Python. Para mejorar el rendimiento, siempre que sea posible, utilice un solo comando en lugar de una serie de comandos independientes. Por ejemplo, ejecute un comando que procese los archivos de un directorio de forma repetida en lugar de ejecutar comandos independientes para cada archivo.
**Topics**
+ [Instalación de la CLI de](crypto-cli-install.md)
+ [Cómo utilizar la CLI](crypto-cli-how-to.md)
+ [Ejemplos](crypto-cli-examples.md)
+ [Referencia de sintaxis y parámetros](crypto-cli-reference.md)
+ [Versiones](crypto-cli-versions.md)
# Instalación de la interfaz de línea de AWS Encryption SDK comandos
En este tema se explica cómo instalar la CLI de AWS cifrado. Para obtener información detallada, consulte el [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositorio en GitHub y [lea los documentos](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/).
**Topics**
+ [
## Instalación de los requisitos previos
](#crypto-cli-prerequisites)
+ [Instalación de la CLI de](#install-sdk-cli)
## Instalación de los requisitos previos
La CLI de AWS cifrado se basa en SDK de cifrado de AWS para Python. Para instalar la CLI de AWS cifrado, necesita Python y `pip` la herramienta de administración de paquetes de Python. Python y `pip` están disponibles en todas las plataformas con soporte.
Instale los siguientes requisitos previos antes de instalar la CLI de AWS cifrado:
**Python**
Las versiones 4.2.0 y posteriores de la CLI de AWS cifrado requieren Python 3.8 o posterior.
Las versiones anteriores de la CLI de AWS cifrado admiten Python 2.7 y 3.4 y versiones posteriores, pero le recomendamos que utilice la versión más reciente de la CLI de AWS cifrado.
Python está incluido en la mayoría de las instalaciones de Linux y macOS, pero es necesario actualizar a la versión Python 3.6 o posterior. Le recomendamos que utilice la última versión de Python. Tendrá que instalar Python en Windows, si todavía no está de forma predeterminada. Para descargar e instalar Python, visite el sitio de [descargas de Python](https://www.python.org/downloads/).
Para determinar si Python está instalado, escriba lo siguiente en la línea de comandos:
```
python
```
Para comprobar la versión de Python, utilice el parámetro `-V` (V mayúscula).
```
python -V
```
En Windows, después de instalar Python, añada la ruta al archivo del `Python.exe` al valor de la variable de entorno **Path**.
De forma predeterminada, Python se instala en el directorio de todos los usuarios o en un directorio de perfil de usuario (`$home` o `%userprofile%`) en el subdirectorio `AppData\Local\Programs\Python`. Para encontrar la ubicación del archivo `Python.exe` en el sistema, consulte una de las siguientes claves del registro. Puede utilizarla PowerShell para buscar en el registro.
```
PS C:\> dir HKLM:\Software\Python\PythonCore\version\InstallPath
# -or-
PS C:\> dir HKCU:\Software\Python\PythonCore\version\InstallPath
```
**pip**
`pip` es el administrador de paquetes de Python. Para instalar la CLI de AWS cifrado y sus dependencias, necesita la `pip` versión 8.1 o una versión posterior. Para obtener ayuda con la instalación o actualización de `pip`, consulte la sección de [instalación](https://pip.pypa.io/en/latest/installing/) en la documentación de `pip`.
En las instalaciones de Linux, las versiones `pip` anteriores a la 8.1 no pueden crear la biblioteca de **criptografía** que requiere la CLI de AWS cifrado. Si decide no actualizar su versión de `pip`, puede instalar las herramientas de compilación por separado. Para obtener más información, consulte [Building cryptography on Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux).
**AWS Command Line Interface**
El AWS Command Line Interface (AWS CLI) solo es necesario si utiliza AWS KMS keys in AWS Key Management Service (AWS KMS) con la CLI de AWS cifrado. Si utiliza un [proveedor de claves maestras](concepts.md#master-key-provider) diferente, no AWS CLI es obligatorio.
Para utilizarla AWS KMS keys con la CLI de AWS cifrado, debe [instalar](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) y [configurar](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-quick-configuration) la AWS CLI. La configuración hace que las credenciales que se utilizan para autenticarse AWS KMS estén disponibles para la CLI de AWS cifrado.
## Instalación y actualización de la CLI AWS de cifrado
Instale la última versión de la CLI de AWS cifrado. Cuando se instala la CLI de AWS cifrado, se instalan automáticamente las bibliotecas que la CLI necesita, incluidas la [SDK de cifrado de AWS para Python](python.md)[biblioteca de criptografía](https://cryptography.io/en/latest/) de Python y la. `pip` [AWS SDK para Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
**nota**
Las versiones de la CLI de AWS cifrado anteriores a la 4.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.1.*x* y versiones posteriores a la última versión de la CLI de cifrado de AWS sin cambios en el código ni en los datos. Sin embargo, se introdujeron [nuevas características de seguridad](about-versions.md#version-2) en la versión 2.1.*x* que no son compatibles con versiones anteriores. Para actualizar desde la versión 1.7. *x* o anterior, primero debe actualizar a la última versión 1. versión *x* de la CLI AWS de cifrado. Para obtener más información, consulte [Migrando su AWS Encryption SDK](migration.md).
Las nuevas funciones de seguridad se publicaron originalmente en las versiones 1.7 de AWS Encryption CLI. *x* y 2.0. *x*. Sin embargo, AWS Encryption CLI versión 1.8. *x* reemplaza a la versión 1.7. *x* y CLI de AWS cifrado 2.1. *x* reemplaza a 2.0. *x*. Para obtener más información, consulte el [aviso de seguridad](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) correspondiente en el [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositorio de GitHub.
**Para instalar la versión más reciente de la CLI de AWS cifrado**
```
pip install aws-encryption-sdk-cli
```
**Para actualizar a la última versión de la CLI de AWS cifrado**
```
pip install --upgrade aws-encryption-sdk-cli
```
**Para encontrar los números de versión de su CLI de AWS cifrado y AWS Encryption SDK**
```
aws-encryption-cli --version
```
El resultado muestra los números de versión de ambas bibliotecas.
```
aws-encryption-sdk-cli/2.1.0 aws-encryption-sdk/2.0.0
```
**Para actualizar a la última versión de la CLI de AWS cifrado**
```
pip install --upgrade aws-encryption-sdk-cli
```
Al instalar la CLI de AWS cifrado, también se instala la versión más reciente de AWS SDK para Python (Boto3), si aún no está instalada. Si Boto3 está instalado, el instalador verifica la versión de Boto3 y la actualiza si es necesario.
**Para encontrar la versión de Boto3 que tiene instalada**
```
pip show boto3
```
**Para actualizar a la versión más reciente de Boto3**
```
pip install --upgrade boto3
```
Para instalar la versión de la CLI de AWS cifrado actualmente en desarrollo, consulte el [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositorio en GitHub.
Para obtener más información acerca de cómo utilizar `pip` para instalar y actualizar paquetes de Python, consulte la [documentación de pip](https://pip.pypa.io/en/stable/quickstart/).
# Cómo utilizar la CLI AWS de cifrado
En este tema se explica cómo utilizar los parámetros de la CLI de AWS cifrado. Para ver ejemplos, consulte [Ejemplos de la CLI AWS de cifrado](crypto-cli-examples.md). Para ver la documentación completa, consulte [Leer los documentos](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/). La sintaxis que se muestra en estos ejemplos corresponde a la versión 2.1 de la CLI de AWS cifrado. *x* y versiones posteriores.
**nota**
Las versiones de la CLI de AWS cifrado anteriores a la 4.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.1.*x* y versiones posteriores a la última versión de la CLI de cifrado de AWS sin cambios en el código ni en los datos. Sin embargo, se introdujeron [nuevas características de seguridad](about-versions.md#version-2) en la versión 2.1.*x* que no son compatibles con versiones anteriores. Para actualizar desde la versión 1.7. *x* o anterior, primero debe actualizar a la última versión 1. versión *x* de la CLI AWS de cifrado. Para obtener más información, consulte [Migrando su AWS Encryption SDK](migration.md).
Las nuevas funciones de seguridad se publicaron originalmente en las versiones 1.7 de AWS Encryption CLI. *x* y 2.0. *x*. Sin embargo, AWS Encryption CLI versión 1.8. *x* reemplaza a la versión 1.7. *x* y CLI de AWS cifrado 2.1. *x* reemplaza a 2.0. *x*. Para obtener más información, consulte el [aviso de seguridad](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) correspondiente en el [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositorio de GitHub.
Para ver un ejemplo que muestra cómo usar la característica de seguridad que limita las claves de datos cifrados, consulte [Limitar las claves de datos cifrados](configure.md#config-limit-keys).
Para ver un ejemplo que muestra cómo utilizar las claves AWS KMS multirregionales, consulte[Uso de varias regiones AWS KMS keys](configure.md#config-mrks).
**Topics**
+ [
## Cómo cifrar y descifrar datos
](#crypto-cli-e-d-intro)
+ [
## Cómo especificar las claves de encapsulamiento
](#crypto-cli-master-key)
+ [
## Cómo proporcionar la entrada
](#crypto-cli-input)
+ [
## Cómo especificar la ubicación de salida
](#crypto-cli-output)
+ [
## Cómo utilizar un contexto de cifrado
](#crypto-cli-encryption-context)
+ [
## Cómo especificar una política de compromiso
](#crypto-cli-commitment-policy)
+ [
## Cómo almacenar parámetros en un archivo de configuración
](#crypto-cli-config-file)
## Cómo cifrar y descifrar datos
La CLI de AWS cifrado utiliza las funciones de AWS Encryption SDK para facilitar el cifrado y el descifrado de datos de forma segura.
**nota**
El parámetro `--master-keys` está obsoleto en la versión 1.8.*x* de la CLI de cifrado de AWS y se eliminó en la versión 2.1.*x*. En su lugar, utilice el parámetro `--wrapping-keys`. A partir de la versión 2.1.*x*, el parámetro `--wrapping-keys` es obligatorio para cifrar y descifrar. Para obtener más información, consulte [AWS Encryption SDK Referencia de parámetros y sintaxis de CLI](crypto-cli-reference.md).
+ Al cifrar datos en la CLI de AWS cifrado, se especifican los datos de texto sin formato y una [clave de empaquetado](concepts.md#master-key) (o *clave maestra*), como una AWS KMS key in AWS Key Management Service (AWS KMS). Si utiliza un proveedor de claves maestras personalizadas, también debe especificarlo. También debe especificar las ubicaciones de salida del [mensaje cifrado](concepts.md#message) y de los metadatos relativos a la operación de cifrado. El [contexto de cifrado](concepts.md#encryption-context) es opcional, pero se recomienda.
En la versión 1.8.*x*, se requiere el parámetro `--commitment-policy` cuando usa el parámetro `--wrapping-keys`; de lo contrario, no será válido. En la versión 2.1.*x*, el parámetro `--commitment-policy` es opcional, pero se recomienda.
```
aws-encryption-cli --encrypt --input myPlaintextData \
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
--output myEncryptedMessage \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt
```
La CLI de AWS cifrado cifra los datos con una clave de datos única. Luego, cifra la clave de datos con las claves de encapsulamiento que especifique. Devuelve un [mensaje cifrado](concepts.md#message) y los metadatos relativos a la operación. El mensaje cifrado contiene los datos cifrados (*texto cifrado*) y una copia cifrada de la clave de datos. No tiene que preocuparse por almacenar, administrar ni perder la clave de datos.
+ Al descifrar datos, en el mensaje cifrado se transmiten el contexto de cifrado opcional y las ubicaciones de salida del texto no cifrado y de los metadatos. También debe especificar las claves de empaquetado que la CLI de AWS cifrado puede usar para descifrar el mensaje o decirle a la CLI de AWS encriptación que puede usar cualquier clave de empaquetado que cifre el mensaje.
A partir de la versión 1.8.*x*, el parámetro `--wrapping-keys` es opcional al descifrar, pero se recomienda. A partir de la versión 2.1.*x*, el parámetro `--wrapping-keys` es obligatorio para cifrar y descifrar.
Al descifrar, puede utilizar el atributo **key** del parámetro `--wrapping-keys` para especificar las claves de encapsulamiento que descifran los datos. Especificar una clave de AWS KMS empaquetado al descifrar es opcional, pero es una [práctica recomendada](best-practices.md) ya que evita que utilice una clave que no tenía intención de usar. Si utiliza un proveedor de claves maestras personalizadas, debe especificar el proveedor y la clave de encapsulamiento.
Si no utiliza el atributo **clave**, debe establecer el atributo de [**detección**](#discovery-cli-attribute) del `--wrapping-keys` parámetro en`true`, lo que permite a la CLI de AWS cifrado descifrar mediante cualquier clave de empaquetado que haya cifrado el mensaje.
Como práctica recomendada, utilice el parámetro `--max-encrypted-data-keys` para evitar descifrar un mensaje mal formado con un número excesivo de claves de datos cifradas. Especifique el número esperado de claves de datos cifrados (una por cada clave de encapsulamiento utilizada en el cifrado) o un máximo razonable (por ejemplo, 5). Para obtener más información, consulte [Limitar las claves de datos cifrados](configure.md#config-limit-keys).
El parámetro `--buffer` devuelve el texto no cifrado solo después de procesar todas las entradas, incluida la verificación de la firma digital, si existe alguna.
El parámetro `--decrypt-unsigned` descifra el texto cifrado y garantiza que los mensajes no estén firmados antes del descifrado. Utilice este parámetro si utilizó el parámetro `--algorithm` y seleccionó un conjunto de algoritmos sin firma digital para cifrar los datos. Si el texto cifrado está firmado, se produce un error en el descifrado.
Puede utilizar `--decrypt` o `--decrypt-unsigned` para el descifrado, pero no ambos.
```
aws-encryption-cli --decrypt --input myEncryptedMessage \
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
--output myPlaintextData \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt
```
La CLI de AWS cifrado utiliza la clave de empaquetado para descifrar la clave de datos del mensaje cifrado. A continuación, utiliza la clave de datos para descifrar los datos. Devuelve los datos en texto no cifrado y los metadatos relativos a la operación.
## Cómo especificar las claves de encapsulamiento
Al cifrar datos en la CLI de AWS cifrado, debe especificar al menos una [clave de empaquetado](concepts.md#master-key) (o *clave maestra*). Puede usar AWS KMS keys in AWS Key Management Service (AWS KMS), empaquetar claves de un [proveedor de claves maestras](concepts.md#master-key-provider) personalizado, o ambas. El proveedor de claves maestras personalizadas puede ser cualquiera que sea compatible con Python.
Para especificar las claves de encapsulamiento en las versiones 1.8.*x* y posteriores, utilice el parámetro `--wrapping-keys` (`-w`). El valor de este parámetro es una colección de [atributos](#cli-master-key-attributes) con el formato `attribute=value`. Los atributos que se utilizan dependen del proveedor de claves maestras y del comando.
+ **AWS KMS**. En los comandos de cifrado, debe especificar un parámetro `--wrapping-keys` con un atributo **key**. A partir de la versión 2.1.*x*, el parámetro `--wrapping-keys` también es obligatorio para descifrar comandos. Al descifrar, el parámetro `--wrapping-keys` requiere un atributo **key** o un atributo **discovery** con un valor de `true` (pero no ambos). Otros atributos son opcionales.
+ **Proveedor de claves maestras personalizadas**. Debe especificar un parámetro `--wrapping-keys` en cada comando. El valor del parámetro debe tener los atributos **key** y **provider**.
Puede incluir [varios parámetros `--wrapping-keys`](#cli-many-cmks) y varios atributos **key** en el mismo comando.
### Atributos de parámetro de clave de encapsulamiento
El valor del parámetro `--wrapping-keys` se compone de los siguientes atributos y sus valores. Todos los comandos de cifrado requieren un parámetro `--wrapping-keys` (o parámetro `--master-keys`). A partir de la versión 2.1.*x*, el parámetro `--wrapping-keys` también es obligatorio para descifrar.
Si el nombre o valor de un atributo contiene espacios o caracteres especiales, incluya tanto el nombre como el valor entre comillas. Por ejemplo, `--wrapping-keys key=12345 "provider=my cool provider"`.
**Key: especifique una clave de encapsulamiento**
Use el atributo **key** para identificar una clave de encapsulamiento. Al cifrar, el valor puede ser cualquier identificador de clave que el proveedor de claves maestras pueda reconocer.
```
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab
```
En un comando de cifrado, debe incluir al menos un atributo **key** y su valor. Para cifrar su clave de datos en varias claves de encapsulamiento, utilice [varios atributos **key**](#cli-many-cmks).
```
aws-encryption-cli --encrypt --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
```
En los comandos de cifrado que utilizan AWS KMS keys, el valor de la **clave** puede ser el ID de la clave, el ARN de la clave, un nombre de alias o el ARN del alias. Por ejemplo, este comando de cifrado utiliza el ARN de un alias en el valor del atributo **key**. *Para obtener más información sobre los identificadores clave de un AWS KMS key, consulte los [identificadores clave en la Guía para desarrolladores](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id).AWS Key Management Service *
```
aws-encryption-cli --encrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
```
En los comandos de descifrado que utilizan un proveedor de claves maestras personalizadas, son obligatorios los atributos **key** y **provider**.
```
\\ Custom master key provider
aws-encryption-cli --decrypt --wrapping-keys provider='myProvider' key='100101'
```
En los comandos de descifrado que se utilizan AWS KMS, puede utilizar el atributo **clave** para especificar el que se va AWS KMS keys a utilizar para el descifrado, o el [atributo de **descubrimiento**](#discovery-cli-attribute) con un valor de`true`, que permite a la AWS CLI de cifrado utilizar cualquiera de los AWS KMS key que se hayan utilizado para cifrar el mensaje. Si especifica una AWS KMS key, debe ser una de las claves de empaquetado utilizadas para cifrar el mensaje.
Especificar la clave de encapsulamiento es una [práctica recomendada de AWS Encryption SDK](best-practices.md). Garantiza que utilice lo que pretende AWS KMS key utilizar.
En un comando de descifrado, el valor del atributo **key** debe ser un [ARN de clave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN).
```
\\ AWS KMS key
aws-encryption-cli --decrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
**Descubrimiento: utilice cualquiera AWS KMS key al descifrar**
Si no necesita limitar el uso AWS KMS keys al descifrar, puede usar el atributo de **descubrimiento** con un valor de. `true` Un valor de `true` permite que la CLI de AWS cifrado descifre mediante cualquiera AWS KMS key que haya cifrado el mensaje. Si no especifica un atributo **discovery**, discovery será `false` (predeterminado). El atributo de **descubrimiento** solo es válido en los comandos de descifrado y solo cuando el mensaje se cifró con. AWS KMS keys
El atributo **discovery** con un valor de `true` es una alternativa al uso del atributo **key** para especificar AWS KMS keys. Al descifrar un mensaje cifrado con AWS KMS keys, cada `--wrapping-keys` parámetro debe tener un atributo **clave** o un atributo de **descubrimiento** con un valor de`true`, pero no ambos.
Cuando el descubrimiento es cierto, se recomienda utilizar los atributos **discovery-partition y **discovery-account**** para limitar el AWS KMS keys uso a los que usted especifique. Cuentas de AWS En el siguiente ejemplo, los atributos de **descubrimiento** permiten que la CLI de AWS cifrado utilice cualquiera AWS KMS key de los especificados Cuentas de AWS.
```
aws-encryption-cli --decrypt --wrapping-keys \
discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666
```
**Provider: especifique el proveedor de claves maestras**
El atributo **provider** identifica el [proveedor de claves maestras](concepts.md#master-key-provider). El valor predeterminado es `aws-kms`, que representa a AWS KMS. Si utiliza otro proveedor de claves maestras, el atributo **provider** es obligatorio.
```
--wrapping-keys key=12345 provider=my_custom_provider
```
Para obtener más información sobre cómo utilizar proveedores de claves maestras personalizadas (distintos de AWS KMS), consulte el tema **Advanced Configuration** del archivo [README](https://github.com/aws/aws-encryption-sdk-cli/blob/master/README.rst) del repositorio de la [CLI de cifrado de AWS](https://github.com/aws/aws-encryption-sdk-cli/).
**Región: especifique una Región de AWS**
Utilice el atributo de **región** para especificar el Región de AWS de un AWS KMS key. Este atributo es válido solo en los comandos de cifrado y únicamente cuando el proveedor de clave maestra es AWS KMS.
```
--encrypt --wrapping-keys key=alias/primary-key region=us-east-2
```
AWS Los comandos CLI de cifrado utilizan lo Región de AWS que se especifica en el valor del atributo **clave** si incluye una región, como un ARN. Si el valor **clave** especifica un Región de AWS, se omite el atributo de la **región**.
El atributo **region** tiene prioridad sobre las demás especificaciones de la región. Si no utiliza un atributo de región, los comandos de CLI de AWS cifrado utilizan el Región de AWS especificado en el [perfil AWS CLI designado](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles), si lo hubiera, o en el perfil predeterminado.
**Profile: permite especificar un perfil con nombre**
Utilice el atributo **profile** para especificar un [perfil con nombre](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles) de la AWS CLI . Los perfiles con nombre pueden contener credenciales y una Región de AWS. Este atributo solo es válido cuando el proveedor de claves maestras es AWS KMS.
```
--wrapping-keys key=alias/primary-key profile=admin-1
```
Puede utilizar el atributo **profile** para especificar unas credenciales alternativas en los comandos de cifrado y descifrado. En un comando de cifrado, la CLI de AWS cifrado utiliza Región de AWS el del perfil nombrado solo cuando el valor de la **clave** no incluye una región y no hay ningún atributo de **región**. En un comando de descifrado, se ignora Región de AWS el perfil del nombre.
### Cómo especificar varias claves de encapsulamiento
Puede especificar varias claves de encapsulamiento (o *claves maestras*) en cada comando.
Si especifica más de una clave de encapsulamiento, la primera de ellas genera y cifra la clave de datos que se utiliza para cifrar sus datos. Las otras claves de encapsulamiento cifran la misma clave de datos. El [mensaje cifrado](concepts.md#message) obtenido contiene los datos cifrados ("texto cifrado") y una colección de claves de datos cifradas, cada una de ellas cifrada mediante cada clave de encapsulamiento. Cualquiera de las claves de encapsulamiento permite descifrar una clave de datos y luego los datos.
Hay dos formas de especificar varias claves de encapsulamiento:
+ Incluir varios atributos **key** en el valor del parámetro `--wrapping-keys`.
```
$key_oregon=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$key_ohio=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
--wrapping-keys key=$key_oregon key=$key_ohio
```
+ Incluir varios parámetros `--wrapping-keys` en el mismo comando. Utilice esta sintaxis cuando los valores de los atributos que vaya a especificar no deban aplicarse a todas las claves de encapsulamiento del comando.
```
--wrapping-keys region=us-east-2 key=alias/test_key \
--wrapping-keys region=us-west-1 key=alias/test_key
```
El atributo de **descubrimiento** con un valor de `true` permite a la CLI de AWS cifrado utilizar cualquier elemento AWS KMS key que haya cifrado el mensaje. Si usa varios parámetros `--wrapping-keys` en el mismo comando, el uso de `discovery=true` en cualquier parámetro `--wrapping-keys` anula de manera efectiva los límites del atributo **key** en otros parámetros `--wrapping-keys`.
Por ejemplo, en el siguiente comando, el atributo **clave** del primer `--wrapping-keys` parámetro limita la CLI de AWS cifrado a lo especificado AWS KMS key. Sin embargo, el atributo de **descubrimiento** del segundo `--wrapping-keys` parámetro permite a la CLI de AWS cifrado utilizar cualquiera AWS KMS key de las cuentas especificadas para descifrar el mensaje.
```
aws-encryption-cli --decrypt \
--wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666
```
## Cómo proporcionar la entrada
La operación de cifrado de la CLI de AWS cifrado toma datos de texto sin formato como entrada y devuelve un mensaje [cifrado](concepts.md#message). La operación de descifrado toma un mensaje cifrado como entrada y devuelve datos en texto no cifrado.
El `--input` parámetro (`-i`), que indica a la CLI de AWS cifrado dónde encontrar la entrada, es obligatorio en todos los comandos de la CLI de AWS cifrado.
Puede proporcionar la entrada de cualquiera de las siguientes formas:
+ Utilice un archivo.
```
--input myData.txt
```
+ Utilice un patrón de nombre de archivo.
```
--input testdir/*.xml
```
+ Utilice un directorio o patrón de nombre de directorio. Cuando la entrada es un directorio, el parámetro `--recursive` (`-r`, `-R`) es obligatorio.
```
--input testdir --recursive
```
+ Canalice la entrada al comando (stdin). Utilice el valor `-` para el parámetro `--input`. El parámetro `--input` siempre es obligatorio.
```
echo 'Hello World' | aws-encryption-cli --encrypt --input -
```
## Cómo especificar la ubicación de salida
El `--output` parámetro indica a la CLI de AWS cifrado dónde escribir los resultados de la operación de cifrado o descifrado. Se requiere en todos los comandos de CLI de AWS cifrado. La CLI de cifrado de AWS crea un nuevo archivo de salida por cada archivo de entrada de la operación.
Si ya existe un archivo de salida, de forma predeterminada, la CLI de AWS cifrado imprime una advertencia y, a continuación, sobrescribe el archivo. Para evitar la sobrescritura, utilice el parámetro `--interactive`, que solicita confirmación antes de sobrescribir, o el parámetro `--no-overwrite`, que omite la entrada si el resultado generara una sobrescritura. Para suprimir la advertencia de sobrescritura, utilice `--quiet`. Para capturar los errores y las advertencias de la CLI de AWS cifrado, utilice el operador de `2>&1` redirección para escribirlos en el flujo de salida.
**nota**
Los comandos que sobrescriben archivos de salida comienzan por eliminar el archivo de salida. Aunque el comando no se ejecute correctamente, el archivo de salida podría sobrescribirse igualmente.
Puede indicar la ubicación de salida de varias maneras.
+ Especifique el nombre de archivo. Si especifica una ruta al archivo, todos los directorios de la ruta deben existir antes de que se ejecute el comando.
```
--output myEncryptedData.txt
```
+ Especifique un directorio. El directorio de salida debe existir antes de que se ejecute el comando.
Si la entrada contiene subdirectorios, el comando los reproduce en el directorio especificado.
```
--output Test
```
Cuando la ubicación de salida es un directorio (sin nombres de archivo), la CLI de AWS cifrado crea nombres de archivos de salida en función de los nombres de los archivos de entrada más un sufijo. Las operaciones de cifrado anexan `.encrypted` al nombre del archivo de entrada y las operaciones de descifrado anexan `.decrypted`. Para cambiar el sufijo, utilice el parámetro `--suffix`.
Por ejemplo, si cifra `file.txt`, el comando de cifrado crea `file.txt.encrypted`. Si descifra `file.txt.encrypted`, el comando de descifrado crea `file.txt.encrypted.decrypted`.
+ Escriba en la línea de comandos (stdout). Escriba el valor `-` para el parámetro `--output`. Puede utilizar `--output -` para canalizar el resultado a otro comando o programa.
```
--output -
```
## Cómo utilizar un contexto de cifrado
La CLI de AWS cifrado le permite proporcionar un contexto de cifrado en los comandos de cifrado y descifrado. No es obligatorio, pero es una práctica criptográfica recomendada que le aconsejamos.
Un *contexto de cifrado* es un tipo de *información autenticada adicional* que es arbitraria y no es secreta. En la CLI de cifrado de AWS , el contexto de cifrado consta de una colección de pares `name=value`. Puede utilizar cualquier contenido en los pares; esto incluye información sobre los archivos, datos que le ayuden a encontrar la operación de cifrado en los registros o datos que se requieran para sus concesiones o políticas.
**En un comando de cifrado**
El contexto de cifrado que se especifica en un comando de cifrado, junto con cualquier par adicional que agregue el [CMM](concepts.md#crypt-materials-manager), está vinculado criptográficamente a los datos cifrados. También se incluye (en texto no cifrado) en el [mensaje cifrado](concepts.md#encryption-context) que devuelve el comando. Si utiliza una AWS KMS key, es posible que el contexto de cifrado también aparezca en texto plano en los registros y registros de auditoría, por ejemplo. AWS CloudTrail
En el siguiente ejemplo se muestra un contexto de cifrado con tres pares de `name=value`.
```
--encryption-context purpose=test dept=IT class=confidential
```
**En un comando de descifrado**
En un comando de descifrado, el contexto de cifrado ayuda a confirmar que se descifre el mensaje cifrado acertado.
No es preciso proporcionar un contexto de cifrado en un comando de descifrado, aunque sí se haya utilizado al realizar el cifrado. Sin embargo, si lo hace, la CLI de AWS cifrado verifica que todos los elementos del contexto de cifrado del comando decrypt coincidan con un elemento del contexto de cifrado del mensaje cifrado. Si cualquier elemento no coincide, el comando de descifrado genera un error.
Por ejemplo, el siguiente comando descifra el mensaje cifrado solo si su contexto de cifrado incluye `dept=IT`.
```
aws-encryption-cli --decrypt --encryption-context dept=IT ...
```
Un contexto de cifrado es una parte importante de la estrategia de seguridad. Sin embargo, al elegir un contexto de cifrado, es importante recordar que sus valores no son secretos. No incluya datos confidenciales en el contexto de cifrado.
**Para especificar un contexto de cifrado**
+ En un comando de **cifrado**, utilice el parámetro `--encryption-context` con uno o varios pares `name=value`. Utilice un espacio para separar cada par del siguiente.
```
--encryption-context name=value [name=value] ...
```
+ En un comando de **descifrado**, el valor del parámetro `--encryption-context` puede incluir pares `name=value`, elementos `name` (sin valores) o una combinación de ambos.
```
--encryption-context name[=value] [name] [name=value] ...
```
Si `name` o `value` de un par `name=value` incluye espacios o caracteres especiales, incluya el par completo entre comillas.
```
--encryption-context "department=software engineering" "Región de AWS=us-west-2"
```
Por ejemplo, este comando de cifrado incluye un contexto de cifrado con dos pares, `purpose=test` y `dept=23`.
```
aws-encryption-cli --encrypt --encryption-context purpose=test dept=23 ...
```
Estos comandos de descifrado se ejecutarían correctamente. El contexto de cifrado de cada comando es un subconjunto del contexto de cifrado original.
```
\\ Any one or both of the encryption context pairs
aws-encryption-cli --decrypt --encryption-context dept=23 ...
\\ Any one or both of the encryption context names
aws-encryption-cli --decrypt --encryption-context purpose ...
\\ Any combination of names and pairs
aws-encryption-cli --decrypt --encryption-context dept purpose=test ...
```
Sin embargo, estos comandos de descifrado generarían un error. El contexto de cifrado del mensaje cifrado no contiene los elementos especificados.
```
aws-encryption-cli --decrypt --encryption-context dept=Finance ...
aws-encryption-cli --decrypt --encryption-context scope ...
```
## Cómo especificar una política de compromiso
Para establecer la [política de compromiso](concepts.md#commitment-policy) del comando, utilice el [parámetro `--commitment-policy`](crypto-cli-reference.md#syntax-commitment-policy). Este parámetro se introduce en la versión 1.8.*x*. Es válido en los comandos de cifrado y descifrado. La política de compromiso que establezca solo es válida para el comando en el que aparece. Si no establece una política de compromiso para un comando, la CLI de AWS cifrado utiliza el valor predeterminado.
Por ejemplo, el siguiente valor de parámetro establece la política de compromiso en `require-encrypt-allow-decrypt`, que siempre cifra con un compromiso clave, pero descifra un texto cifrado que se haya cifrado con o sin compromiso clave.
```
--commitment-policy require-encrypt-allow-decrypt
```
## Cómo almacenar parámetros en un archivo de configuración
Puede ahorrar tiempo y evitar errores de escritura guardando los parámetros y valores de la CLI de AWS cifrado utilizados con frecuencia en los archivos de configuración.
Un *archivo de configuración* es un archivo de texto que contiene parámetros y valores para un comando CLI de AWS cifrado. Cuando se hace referencia a un archivo de configuración en un comando de la CLI de cifrado de AWS , la referencia se sustituye por los parámetros y los valores del archivo de configuración. El efecto es el mismo que si se hubiese escrito el contenido del archivo en la línea de comandos. Un archivo de configuración puede tener cualquier nombre y puede estar ubicado en cualquier directorio al que el usuario actual tenga acceso.
En el siguiente ejemplo de archivo de configuración, `key.conf`, se especifican dos AWS KMS keys en diferentes regiones.
```
--wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
--wrapping-keys key=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
```
Para utilizar el archivo de configuración en un comando, el nombre de archivo debe llevar el símbolo de arroba (`@`) como prefijo. En una PowerShell consola, utilice un carácter de comilla invertida para evitar el signo at (``@`).
En el comando de este ejemplo se utiliza el archivo `key.conf` en un comando de cifrado.
------
#### [ Bash ]
```
$ aws-encryption-cli -e @key.conf -i hello.txt -o testdir
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli -e `@key.conf -i .\Hello.txt -o .\TestDir
```
------
**Reglas de los archivos de configuración**
A continuación, se enumeran las reglas para utilizar archivos de configuración:
+ Puede incluir varios parámetros en cada archivo de configuración y enumerarlos en cualquier orden. Enumere cada parámetro con sus valores (si procede) en una línea independiente.
+ Utilice `#` para agregar un comentario a la totalidad o parte de una línea.
+ Puede incluir referencias a otros archivos de configuración. No utilices una tilde para escapar del `@` letrero, ni siquiera para entrar. PowerShell
+ Si utiliza comillas en un archivo de configuración, el texto entrecomillado no puede abarcar varias líneas.
Por ejemplo, este es el contenido de un archivo `encrypt.conf` de muestra.
```
# Archive Files
--encrypt
--output /archive/logs
--recursive
--interactive
--encryption-context class=unclassified dept=IT
--suffix # No suffix
--metadata-output ~/metadata
@caching.conf # Use limited caching
```
También puede incluir varios archivos de configuración en un comando. En el comando de este ejemplo se utilizan los archivos de configuración `encrypt.conf` y `master-keys.conf`.
------
#### [ Bash ]
```
$ aws-encryption-cli -i /usr/logs @encrypt.conf @master-keys.conf
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli -i $home\Test\*.log `@encrypt.conf `@master-keys.conf
```
------
**Siguiente: **[Pruebe los ejemplos de CLI de cifrado de AWS](crypto-cli-examples.md)
# Ejemplos de la CLI AWS de cifrado
Utilice los siguientes ejemplos para probar la CLI de AWS cifrado en la plataforma que prefiera. Para obtener ayuda con las claves maestras y otros parámetros, consulte [Cómo utilizar la CLI AWS de cifrado](crypto-cli-how-to.md). Para obtener rápidamente información de referencia, consulte [AWS Encryption SDK Referencia de parámetros y sintaxis de CLI](crypto-cli-reference.md).
**nota**
Los siguientes ejemplos utilizan la sintaxis de la versión 2.1 de la CLI de AWS cifrado. *x*.
Las nuevas funciones de seguridad se publicaron originalmente en las versiones 1.7 de AWS Encryption CLI. *x* y 2.0. *x*. Sin embargo, AWS Encryption CLI versión 1.8. *x* reemplaza a la versión 1.7. *x* y CLI de AWS cifrado 2.1. *x* reemplaza a 2.0. *x*. Para obtener más información, consulte el [aviso de seguridad](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) correspondiente en el [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositorio de GitHub.
Para ver un ejemplo que muestra cómo usar la característica de seguridad que limita las claves de datos cifrados, consulte [Limitar las claves de datos cifrados](configure.md#config-limit-keys).
Para ver un ejemplo que muestra cómo utilizar las claves AWS KMS multirregionales, consulte[Uso de varias regiones AWS KMS keys](configure.md#config-mrks).
**Topics**
+ [
## Cifrado de un archivo
](#cli-example-encrypt-file)
+ [
## Descifrado de un archivo
](#cli-example-decrypt-file)
+ [
## Cifrado de todos los archivos de un directorio
](#cli-example-encrypt-directory)
+ [
## Descifrado de todos los archivos de un directorio
](#cli-example-decrypt-directory)
+ [
## Cifrado y descifrado en la línea de comandos
](#cli-example-stdin)
+ [
## Uso de varias claves maestras
](#cli-example-multimaster)
+ [
## Cifrado y descifrado en scripts
](#cli-example-script)
+ [
## Uso del almacenamiento en caché de claves de datos
](#cli-example-caching)
## Cifrado de un archivo
En este ejemplo, se utiliza la CLI de AWS cifrado para cifrar el contenido del `hello.txt` archivo, que contiene la cadena «Hello World».
Al ejecutar un comando de cifrado en un archivo, la CLI de AWS cifrado obtiene el contenido del archivo, genera una [clave de datos](concepts.md#DEK) única, cifra el contenido del archivo con la clave de datos y, a continuación, escribe el [mensaje cifrado](concepts.md#message) en un archivo nuevo.
El primer comando guarda la clave ARN de an AWS KMS key en la `$keyArn` variable. Al cifrar con un AWS KMS key, puede identificarlo mediante un identificador de clave, un ARN de clave, un nombre de alias o un ARN de alias. *Para obtener más información sobre los identificadores clave de un AWS KMS key, consulta los [identificadores clave en la Guía para desarrolladores](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id).AWS Key Management Service *
El segundo comando cifra el contenido del archivo. El comando utiliza el parámetro `--encrypt` para especificar la operación y el parámetro `--input` para indicar el archivo que se ha de cifrar. El [`--wrapping-keys`parámetro](crypto-cli-how-to.md#crypto-cli-master-key) y su atributo **clave** obligatorio indican al comando que utilice el AWS KMS key representado por la clave ARN.
El comando utiliza el parámetro `--metadata-output` para especificar un archivo de texto para los metadatos acerca de la operación de cifrado. El comando aplica la práctica recomendada de utilizar el parámetro `--encryption-context` para especificar un [contexto de cifrado](crypto-cli-how-to.md#crypto-cli-encryption-context).
Este comando también usa el [parámetro `--commitment-policy`](crypto-cli-reference.md#syntax-commitment-policy) para establecer la política de compromiso de forma explícita. En la versión 1.8.*x*, se requiere este parámetro cuando usa el parámetro `--wrapping-keys`. En la versión 2.1.*x*, el parámetro `--commitment-policy` es opcional, pero se recomienda.
El valor del parámetro `--output`, un punto (.), indica al comando que escriba el archivo de salida en el directorio actual.
------
#### [ Bash ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt \
--output .
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input Hello.txt `
--wrapping-keys key=$keyArn `
--metadata-output $home\Metadata.txt `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--output .
```
------
Cuando el comando de cifrado se ejecuta correctamente, no devuelve ningún resultado. Para determinar si el comando se ha ejecutado correctamente, consulte el valor booleano de la variable `$?`. Si el comando se ejecuta correctamente, el valor de `$?` es `0` (Bash) o `True` (). PowerShell Cuando se produce un error en el comando, el valor de `$?` es distinto de cero (Bash) o (). `False` PowerShell
------
#### [ Bash ]
```
$ echo $?
0
```
------
#### [ PowerShell ]
```
PS C:\> $?
True
```
------
También puede utilizar un comando de lista de directorios para comprobar que el comando de cifrado ha creado un archivo nuevo, `hello.txt.encrypted`. Como el comando encrypt no especificó un nombre de archivo para el resultado, la CLI de AWS cifrado escribió el resultado en un archivo con el mismo nombre que el archivo de entrada más un `.encrypted` sufijo. Si desea utilizar un sufijo diferente o suprimir el sufijo, utilice el parámetro `--suffix`.
El archivo `hello.txt.encrypted` contiene un [mensaje cifrado](concepts.md#message) que incluye el texto cifrado del archivo `hello.txt`, una copia cifrada de la clave de datos y metadatos adicionales, incluido el contexto de cifrado.
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
```
------
## Descifrado de un archivo
En este ejemplo, se utiliza la CLI de AWS cifrado para descifrar el contenido del `Hello.txt.encrypted` archivo que se cifró en el ejemplo anterior.
El comando de descifrado utiliza el parámetro `--decrypt` para indicar la operación y el parámetro `--input` para identificar el archivo que se ha de descifrar. El valor del parámetro `--output` es un punto que representa el directorio actual.
El parámetro `--wrapping-keys` con un atributo **key** especifica la clave de encapsulamiento que se utiliza para descifrar el mensaje cifrado. En los comandos de descifrado con AWS KMS keys, el valor del atributo clave debe ser un [ARN clave.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) El parámetro `--wrapping-keys` es obligatorio en un comando de descifrado. Si usa AWS KMS keys, puede usar el atributo **key** para especificar AWS KMS keys para descifrar o el atributo **discovery** con un valor de `true` (pero no ambos). Si utiliza un proveedor de claves maestras personalizado, los atributos **key** y **provider** son obligatorios.
El [parámetro `--commitment-policy`](crypto-cli-reference.md#syntax-commitment-policy) es opcional a partir de la versión 2.1.*x*, pero se recomienda. Su uso explícito deja clara su intención, incluso si especifica el valor predeterminado, `require-encrypt-require-decrypt`.
El parámetro `--encryption-context` es opcional en el comando de descifrado, incluso cuando se proporciona un [contexto de cifrado](crypto-cli-how-to.md#crypto-cli-encryption-context) en el comando de cifrado. En este caso, el comando de descifrado utiliza el mismo contexto de cifrado que se proporcionó en el comando de cifrado. Antes de descifrar, la CLI de AWS cifrado verifica que el contexto de cifrado del mensaje cifrado incluya un `purpose=test` par. En caso contrario, el comando de descifrado genera un error.
El parámetro `--metadata-output` especifica un archivo para los metadatos relativos a la operación de descifrado. El valor del parámetro `--output`, un punto (.), escribe el archivo de salida en el directorio actual.
Como práctica recomendada, utilice el parámetro `--max-encrypted-data-keys` para evitar descifrar un mensaje mal formado con un número excesivo de claves de datos cifradas. Especifique el número esperado de claves de datos cifrados (una por cada clave de encapsulamiento utilizada en el cifrado) o un máximo razonable (por ejemplo, 5). Para obtener más información, consulte [Limitar las claves de datos cifrados](configure.md#config-limit-keys).
El `--buffer` devuelve el texto no cifrado solo después de procesar todas las entradas, incluida la verificación de la firma digital, si existe alguna.
------
#### [ Bash ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy require-encrypt-require-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output .
```
------
#### [ PowerShell ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input Hello.txt.encrypted `
--wrapping-keys key=$keyArn `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output .
```
------
Cuando el comando de descifrado se ejecuta correctamente, no devuelve ningún resultado. Para determinar si el comando se ha ejecutado correctamente, obtenga el valor de la variable `$?`. También puede utilizar un comando de lista de directorios para comprobar que el comando de descifrado ha creado un archivo nuevo con el sufijo `.decrypted`. Para ver el contenido de texto no cifrado, utilice un comando para obtener el contenido del archivo (por ejemplo, `cat` o [Get-Content](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content)).
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted hello.txt.encrypted.decrypted
$ cat hello.txt.encrypted.decrypted
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 1:01 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
-a---- 9/17/2017 1:08 PM 11 Hello.txt.encrypted.decrypted
PS C:\> Get-Content Hello.txt.encrypted.decrypted
Hello World
```
------
## Cifrado de todos los archivos de un directorio
En este ejemplo, se utiliza la CLI de AWS cifrado para cifrar el contenido de todos los archivos de un directorio.
Cuando un comando afecta a varios archivos, la CLI de AWS cifrado procesa cada archivo de forma individual. Obtiene el contenido del archivo, obtiene una [clave de datos](concepts.md#DEK) única para el archivo a partir de la clave maestra, cifra el contenido del archivo con la clave de datos y escribe los resultados en un archivo nuevo en el directorio de salida. Por lo tanto, los archivos de salida se pueden descifrar de manera independiente.
Esta lista del directorio `TestDir` muestra los archivos de texto no cifrado que deseamos cifrar.
------
#### [ Bash ]
```
$ ls testdir
cool-new-thing.py hello.txt employees.csv
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestDir
Directory: C:\TestDir
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/12/2017 3:11 PM 2139 cool-new-thing.py
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:44 PM 46 Employees.csv
```
------
El primer comando guarda el [nombre de recurso de Amazon (ARN)](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn) de an AWS KMS key en la `$keyArn` variable.
El segundo comando cifra el contenido de los archivos en el directorio `TestDir` y escribe los archivos con el contenido cifrado en el directorio `TestEnc`. Si el directorio `TestEnc` no existe, el comando genera un error. Dado que la ubicación de entrada es un directorio, el parámetro `--recursive` es obligatorio.
El [parámetro `--wrapping-keys`](crypto-cli-how-to.md#crypto-cli-master-key) y su atributo **key** obligatorio especifican la clave de encapsulamiento para utilizar. El comando de cifrado incluye un [contexto de cifrado](crypto-cli-how-to.md#crypto-cli-encryption-context), `dept=IT`. Cuando especifique un contexto de cifrado en un comando que cifre varios archivos, se utilizará el mismo contexto de cifrado para todos ellos.
El comando también tiene un `--metadata-output` parámetro para indicar a la CLI de AWS cifrado dónde escribir los metadatos sobre las operaciones de cifrado. La CLI de AWS cifrado escribe un registro de metadatos para cada archivo que se cifró.
El [`--commitment-policy parameter`](crypto-cli-how-to.md#crypto-cli-commitment-policy) es opcional a partir de la versión 2.1.*x*, pero se recomienda. Si el comando o el script fallan porque no pueden descifrar un texto cifrado, la configuración explícita de la política de compromiso puede ayudarle a detectar el problema rápidamente.
Cuando se completa el comando, la CLI de AWS cifrado escribe los archivos cifrados en el `TestEnc` directorio, pero no devuelve ningún resultado.
El último comando muestra los archivos en el directorio `TestEnc`. Hay un archivo de salida de contenido cifrado por cada archivo de entrada de contenido de texto no cifrado. Dado que el comando no ha especificado un sufijo alternativo, el comando de cifrado ha agregado `.encrypted` al nombre de cada archivo de entrada.
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input testdir --recursive\
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--output testenc
$ ls testenc
cool-new-thing.py.encrypted employees.csv.encrypted hello.txt.encrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
PS C:\> aws-encryption-cli --encrypt `
--input .\TestDir --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output .\Metadata\Metadata.txt `
--output .\TestEnc
PS C:\> dir .\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
## Descifrado de todos los archivos de un directorio
Este ejemplo descifra todos los archivos de un directorio. Comienza por los archivos del directorio `TestEnc` que se han cifrado en el ejemplo anterior.
------
#### [ Bash ]
```
$ ls testenc
cool-new-thing.py.encrypted hello.txt.encrypted employees.csv.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
Este comando de descifrado descifra todos los archivos del TestEnc directorio y escribe los archivos de texto sin formato en el directorio. TestDec El `--wrapping-keys` parámetro con un atributo **clave** y un valor de [ARN clave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) indica a la AWS CLI de cifrado qué se debe utilizar AWS KMS keys para descifrar los archivos. El comando usa el `--interactive` parámetro para indicar a la CLI de AWS cifrado que le pregunte antes de sobrescribir un archivo con el mismo nombre.
Este comando también utiliza el contexto de cifrado que se proporcionó al cifrar los archivos. Al descifrar varios archivos, la CLI de AWS cifrado comprueba el contexto de cifrado de cada archivo. Si se produce un error en la comprobación del contexto de AWS cifrado de algún archivo, la CLI de cifrado rechaza el archivo, escribe una advertencia, registra el error en los metadatos y, a continuación, continúa comprobando los archivos restantes. Si la CLI de AWS cifrado no puede descifrar un archivo por cualquier otro motivo, el comando de descifrado completo fallará inmediatamente.
En este ejemplo, los mensajes cifrados de todos los archivos de entrada contienen el elemento de contexto de cifrado `dept=IT`. Sin embargo, si va a descifrar mensajes con diferentes contextos de cifrado, puede verificar parte del contexto de cifrado. Por ejemplo, si algunos mensajes tuviesen el contexto de cifrado `dept=finance` y otros tuviesen `dept=IT`, podría verificar que el contexto de cifrado siempre contiene el nombre `dept`, sin especificar su valor. Si desea mayor precisión, podría descifrar los archivos mediante comandos independientes.
El comando de descifrado no devuelve ningún resultado, pero puede utilizar un comando de lista de directorios para comprobar que ha creado nuevos archivos con el sufijo `.decrypted`. Para ver el contenido de texto no cifrado, utilice un comando para obtener el contenido del archivo.
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input testenc --recursive \
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output testdec --interactive
$ ls testdec
cool-new-thing.py.encrypted.decrypted hello.txt.encrypted.decrypted employees.csv.encrypted.decrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input C:\TestEnc --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output C:\TestDec --interactive
PS C:\> dir .\TestDec
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 10/8/2017 4:57 PM 2139 cool-new-thing.py.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 46 Employees.csv.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 11 Hello.txt.encrypted.decrypted
```
------
## Cifrado y descifrado en la línea de comandos
Estos ejemplos muestran cómo canalizar la entrada a los comandos (stdin) y escribir el resultado en la línea de comandos (stdout). Explican cómo representar stdin y stdout en un comando y cómo utilizar las herramientas de codificación Base64 integradas para evitar que el shell interprete incorrectamente los caracteres no ASCII.
En este ejemplo se canaliza una cadena de texto no cifrado a un comando de cifrado y se guarda el mensaje cifrado en una variable. A continuación, se canaliza el mensaje cifrado de la variable a un comando de descifrado que escribe su resultado en la canalización (stdout).
El ejemplo se compone de tres comandos:
+ El primer comando guarda la [clave ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) de an AWS KMS key en la `$keyArn` variable.
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
```
------
+ El segundo comando envía la cadena `Hello World` al comando de cifrado y guarda el resultado en la variable `$encrypted`.
Los parámetros `--input` y `--output` son obligatorios en todos los comandos de la CLI de cifrado de AWS . Para indicar que la entrada se va a canalizar al comando (stdin), utilice un guion (`-`) para el valor del parámetro `--input`. Para enviar el resultado a la línea de comandos (stdout), utilice un guion para el valor del parámetro `--output`.
El parámetro `--encode` codifica en Base64 el resultado antes de devolverlo. Esto impide que el shell interprete incorrectamente los caracteres no ASCII del mensaje cifrado.
Dado que este comando es una mera prueba de concepto, omitimos el contexto de cifrado y suprimimos los metadatos (`-S`).
------
#### [ Bash ]
```
$ encrypted=$(echo 'Hello World' | aws-encryption-cli --encrypt -S \
--input - --output - --encode \
--wrapping-keys key=$keyArn )
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted = 'Hello World' | aws-encryption-cli --encrypt -S `
--input - --output - --encode `
--wrapping-keys key=$keyArn
```
------
+ El tercer comando canaliza el mensaje cifrado de la variable `$encrypted` al comando de descifrado.
Este comando de descifrado utiliza `--input -` para indicar que la entrada procede de la canalización (stdin) y `--output -` para enviar el resultado a la canalización (stdout). (El parámetro de entrada toma la ubicación de la entrada, no los bytes de entrada reales, por lo que no puede utilizar la variable `$encrypted` como valor del parámetro `--input`.)
En este ejemplo, se utiliza el atributo de **descubrimiento** del `--wrapping-keys` parámetro para permitir que la CLI de AWS cifrado lo utilice AWS KMS key para descifrar los datos. No especifica una [política de compromiso](concepts.md#commitment-policy), por lo que utiliza el valor predeterminado para las versiones 2.1.*x* y posteriores, `require-encrypt-require-decrypt`.
Debido a que el resultado se ha cifrado y, a continuación, codificado, el comando de descifrado utiliza el parámetro `--decode` para descodificar entrada codificada en Base64 antes de descifrarlo. También puede utilizar el parámetro `--decode` para descodificar la entrada codificada en Base64 antes de cifrarla.
También en este caso, el comando omite el contexto de cifrado y elimina los metadatos (-`S`).
------
#### [ Bash ]
```
$ echo $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode --buffer -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode --buffer -S
Hello World
```
------
También puede realizar las operaciones de cifrado y descifrado en un solo comando sin que intervenga la variable.
Como en el ejemplo anterior, los parámetros `--input` y `--output` tienen un valor `-`; el comando usa el parámetro `--encode` para codificar el resultado y el parámetro `--decode` para descodificar la entrada.
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ echo 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode -S
Hello World
```
------
## Uso de varias claves maestras
En este ejemplo, se muestra cómo utilizar varias claves maestras al cifrar y descifrar datos en la AWS CLI de cifrado.
Cuando se utilizan varias claves maestras para cifrar los datos, cualquiera de ellas se puede utilizar para descifrarlos. Esta estrategia garantiza que se puedan descifrar los datos, aunque una de las claves maestras no esté disponible. Si va a almacenar los datos cifrados en varios Regiones de AWS, esta estrategia le permite utilizar una clave maestra en la misma región para descifrar los datos.
Cuando se realiza el cifrado con varias claves maestras, la primera de ellas desempeña una función especial. Genera la clave de datos que se utiliza para cifrar los datos. Las demás claves maestras cifran la clave de datos en texto no cifrado. El [mensaje cifrado](concepts.md#message) resultante incluye los datos cifrados y una colección de claves de datos cifradas, una por cada clave maestra. Aunque la primera clave maestra fue la que generó la clave de datos, cualquiera de ellas puede descifrar una de las claves de datos con el fin de utilizarla para descifrar los datos.
**Cifrado con tres claves maestras**
El comando de este ejemplo utiliza tres claves maestras para cifrar el archivo `Finance.log`, una en cada una de las tres Regiones de AWS.
Escribe el mensaje cifrado en el directorio `Archive`. El comando utiliza el parámetro `--suffix` sin ningún valor para suprimir el sufijo, de tal forma que los nombres de los archivos de entrada y salida sean iguales.
El comando utiliza el parámetro `--wrapping-keys` con tres atributos **key**. También puede utilizar varios parámetros `--wrapping-keys` en el mismo comando.
Para cifrar el archivo de registro, la CLI de AWS cifrado solicita a la primera clave de empaquetado de la lista`$key1`,, que genere la clave de datos que utiliza para cifrar los datos. A continuación, utiliza cada una de las demás claves de encapsulamiento para cifrar una copia en texto no cifrado de la misma clave de datos. El mensaje cifrado del archivo de salida incluye las tres claves de datos cifradas.
------
#### [ Bash ]
```
$ key1=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ key2=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
$ key3=arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
$ aws-encryption-cli --encrypt --input /logs/finance.log \
--output /archive --suffix \
--encryption-context class=log \
--metadata-output ~/metadata \
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
#### [ PowerShell ]
```
PS C:\> $key1 = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> $key2 = 'arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef'
PS C:\> $key3 = 'arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d'
PS C:\> aws-encryption-cli --encrypt --input D:\Logs\Finance.log `
--output D:\Archive --suffix `
--encryption-context class=log `
--metadata-output $home\Metadata.txt `
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
Este comando descifra la copia cifrada del archivo `Finance.log` y la escribe en un archivo `Finance.log.clear` del directorio `Finance`. Para descifrar los datos cifrados en tres AWS KMS keys, puede especificar las mismas tres AWS KMS keys o cualquier subconjunto de ellas. En este ejemplo se especifica solo uno de los AWS KMS keys.
Para indicar a la CLI de AWS cifrado qué AWS KMS keys debe utilizar para descifrar los datos, utilice el atributo **clave** del `--wrapping-keys` parámetro. Al descifrar con AWS KMS keys, el valor del atributo **clave** debe ser un [ARN clave.](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)
Debe tener permiso para llamar a la [API de descifrado](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) en el AWS KMS keys lugar que especifique. Para obtener más información, consulte [ Autenticación y control de acceso de AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html).
Como práctica recomendada, en este ejemplo se utiliza el parámetro `--max-encrypted-data-keys` para evitar descifrar un mensaje mal formado con un número excesivo de claves de datos cifradas. Aunque en este ejemplo se utiliza solo una clave de encapsulamiento para el descifrado, el mensaje cifrado tiene tres (3) claves de datos cifrados, una para cada una de las tres claves de encapsulamiento utilizadas al cifrar. Especifique el número esperado de claves de datos cifrados o un valor máximo razonable, como 5. Si especifica un valor máximo inferior a 3, se produce un error en el comando. Para obtener más información, consulte [Limitar las claves de datos cifrados](configure.md#config-limit-keys).
------
#### [ Bash ]
```
$ aws-encryption-cli --decrypt --input /archive/finance.log \
--wrapping-keys key=$key1 \
--output /finance --suffix '.clear' \
--metadata-output ~/metadata \
--max-encrypted-data-keys 3 \
--buffer \
--encryption-context class=log
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli --decrypt `
--input D:\Archive\Finance.log `
--wrapping-keys key=$key1 `
--output D:\Finance --suffix '.clear' `
--metadata-output .\Metadata\Metadata.txt `
--max-encrypted-data-keys 3 `
--buffer `
--encryption-context class=log
```
------
## Cifrado y descifrado en scripts
En este ejemplo, se muestra cómo utilizar la CLI de AWS cifrado en los scripts. Puede escribir scripts que se limiten a cifrar y descifrar datos o scripts que cifren o descifren los datos dentro de un proceso de administración de datos.
En este ejemplo, el script obtiene una colección de archivos de registro, los comprime, los cifra y, una vez cifrados, los copia en un bucket de Amazon S3. Este script procesa cada archivo por separado, de forma que podrá descifrarlos y expandirlos por separado.
Cuando comprima y cifre archivos, asegúrese de comprimirlos antes de cifrarlos. Los datos cifrados correctamente no se pueden comprimir.
**aviso**
Tenga cuidado al comprimir datos que incluyan secretos e información confidencial que algún tercero malintencionado podría tratar de controlar. El tamaño final de los datos comprimidos podría, sin pretenderlo, revelar información confidencial sobre su contenido.
------
#### [ Bash ]
```
# Continue running even if an operation fails.
set +e
dir=$1
encryptionContext=$2
s3bucket=$3
s3folder=$4
masterKeyProvider="aws-kms"
metadataOutput="/tmp/metadata-$(date +%s)"
compress(){
gzip -qf $1
}
encrypt(){
# -e encrypt
# -i input
# -o output
# --metadata-output unique file for metadata
# -m masterKey read from environment variable
# -c encryption context read from the second argument.
# -v be verbose
aws-encryption-cli -e -i ${1} -o $(dirname ${1}) --metadata-output ${metadataOutput} -m key="${masterKey}" provider="${masterKeyProvider}" -c "${encryptionContext}" -v
}
s3put (){
# copy file argument 1 to s3 location passed into the script.
aws s3 cp ${1} ${s3bucket}/${s3folder}
}
# Validate all required arguments are present.
if [ "${dir}" ] && [ "${encryptionContext}" ] && [ "${s3bucket}" ] && [ "${s3folder}" ] && [ "${masterKey}" ]; then
# Is $dir a valid directory?
test -d "${dir}"
if [ $? -ne 0 ]; then
echo "Input is not a directory; exiting"
exit 1
fi
# Iterate over all the files in the directory, except *gz and *encrypted (in case of a re-run).
for f in $(find ${dir} -type f \( -name "*" ! -name \*.gz ! -name \*encrypted \) ); do
echo "Working on $f"
compress ${f}
encrypt ${f}.gz
rm -f ${f}.gz
s3put ${f}.gz.encrypted
done;
else
echo "Arguments: "
echo " and ENV var \$masterKey must be set"
exit 255
fi
```
------
#### [ PowerShell ]
```
#Requires -Modules AWSPowerShell, Microsoft.PowerShell.Archive
Param
(
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String[]]
$FilePath,
[Parameter()]
[Switch]
$Recurse,
[Parameter(Mandatory=$true)]
[String]
$wrappingKeyID,
[Parameter()]
[String]
$masterKeyProvider = 'aws-kms',
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$ZipDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$EncryptDirectory,
[Parameter()]
[String]
$EncryptionContext,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$MetadataDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-S3Bucket -BucketName $_})]
[String]
$S3Bucket,
[Parameter()]
[String]
$S3BucketFolder
)
BEGIN {}
PROCESS {
if ($files = dir $FilePath -Recurse:$Recurse)
{
# Step 1: Compress
foreach ($file in $files)
{
$fileName = $file.Name
try
{
Microsoft.PowerShell.Archive\Compress-Archive -Path $file.FullName -DestinationPath $ZipDirectory\$filename.zip
}
catch
{
Write-Error "Zip failed on $file.FullName"
}
# Step 2: Encrypt
if (-not (Test-Path "$ZipDirectory\$filename.zip"))
{
Write-Error "Cannot find zipped file: $ZipDirectory\$filename.zip"
}
else
{
# 2>&1 captures command output
$err = (aws-encryption-cli -e -i "$ZipDirectory\$filename.zip" `
-o $EncryptDirectory `
-m key=$wrappingKeyID provider=$masterKeyProvider `
-c $EncryptionContext `
--metadata-output $MetadataDirectory `
-v) 2>&1
# Check error status
if ($? -eq $false)
{
# Write the error
$err
}
elseif (Test-Path "$EncryptDirectory\$fileName.zip.encrypted")
{
# Step 3: Write to S3 bucket
if ($S3BucketFolder)
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted" -Key "$S3BucketFolder/$fileName.zip.encrypted"
}
else
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted"
}
}
}
}
}
}
```
------
## Uso del almacenamiento en caché de claves de datos
En este ejemplo, se utiliza el [almacenamiento en caché de claves de datos](data-key-caching.md) en un comando que cifra gran cantidad de archivos.
De forma predeterminada, la CLI de AWS cifrado (y otras versiones de AWS Encryption SDK) generan una clave de datos única para cada archivo que cifra. Aunque el uso de una clave de datos única para cada operación es una práctica criptográfica recomendada, una reutilización limitada de las claves de datos es aceptable en algunas situaciones. Si está estudiando la posibilidad de utilizar el almacenamiento en caché de claves de datos, consulte a un ingeniero de seguridad para conocer los requisitos de seguridad de la aplicación y determinar los umbrales de seguridad que sean adecuados para su caso.
En este ejemplo, el almacenamiento en caché de claves de datos acelera la operación de cifrado porque reduce la frecuencia de las solicitudes al proveedor de claves maestras.
El comando de este ejemplo cifra un gran directorio con varios subdirectorios que contienen un total aproximado de 800 archivos de registro de pequeño tamaño. El primer comando guarda el ARN de la AWS KMS key en una variable `keyARN`. El segundo comando cifra todos los archivos del directorio de entrada (de forma recursiva) y los escribe en un directorio de archivo. El comando utiliza el parámetro `--suffix` para especificar el sufijo `.archive`.
El parámetro `--caching` permite el almacenamiento en caché de claves de datos. El atributo **capacity**, que limita el número de claves de datos de la caché, se establece en 1, ya que el procesamiento de archivos en serie nunca utiliza más de una clave de datos a la vez. El atributo **max\$1age**, que determina durante cuánto tiempo se puede utilizar la clave de datos almacenada en la memoria caché, se establece en 10 segundos.
El atributo opcional **max\$1messages\$1encrypted** se establece en 10 mensajes, de tal forma que la misma clave de datos nunca se utilice para cifrar más de 10 archivos. Limitar la cantidad de archivos cifrados mediante cada clave de datos reduce la cantidad de archivos que se verían afectadas en el caso poco probable de que se filtrase una clave de datos.
Para ejecutar este comando en los archivos de registro generados por el sistema operativo, es posible que necesite permisos de administrador (`sudo` en Linux; **Ejecutar como administrador** en Windows).
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input /var/log/httpd --recursive \
--output ~/archive --suffix .archive \
--wrapping-keys key=$keyArn \
--encryption-context class=log \
--suppress-metadata \
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
#### [ PowerShell ]
```
PS C:\> $keyARN = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
Para probar el efecto del almacenamiento en caché de las claves de datos, en este ejemplo se utiliza el cmdlet [Measure-Command](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/measure-command) in. PowerShell Cuando se ejecuta este ejemplo sin almacenar las claves de datos en caché, tarda unos 25 segundos en completarse. Este proceso genera una nueva clave de datos para cada archivo del directorio.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata }
Days : 0
Hours : 0
Minutes : 0
Seconds : 25
Milliseconds : 453
Ticks : 254531202
TotalDays : 0.000294596298611111
TotalHours : 0.00707031116666667
TotalMinutes : 0.42421867
TotalSeconds : 25.4531202
TotalMilliseconds : 25453.1202
```
El almacenamiento en caché de claves de datos agiliza el proceso, aunque se limite cada clave de datos para un máximo de 10 archivos. Ahora, el comando tarda menos de 12 segundos en completarse y reduce el número de llamadas al proveedor de claves maestras a 1/10 del valor original.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 11
Milliseconds : 813
Ticks : 118132640
TotalDays : 0.000136727592592593
TotalHours : 0.00328146222222222
TotalMinutes : 0.196887733333333
TotalSeconds : 11.813264
TotalMilliseconds : 11813.264
```
Si se elimina la restricción `max_messages_encrypted`, todos los archivos se cifrarán con la misma clave de datos. Este cambio aumenta el riesgo inherente a la reutilización de claves de datos sin aportar mucha más rapidez al proceso. Sin embargo, reduce a una sola el número de llamadas al proveedor de claves maestras.
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 10
Milliseconds : 252
Ticks : 102523367
TotalDays : 0.000118661304398148
TotalHours : 0.00284787130555556
TotalMinutes : 0.170872278333333
TotalSeconds : 10.2523367
TotalMilliseconds : 10252.3367
```
# AWS Encryption SDK Referencia de parámetros y sintaxis de CLI
En este tema se proporcionan diagramas de sintaxis y descripciones breves de los parámetros para ayudarlo a usar la interfaz de línea de comandos (CLI) del AWS Encryption SDK . Para obtener ayuda con las claves de encapsulamiento y otros parámetros, consulte [Cómo utilizar la CLI AWS de cifrado](crypto-cli-how-to.md). Para ver ejemplos, consulte [Ejemplos de la CLI AWS de cifrado](crypto-cli-examples.md). Para ver la documentación completa, consulte [Leer los documentos](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/).
**Topics**
+ [
## AWS Sintaxis de CLI de cifrado
](#crypto-cli-syntax)
+ [
## AWS Parámetros de línea de comandos de la CLI de cifrado
](#crypto-cli-parameters)
+ [
## Parámetros avanzados
](#cli-advanced-parameters)
## AWS Sintaxis de CLI de cifrado
Estos diagramas de sintaxis de la CLI de AWS cifrado muestran la sintaxis de cada tarea que se realiza con la CLI de AWS cifrado. Representan la sintaxis recomendada en la versión 2.1 de la CLI de AWS cifrado. *x* y versiones posteriores.
Las nuevas funciones de seguridad se publicaron originalmente en las versiones 1.7 de AWS Encryption CLI. *x* y 2.0. *x*. Sin embargo, AWS Encryption CLI versión 1.8. *x* reemplaza a la versión 1.7. *x* y CLI de AWS cifrado 2.1. *x* reemplaza a 2.0. *x*. Para obtener más información, consulte el [aviso de seguridad](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r) correspondiente en el [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)repositorio de GitHub.
**nota**
A menos que se indique lo contrario en la descripción del parámetro, cada parámetro o atributo solo se puede usar una vez en cada comando.
Si utiliza un atributo que un parámetro no admite, la CLI de AWS cifrado ignora ese atributo no admitido sin que aparezca ninguna advertencia o error.
**Obtención de ayuda**
Para obtener la sintaxis CLI de AWS cifrado completa con descripciones de parámetros, utilice `--help` o`-h`.
```
aws-encryption-cli (--help | -h)
```
**Obtención de la versión**
Para obtener el número de versión de la instalación de la CLI de AWS cifrado, utilice`--version`. Asegúrese de incluir la versión cuando haga preguntas, informe de problemas o comparta consejos sobre el uso de la CLI de AWS cifrado.
```
aws-encryption-cli --version
```
**Cifrar datos**
En el siguiente diagrama de sintaxis se muestran los parámetros que se utilizan en un comando de cifrado **encrypt**.
```
aws-encryption-cli --encrypt
--input [--recursive] [--decode]
--output